Clanforge API
Note: The content on this page pertains to Clanforge. If you’re using Multiplay Hosting, refer to the Multiplay Hosting documentation.
There are two primary methods for updating your game image binary (build): through the Clanforge web interface, or through the Clanforge API. This topic details the process for updating through the Clanforge API.
Prerequisites
- You have completed the Clanforge Integrations Process.
- You have received your Service Identifiers from the Integrations Team.
- You have an updated game image that you’re ready to deploy to your fleet.
- You have your service identifier document.
These instructions assume that you have a new game build ready in Steam, and have an S3 bucket or a Google Cloud bucket. If you have opted to have the Clanforge support team manually install your game build to your jump machine, you can skip Create an image update on your build machine.
Process overview
The process for updating your game image through the Clanforge API includes the following steps:
- Create an image update on your build machine.
- Create a difference analysis from the update.
- Create a new image version from the difference analysis results.
Unity recommends that you test your game image on your build machine before proceeding from step one to step two.
 |
Step 1: Create an image update on your build machine
Use the Image Update Create endpoint to deploy an updated game image to your build machine. You have the option to use Steam, Google Cloud, or AWS. If you don’t have a cloud bucket or Steam account configured with your game image, contact the Multiplayer Support Team.
It's recommended that you test the updated game image on your build machine before continuing to the next step of this process. This ensures that you’ll identify any issues before deploying the updated game image to the rest of your infrastructure.
Step 2: Create a difference analysis from the update
Use the Image Diff Create endpoint to create a difference analysis (also called a diff analysis) based on the updated game image on your build machine. When you have generated a diff analysis, you can check the status of the diff analysis creation job, reject the diff analysis, or create a new image version from the diff analysis.
Action | Endpoint | Explanation |
|---|---|---|
Check the diff analysis status | After you send the request to create the diff analysis, you can use the Image Diff Status endpoint to check the current status of the diff analysis job. | |
Reject the diff analysis | Reject the results of the diff analysis (using the diff's unique diff ID value) if it has any unexpected changes. After you reject the diff analysis, you can generate a new diff analysis. If you try to generate another diff analysis from the same game image before rejecting or accepting the outstanding diff analysis, you receive an error stating that the image is locked by the diff ID XXXX. | |
Retry the diff analysis | If the diff analysis failed, troubleshoot the failure, and then retry the diff analysis. | |
Create a new image version from the diff analysis | Creating a new image version from a diff analysis is the same as accepting the results of the diff analysis. |
Step 3: Create a new image version from the difference analysis
To accept the changes generated from the diff analysis, use the Image Version Create endpoint with the diff ID that the Image Diff Create request returned. The Image Version Create endpoint uses the diff analysis (as specified by the diff ID in the request body), packages the differences, and once complete triggers a rollout to your fleet.
After you’ve called the Image Version Create endpoint, you can call the Image Version Status endpoint to check the status of this packaging process. The following table describes the statuses (job states) of the Image Version Status endpoint.
Job State ID (jobstateid) | Description |
|---|---|
1 | Created (new job) |
2 | Pending (waiting to be queued) |
3 | Queued (waiting to be processed) |
4 | Running (processing) |
5 | Completed (successful and triggers the rollout process) |
6 | Failed (unsuccessful) |
Step 4: Monitor rollout progress to machines
Upon successful completion of the image version, the platform starts rolling out the image to machines. Use the Image Rollout Status to observe its progress.
While the rollout is in progress, profiles using this image can still be used for allocations. However, it is the recommended best practice to avoid using those profiles. The machine might not have received the update yet and the underlying files may be changed while in use, which can lead to unexpected behavior.
Instead, zero downtime patching is recommended to ensure build has been fully rolled out before use.