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 maintaining 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 switch 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 switch, you can check the switch status by calling the Fleet Profile Switch Status endpoint.

When the profile switch 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 through the CLI, 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 is 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.

Action

Endpoint

Explanation

Check the diff analysis status

Image Diff 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

Image Diff Reject

Reject the results of the diff analysis (using the diff’s unique diff ID value) if it contains any unexpected changes. After you reject the diff analysis, you can generate a new diff analysis. If you attempt to generate another diff analysis from the same game image before rejecting or accepting the outstanding diff analysis, you will receive an error stating that the image is locked by the diff ID XXXX.

Retry the diff analysis

Image Diff Retry

If the diff analysis failed, troubleshoot the failure, and then retry the diff analysis.

Create a new image version from the diff analysis

Image Version Create

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)

Description

1

Created (new job)

2

Pending (waiting to be queued)

3

Queued (waiting to be processed)

4

Running (in process)

5

Completed (successful)

6

Failed (unsuccessful)

Step 4. Switch your fleet profile

After the result of the Image Version Status endpoint confirms that the image version is ready, switch 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.

Reservation-based fleets
For reservation-based fleets, you must call the Fleet Profile Switch endpoint to switch to the updated game version. After the result of the Image Version Status endpoint confirms that the image version is ready, switch your Fleet Profile to the Profile that’s tied with the image version you updated with the Fleet Profile Switch endpoint. Check the status of the Fleet Profile Switch job with the Fleet Profile Switch Status endpoint. When the return body contains a success message, the process is complete. If you encounter any problems or error messages, contact the Multiplayer support team.