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:
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 container registry.
- 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}