Dependencies

• Cloud deployment - You need to have a Cloud Deployment to persist secrets.
• Have the Metaplay CLI installed - You need the Metaplay CLI tool to manage Kubernetes Secrets.
• Familiarity of Working with Runtime Options - You should be able to extend your game server's runtime options.

Key Concepts

• Secrets are objects that store confidential data, such as passwords or API keys, to be used in the game server. They help keep sensitive data separate from application code.

Overview

For security reasons, you should store Secrets outside of game server container images. The most secure place to store Secrets is in the cloud environment as "Kubernetes Secrets".

You can create Kubernetes Secrets using the Metaplay CLI, such that the Secrets' content can be later consumed by your game server regardless of whether it is running in cloud or locally.

Kubernetes Secrets

Kubernetes Secrets are namespace-specific, meaning that they can only be consumed by a game server that runs in the same Kubernetes namespace of your cloud environment. In practice, this keeps your secrets secure and prevents them from being exposed to other game servers running in the same cluster.

For example, your development and production environments are in separate namespaces, and you can create separate Secrets for each environment.

Create a Kubernetes Secret

You can use the Metaplay CLI to create Kubernetes Secrets in selected environments. A Kubernetes Secret can contain multiple named entries. This allows you to group several related values in a single Secret object. The name of the Secrets, however, 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

Managing Kubernetes Secrets

Besides creating Kubernetes Secrets, the Metaplay CLI also provides some utilities to list, delete and show Secrets.

$ metaplay secrets show my-environment user-some-credentials
$ metaplay secrets delete my-environment user-some-credentials
$ metaplay secrets list my-environment

💡 Note

To update a Secret, you must first delete the existing Secret and then create it again. We'll add an update command in the future.

Access a Kubernetes Secret

To access a specific Kubernetes 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 Kubernetes Secret.
  # 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.

[RuntimeOptions("MySecret", isStatic: false, "")]
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; } = null;

    // This is the resolved value for the password. The attributes prevent 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 Kubernetes Secret.
        ResolvedPassword = await SecretUtil.ResolveSecretAsync(Log, PasswordSecretPath).ConfigureAwait(false);
    }
}

Running the Game Server with Cloud Secrets

When testing a specific feature, it's useful to be able to access the cloud environment's Secrets in your local development setup.

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
export KUBECONFIG="/path/to/my-environment.yaml"

// Windows
$env:KUBECONFIG="c:/path/to/my-environment.yaml"

The game server will automatically detect that it has a valid configuration and load the Secrets from that environment instead.

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)

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