Dependencies

• Signing up to the Metaplay Portal - To be able to deploy a game server to the Metaplay Cloud, you need to set up an organization, project, and environment for a game in the Metaplay Portal. Your user also needs the game-admin role for the environment.
• Having the required tools installed on your system - To follow the steps provided you need: AWS CLI, Docker, Helm, and jq.

Overview

This guide provides step-by-step instructions for manually building and deploying your game server into a Metaplay-managed environment.

Instead of manually building and deploying the server, you should consider setting up a CI to do this task automatically. See the Setup CI to Deploy a Game Server to the Metaplay-Managed Cloud guide for instructions.

Installing the metaplay-auth Command Line Tool

We provide a command line tool to help you obtain the required credentials as well as to easily fetch relevant details required for building, pushing, and deploying a game server to the cloud.

Installing from NPM

We provide metaplay-auth as an NPM package under the @metaplay organization. You can install the package globally with:

npm install -g @metaplay/metaplay-auth

Alternatively, if you just want to run commands with the latest metaplay-auth version, you can leverage npx:

npx @metaplay/metaplay-auth@latest -V

Using the metaplay-auth Tool

The metaplay-auth tool serves a couple of different, important functions:

1. It allows you to log into your Metaplay account and obtain associated tokens for interacting with different Metaplay APIs.
2. It allows you to obtain ephemeral Kubernetes and AWS credentials for your game server environments, which are needed for pushing images and deploying game servers.
3. It provides easy access to the details of your environments, which you'll need for pushing images.

To use the tool, you should first log in:

metaplay-auth login

This will pop up a browser and allow you to log in using your Metaplay identity. The tokens and the session are by default valid for an hour, after which you'll need to log in again to obtain fresh tokens. If you want to end your session earlier, you can invoke the logout command, which will remove your tokens. Otherwise, the tokens automatically expire after the validity period.

Once logged in, you can obtain information about an environment using the get-environment command. You can either provide the fully qualified name of the game server (for example, idler-develop.p1.metaplay.io) or, alternatively, a set of organization, project, and environment parameters:

metaplay-auth get-environment idler-develop.p1.metaplay.io

The output will be a JSON object that contains details about the infrastructure and environment where the game server can be provisioned.

Finally, you can use metaplay-auth to generate ephemeral credentials for both AWS and Kubernetes. These are needed for actions such as being able to push the game server container image to AWS as well as to deploy a game server onto the Kubernetes cluster. These can be handled with the get-aws-credentials and get-kubeconfig, respectively:

metaplay-auth get-aws-credentials idler-develop.p1.metaplay.io
metaplay-auth get-kubeconfig idler-develop.p1.metaplay.io

Building and Pushing the Server Container Image

Create a unique docker image tag for this particular build. You must use unique tags for each build! The current timestamp is used here, but in a CI job, you should use the git commit hash or similar instead.

export IMAGE_TAG=$(date +%s)

Next, build the docker image (more information about builds can be found in Deploying a Game Server):

docker build --platform linux/amd64 -f MetaplaySDK/Dockerfile.server -t gameserver:$IMAGE_TAG .

Next, login to Metaplay cloud with your developer portal account:

metaplay-auth login

Then, get credentials to the docker repository. The get-docker-login --format env outputs the environment variables DOCKER_REPO, DOCKER_USERNAME, and DOCKER_PASSWORD to use for logging in to the docker repository.

eval $(metaplay-auth get-docker-login idler-develop.p1.metaplay.io --format env)
echo $DOCKER_PASSWORD | docker login --username $DOCKER_USERNAME --password-stdin $DOCKER_REPO

Finally, tag your local game server image and push it to the remote docker repository:

docker tag gameserver:$IMAGE_TAG $DOCKER_REPO:$IMAGE_TAG
docker push $DOCKER_REPO:$IMAGE_TAG

Deploying a Game Server

After building and pushing the game server container image, you'll be ready to deploy the server. This is done in the same way as the standalone infrastructure stacks, but you can use the metaplay-auth tool to obtain the Kubernetes credentials and use a minimal set of Helm values to get the game server deployed.

First, obtain a kubeconfig to access the Kubernetes cluster and to be able to deploy the game server:

metaplay-auth login # unless you have already done this and have valid tokens
export KUBECONFIG=$(pwd)/kubeconfig.yaml
metaplay-auth get-kubeconfig idler-develop.p1.metaplay.io > $KUBECONFIG

Then, get the Kubernetes namespace for the deployment:

export KUBERNETES_NAMESPACE=$(metaplay-auth get-environment idler-develop.p1.metaplay.io | jq -r .deployment.kubernetes_namespace)

Then, deploy the game server using helm. You can use the metaplay-gameserver Helm chart available at https://charts.metaplay.dev/ and define the appropriate chart version (0.5.2 at the time of the writing). In this example, we'll name the deployment idler-develop, after the Idler sample.

INFO

Note: This step uses the pre-generated Helm values file for the deployment which is located in Backend/Deployments/develop-server.yaml. If your project does not contain this file, take a look at Release 27 Migration Guide for Managed Environments for instructions on how to add these configuration files into your project.

helm upgrade \
  --install \
  --kubeconfig kubeconfig.yaml \
  --repo https://charts.metaplay.dev/ \
  --version 0.5.2 \
  -f Backend/Deployments/develop-server.yaml \
  -n $KUBERNETES_NAMESPACE \
  --set-string image.tag=$IMAGE_TAG \
  idler-develop \
  metaplay-gameserver

The Helm deployment will output a set of details about the deployed game server, including the endpoint for the LiveOps Dashboard. You can attempt to log into it. Alternatively, you can log into the Metaplay Portal and navigate to the specific environment under your organization and project to get the same information.

Finally, you should validate that the game server deployed correctly:

metaplay-auth check-deployment $KUBERNETES_NAMESPACE

Tips and Tricks

The metaplay-auth command line tool is a fairly powerful tool, which you can chain together with other tools to provide identity and authentication services. This section contains some examples of how to do this.

metaplay-auth and aws

As a game server administrator, you may sometimes need to access various underlying AWS resources that the game server relies on. These can include things like the S3 object storage bucket to manage files that the game server might be interacting with, the Cloudfront content delivery network distribution when you want to invalidate certain cached objects, and so on.

The aws tool allows you to define profiles. The configuration structure of profiles is flexible and allows you to obtain the credentials from another external process, which can in this case be metaplay-auth, which produces ephemeral AWS credentials in a format that aws accepts.

In the aws config file (typically under ~/.aws/config), we could define a profile for the game server idler-develop following the prior example:

~/.aws/config

[profile idler-develop-admin]
credential_process = metaplay-auth get-aws-credentials --format json idler-develop.p1.metaplay.io

After this, we can ensure that we are logged in metaplay-auth login and just use the regular methods for setting a profile for the aws tool (e.g. --profile switches or AWS_PROFILE environment variable):

$ metaplay-auth login
$ aws sts get-caller-identity --profile idler-develop-admin
{
    "UserId": "AXXXXXXXXXXXXXXXXXXXX:stackapi",
    "Account": "000000000000",
    "Arn": "arn:aws:sts::000000000000:assumed-role/metaplay-p1-idler-develop-gameserver-admin/stackapi"
}

Further Reading

For a more detailed explanation of the build and deploy steps, or if you're deploying into a self-hosted environment, check out Deploying a Game Server. It's mostly the same process but the steps to acquire the credentials differ for self-hosted environments.