Metaplay Docs

Appearance

Persisting Secrets

This guide walks you through creating your first secret in a cloud environment and using it in your game server.

Dependencies ​

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. You can create two types of secrets for your cloud deployments:

  • Kubernetes Secret
  • AWS Secrets Manager secret

Kubernetes Secret ​

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). We highly recommend using Kubernetes Secrets which are more easy to manage.

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.

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.

bash
# 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

💡 Note

Secret names must begin with the user- prefix to ensure they do not clash with any built-in secret in the environment.

Managing Kubernetes Secrets ​

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

bash
$ 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 add it to your runtime options.

Options.<env>.yaml
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.

csharp
[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:

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

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

bash
// 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:

bash
$ 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:

bash
$ metaplay secrets list --help

AWS Secrets Manager secrets ​

INFO

AWS Secrets Manager secrets are intended for self-hosting stacks.

AWS Secrets Manager secrets is often used for sharing same secret values among multiple environments. This is an advanced use case, where consuming secrets require additional IAM policies if the consumer comes from other environments. Please use AWS Secrets Manager secrets only if Kubernetes Secret can not support your need.

Game servers and game server administrators can create AWS Secrets Manager secrets by using the AWS credentials obtained with the Metaplay CLI. An example of how to create, update, and delete AWS Secrets Manager secrets can be found below.

INFO

The path of an AWS Secrets Manager secret is in the format of metaplay/p1/deployments/<Environment ID>/*. For example, in the case of an Environment with an environment ID lovely-wombats-build-quickly, the path of the AWS Secrets Manager secret should be metaplay/p1/deployments/lovely-wombats-build-quickly/.

You can find the environment ID in the Metaplay Portal » Your Project » Environments » top-right corner of the environment info card.

bash
# We assume that you have set AWS credentials and a profile, as described above.
# And your Environment has been created before September 10, 2024.
metaplay get aws-credentials lovely-wombats-build-quickly

# Create a secret in the eu-west-1 region
aws secretsmanager create-secret \
    --profile lovely-wombats-build-quickly-admin \
    --region eu-west-1 \
    --name metaplay/p1/deployments/lovely-wombats-build-quickly/my-secret \
    --secret-string '{"my-secret": "my-value"}'

# Update a secret's value
aws secretsmanager update-secret \
    --profile lovely-wombats-build-quickly-admin \
    --region eu-west-1 \
    --secret-id metaplay/p1/deployments/lovely-wombats-build-quickly/my-secret \
    --secret-string 'THESECRETKEY'

# Delete a secret
aws secretsmanager delete-secret \
    --profile lovely-wombats-build-quickly-admin \
    --region eu-west-1 \
    --secret-id metaplay/p1/deployments/lovely-wombats-build-quickly/my-secret \
    --force-delete-without-recovery # you can enable this switch to immediately destroy the secret; otherwise, the secret will be deleted after a grace period, during which you cannot reuse the secret name

For more details on AWS Secrets Manager commands, please refer to the AWS CLI's Secrets Manager documentation.

The AWS Secrets Manager supports storing secrets in many formats, the most common being plain text and JSON.

After creating the secret, you can refer to it in the game server runtime options using the aws-sm:// prefix. For example, BigQuery credentials can be loaded from a secret in the following way in the runtime options:

yaml
AnalyticsSinkBigQuery:
    # file path to the credentials, or aws-sm:// url for credential from AWS Secrets
    # Manager
    BigQueryCredentialsJsonPath: aws-sm://eu-west-1#metaplay/p1/deployments/lovely-wombats-build-quickly/my-secret

Alternatively, you can also use the SecretUtil.ResolveSecretAsync API to resolve secrets.