Dependencies

• Cloud deployment - You need to have a cloud deployment to persist Secrets.
• Metaplay CLI installed - You need the Metaplay CLI tool to manage Secrets.
• Familiarity with Working with Runtime Options - You should understand how to declare your own Runtime Options.

Key Concepts

• Secrets store confidential data in a cloud environment, consumed by game servers running in that environment.

Overview

Secrets are the recommended way to provide sensitive values, such as API keys and passwords, to your game servers running in the cloud. You should use Secrets instead of environment variables, files, or embedding them in your container images.

Secrets are environment-specific, meaning that they can only be consumed by a game server that runs in the same cloud environment as the secret resides in. They are stored as Kubernetes secrets in the cloud environment.

Each Secret can contain multiple named entries, each with its own value. You can group several related values in a single Secret object.

Create a Secret

You can use the Metaplay CLI to create Secrets in selected environments.

The name of the Secret must begin with the user- prefix.

For this example, we'll use an imaginary service with the name user-some-credentials. The Secret will contain two named entries: username and password, each with its own value. For demonstration purposes, the username will be specified directly on the command line and the password will be sourced from a file.

# Here we're creating a secret named user-some-credentials on the my-environment environment with keys username and password
$ metaplay secrets create my-environment user-some-credentials --from-literal=username=myusername --from-file=password=password.txt

💡 Tip

Use the --overwrite flag to replace an existing secret. This is useful for scripting and CI/CD pipelines where you want to ensure a secret has specific values regardless of whether it already exists.

List, Update, and Delete Secrets

The Metaplay CLI also provides utilities to list, show, update, and delete Secrets.

$ metaplay secrets list my-environment
$ metaplay secrets show my-environment user-some-credentials
$ metaplay secrets update my-environment user-some-credentials --from-literal=password=newsecret --remove=oldkey
$ metaplay secrets delete my-environment user-some-credentials

For more information, run metaplay secrets --help.

Access a Secret

To access a specific Secret from your game server code, you'll need to reference it in your runtime options.

Options.<env>.yaml

MySecret:
  # The 'kube-secret://' prefix indicates that the value should be resolved from the cloud environment.
  # Note that you must refer to the secret with both the secret and key name, using the special syntax.
  PasswordSecretPath: "kube-secret://user-some-credentials#password"

This example only reads the password from the Secret, but you can read any other entry as well.

Then, you can resolve the password value in your game server code by creating a Runtime Options class that uses the OnLoadedAsync() hook to fetch the secret value.

[RuntimeOptions("MySecret", isStatic: false, "Configuration example for secret credentials.")]
public class MySecretOptions : RuntimeOptionsBase
{
    // PasswordSecretPath is the path to the password secret, defined in Options.yaml.
    [MetaDescription("The path to the password secret.")]
    public string PasswordSecretPath { get; private set; }

    // The resolved value for the password.
    // [IgnoreDataMember] excludes this from serialization (eg, API responses).
    // [Sensitive] prevents the value from being logged.
    [IgnoreDataMember, Sensitive]
    public string ResolvedPassword { get; private set; }

    public override async Task OnLoadedAsync()
    {
        // Resolve the value for the password from the cloud environment.
        if (!string.IsNullOrEmpty(PasswordSecretPath))
            ResolvedPassword = await SecretUtil.ResolveSecretAsync(Log, PasswordSecretPath);
    }
}

Note

The OnLoadedAsync() hook is called both when the server starts and during hot-loading of configuration changes. For more details, see Working with Runtime Options.

Accessing Cloud Secrets From Local Servers

When testing a specific feature, it's useful to be able to access the cloud environment's Secrets from your locally running game server.

You'll have to get the kubeconfig required to access the cloud environment. This is easily doable with the Metaplay CLI:

$ metaplay get kubeconfig my-environment > my-environment.yaml

Next, set the KUBECONFIG environment variable to the full path to the my-environment.yaml file.

# Unix/macOS
export KUBECONFIG="/path/to/my-environment.yaml"

# Windows PowerShell
$env:KUBECONFIG="C:\path\to\my-environment.yaml"

The game server automatically detects that it has access to the cloud environment and loads the Secrets from that environment.

Programmatic Use

The CLI supports showing the Secret in JSON format, which can be useful for programmatic use.

For example, you could use the following command to extract a value from a Secret into an environment variable:

$ PASSWORD=$(metaplay secrets show my-environment user-some-credentials --format=json | jq -r .data.password)

Supported Secret Sources

The SecretUtil.ResolveSecretAsync() method supports multiple secret sources, identified by their URL prefix:

Prefix	Description	Availability	Example
kube-secret://	Secrets in the cloud environment	Recommended	kube-secret://user-credentials#password
aws-sm://	AWS Secrets Manager	Self-hosted only	aws-sm://eu-north-1#my-secret-name
file://	Local file on disk	Not recommended	file:///path/to/secret.txt
unsafe://	Plaintext value	Testing only	unsafe://my-test-password

If no prefix is specified, the value is treated as a file path by default.

Caution

The unsafe:// prefix should only be used for local development and testing. Never use it in production environments as it exposes the secret value in plain text in your configuration files.

Further Reading

You can get more details about the available CLI Secret management commands with metaplay secrets --help, or for individual commands with metaplay secrets [command] --help. Here's an example with the list command:

$ metaplay secrets list --help