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 process.

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 with profile and game image version duplicates.

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:

1. Create an image update on your build machine.
2. Create a difference analysis from the update.
3. Create a new image version from the difference analysis results.
4. 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.

Zero downtime patching workflow.

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.

Check the status of the diff analysis with the Image Diff Status endpoint. If the diff analysis failed, you can retry the diff analysis with the Image Diff Retry 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.

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.

Step 4. Switch your fleet profile#

After the result of the Image Version Status endpoint confirms that the image version is complete, it begins rolling out. You can monitor the progress of rollouts to machine using the Image Rollout Status endpoint, which indicates when the rollout status.

You can then begin allocating servers with the Server Allocate endpoint on 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.