Zero downtime patching
Zero downtime patching is the process of updating a game image without taking any game servers offline, which allows you to update your game without subjecting your players to inactive servers.
You can implement zero downtime patching by keeping two versions of your game image. For example, one might be named Image A, and the other Image B. At any point, you’ll have one version live while you’re updating the other. When you’re ready to deploy the updated image version, you’ll change the live game version.
For allocations, this means that you make the allocation API call with the updated profile ID associated with the updated image. For example, if you start making allocations for profile A, you would then update Image B. When you’re done updating Image B, you would then begin making allocations by using profile B.
For reservations, you would explicitly change the fleet to the profile associated with the updated build by calling the Fleet Profile Switch API endpoint. After you’ve started the change, you can check the change status by calling the Fleet Profile Switch Status endpoint.
When the profile change is complete, Image B is live in production, and Build A is ready for the next update.
Zero downtime patching is possible because profiles and game versions are tightly coupled. In the scenario detailed in the preceding diagram, the Image A image version would have a profile named Image A, and the Image B image version would have a profile named Image B.
Zero downtime patching requirements
To use zero downtime patching, you must have a duplicate of each profile and game image version. For example, if you have a branch for production, development, and staging, you’ll have two profiles for production, two profiles for development, and two profiles for staging.
Zero downtime patching workflow
Excluding the prerequisites, the zero downtime patching workflow is similar to the process for updating an image, but with the addition of the Fleet Profile Switch step. The flow 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.
- Change your fleet profile to the profile associated with the game image version you updated.
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
After you have prepared the updated game image by uploading it to your Steam bucket, Google Cloud bucket, or AWS bucket, you’re ready to deploy the updated game image to your build machine. Deploy the updated game image to your build machine with the Image Update Create endpoint.
Check the status of the Image Update Create job with the Image Update Status endpoint. If the status returns a failed state, troubleshoot the cause of the failure, and then use the Image Update Retry endpoint to retry the update.
When the Image Update Status confirms that the update successfully completed, test the updated game image on your build machine. It's recommended that you test the updated game image on your build machine before continuing any further in 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
After you’ve confirmed that the updated game image works correctly on your build machine, create a difference analysis (also called a diff analysis) from the updated image with the Image Diff Create endpoint.
When the diff analysis successfully completes, you can reject the diff analysis with the Image Diff Reject endpoint or create a new image version from the diff analysis with the Image Version Create endpoint.
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 results
After you’ve accepted the diff analysis by calling the Image Version Create endpoint with the diff ID, you can check on the status of the Image Version Create job with the Image Version Status endpoint.
The following table describes the statuses (job states) of the Image Version Status endpoint.
Job State ID (jobstateid)
Created (new job)
Pending (waiting to be queued)
Queued (waiting to be processed)
Running (in process)
Step 4. Switch your fleet profile
After the result of the Image Version Status endpoint confirms that the image version is ready, change your start allocating servers with the Server Allocate endpoint with the Profile ID that’s associated with the updated game version. The response body should contain a success message and the Profile ID that you supplied in the request body.