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 the following steps:
- Prepare the container
- Get (or create) a build
- Tag the container image
- Push the image to the container registry
- Create a build version
- Wait 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:
Prepare the build container
Note: Building the game binary and building the container is out of scope for the Multiplay Hosting API.
- Build the container image (using an out-of-band process).
- Take note of your Unity project ID and environment ID.
- Log into the Multiplay Hosting container registry.
- Use your 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.
Get an existing build by name
You can retrieve an existing build ID by name using the List Builds API. Remember to 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 Hosting container registry. Use the following code snippet as a template:
docker push registry.multiplay.com/<ProjectID>/<EnvironmentID>/<BuildID>:<MultiplayTag>
Once you push a tag, you cannot use that tag again for the same build; Multiplay Hosting prevents pushing the same tag more than once for a build to ensure that the exact same container is pulled during scaling. Refer to Zero downtime releases for more information.
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