Container build workflow

Warning: This content is a preview of the documentation. The full documentation, along with code samples, is still in progress. Please provide feedback via the feedback mechanism at the bottom of this page.

The container build workflow includes preparing the container, getting (or creating) a build, creating a list of build files, iterating over the build files, creating a build version, and waiting for the build to sync.

Before using the container build workflow, you must have a CCD API key and a UGS service account with the following roles:

  • Multiplay API Viewer
  • Multiplayer API Editor
  • Multiplay Registry Editor

Note: Refer to Project roles and Service account authentication for more information.

Note: Throughout this workflow you need to refer to your Unity project ID and environment ID. You can find your project ID on the project settings page, and the environment ID on the environments page.

The following diagram shows a simplified version of the workflow:

container workflow diagram

Prepare the build container

Note: Building the game binary and building the container is out of scope for the Game Server Hosting (Multiplay) API.

  1. Build the container image (using an out-of-band process).
  2. Take note of your Unity project ID and environment ID.
  3. Log into the Multiplay container registry.
  4. Use you Key ID for the username and Secret Key for the password. Refer to Authentication.
docker login registry.multiplay.com -u <KeyID>

Get or create a build

The process for getting a build varies depending on whether you want to use an existing build or create a new build.

Note: A build ID and a CCD bucket ID are separate IDs with a one-to-one relationship. The bucket (identified by the bucket ID) stores the build files, and the build (identified by the build ID) wraps the files from the bucket with metadata.

Get an existing build by name

You can retrieve an existing build ID by name using the List Builds API.

The Build List API response body includes the CCD Bucket ID of each build in the ccd.bucketID field and the build ID in the buildID field for each build. Make note of the buildID of the build you want to use.

The following code sample shows how to get an existing build using curl:

curl -X GET -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" https://services.api.unity.com/multiplay/builds/v1/projects/{projectId}/environments/{environmentId}/builds

After finding the build you want to use, make a note of the buildID from the response body.

Create a new build

You can create a new build using the Create build API.

The following code sample shows how to create a build using curl:

curl -X POST -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" -H "Content-Type: application/json" \
    -d '{"buildName":"Dev Build A", "osFamily": "LINUX"}' \
    https://services.api.unity.com/multiplay/builds/v1/projects/{projectId}/environments/{environmentId}/builds

After creating the new build, make a note of the buildID from the response body.

Tag the container image

The first time you push to a new build, use v1 as the MultiplayTag. After the first push, use incremental tags (for example, v2).

Use the following code snippet as template for tagging the container (where ImageName and ImageTag are your local image name and tag).

docker tag <ImageName>:<ImageTag> registry.multiplay.com/<ProjectID>/<EnvironmentID>/<BuildID>:<MultiplayTag>

Push the image to the container registry

After tagging the container, push it to the Multiplay container registry. Use the following code snippet as a template:

docker push registry.multiplay.com/<ProjectID>/<EnvironmentID>/<BuildID>:<MultiplayTag>

Create a build version

You can create a build version with the Create a new build version API.

The following code sample shows how to create a build version using curl:

curl -X POST -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" -H "Content-Type: application/json" \
    -d '{"container": {"imageTag": "v1"}, "forceRollout": false}' \
    https://services.api.unity.com/multiplay/builds/v1/projects/{projectId}/environments/{environmentId}/builds/{buildId}/versions

Wait for the build to sync

You can determine when the build synchronization completes by retying the Get a single build API until the syncStatus field is SYNCED.

The following code sample shows how to wait for the build to sync using curl:

curl -X GET -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" https://services.api.unity.com/multiplay/builds/v1/projects/{projectId}/environments/{environmentId}/builds/{buildId}