Dependencies

• Have the Metaplay CLI installed - You need the Metaplay CLI tool to manage Kubernetes Secrets.

Key Concepts

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

Overview

Storing Secrets outside of game server container images is advisable from a security perspective. For enhanced security, we recommend to create Secrets in the cloud environment instead. You can create Kubernetes Secrets using the Metaplay CLI, where 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 the game server that runs in the same Kubernetes namespace (cloud 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 is useful for grouping several related values in a single Secret object. The name of Secrets however must begin with the user- prefix.

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, the CLI makes this easy for you:

$ 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