Creating or updating a rollout

This page explains how to create, update, and view details of a Game Servers rollout in a deployment. A rollout maps game server configs to target realms. To see an end-to-end example of how to create a deployment, add a config, and then roll it out, see Configuring cluster scaling behavior.

Figure 1. Config version 1.0 rolled out to the US realm, version 1.1 rolled out to the Europe and Japan realms

For more information, see the Game Servers overview.

Before you begin

Before you start, we recommend you familiarize yourself with key concepts in the Game Servers Overview. Make sure you have also performed the following tasks:

• Ensure that you have enabled the Game Services API.
Enable Game Services API
• Either choose a shell with gcloud CLI installed, or use an API client:

Cloud Shell

To launch Cloud Shell, perform the following steps:

1. Go to Google Cloud console.

   Google Cloud console

2. From the upper-right corner of the console, click the Activate Cloud Shell button:

A Cloud Shell session opens inside a frame lower on the console. You use this shell to run gcloud commands.

Local shell

Install the gcloud CLI.

Verify that you have set desired default project for Google Cloud CLI (otherwise you need to specify flag --project explicitly for each command later):

gcloud config list project

If not you can run the following command to set a default project, replacing PROJECT_ID with your desired project ID :

gcloud config set project PROJECT_ID

Run the following command to verify your version of the Google Cloud CLI. Game Servers requires version 306.0.0 or higher of the gcloud CLI.

gcloud version

To update your installation, run the following command:

gcloud components update

curl / PowerShell

To use the REST API with curl or Windows PowerShell, do the following:

1. Create a service account.
2. Download a private key as a JSON file.

3. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

Client Library

Google Cloud Game Servers can be controlled programmatically using a client library. See Client Libraries Overview for instructions on using the library and authenticating.

Updating a rollout

The process for updating a rollout is the same as creating a rollout. First, make sure you have created a Game Servers config. If you want to target specific realms with a different config, create a separate override config.

Updating a rollout's default config

The default game server config is rolled out to all realms. To target specific realms with a different config, see Overriding the config for certain realms.

Console

1. In the console, go to the Game Server Deployments page.

   Go to Game Servers

2. Find a deployment in the table. In the last table column, click the ellipses and select List configs. You can view the active and inactive configs for the deployment from this page.

3. Click Manage Rollout.

4. (Optional) In the Select a config list, choose a default config that applies to all realms.

5. Click Save.

gcloud

To update the default config of a Game Servers rollout using the Google Cloud CLI:

1. Run the following command after replacing the following placeholder values:

   • deploymentID is the unique identifier for the deployment.
   • configID is a unique identifier for the config.

   gcloud game servers deployments update-rollout deploymentID --default-config configID --dry-run
   

   The output returns the targetState so that you can preview the changes.

2. To apply the changes, run the following command:

   gcloud game servers deployments update-rollout deploymentID --default-config configID --no-dry-run
   

REST & CMD LINE

Before using any of the request data, make the following replacements:

• PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
• DEPLOYMENT_ID: a user-defined identifier for the deployment
• CONFIG_ID: a user-defined identifier for the configuration

Request JSON body:

{
  "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
  "defaultGameServerConfig": "CONFIG_ID"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
   Note: The following command will overwrite any existing request.json file in the current directory.

   cat > request.json << 'EOF'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
     "defaultGameServerConfig": "CONFIG_ID"
   }
   EOF

2. Execute the following command in the terminal. It references the request.json file you just created.

   curl -X PATCH \
   -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout?updateMask=defaultGameServerConfig"

PowerShell (Windows)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
   Note: The following command will overwrite any existing request.json file in the current directory.

   @'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
     "defaultGameServerConfig": "CONFIG_ID"
   }
   '@  | Out-File -FilePath request.json -Encoding utf8

2. Execute the following command in the terminal. It references the request.json file you just created.

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method PATCH `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout?updateMask=defaultGameServerConfig" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.gaming.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Clearing a rollout's default config

Clear the default config to remove the fleet config for this deployment from all Game Servers clusters.

Console

1. In the console, go to the Game Server Deployments page.

   Go to Game Servers

2. Find a deployment in the table. In the last table column, click the ellipses and select List configs. You can view the active and inactive configs for the deployment from this page.

3. Click Manage Rollout.

4. In the Select a config list, select (no default config).

5. Click Save.

gcloud

To clear the default config of a Game Servers rollout using the Google Cloud CLI:

1. Run the following command after replacing the following placeholder value:

   • deploymentID is the unique identifier for the deployment.

   gcloud game servers deployments update-rollout deploymentID --clear-default-config --dry-run
   

   The output returns the targetState so that you can preview the changes.

2. To apply the changes, run the following command:

   gcloud game servers deployments update-rollout deploymentID --clear-default-config --no-dry-run
   

REST & CMD LINE

Before using any of the request data, make the following replacements:

• PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
• DEPLOYMENT_ID: a user-defined identifier for the deployment

Request JSON body:

{
  "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
  "defaultGameServerConfig": ""
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
   Note: The following command will overwrite any existing request.json file in the current directory.

   cat > request.json << 'EOF'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
     "defaultGameServerConfig": ""
   }
   EOF

2. Execute the following command in the terminal. It references the request.json file you just created.

   curl -X PATCH \
   -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout?updateMask=defaultGameServerConfig"

PowerShell (Windows)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
   Note: The following command will overwrite any existing request.json file in the current directory.

   @'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
     "defaultGameServerConfig": ""
   }
   '@  | Out-File -FilePath request.json -Encoding utf8

2. Execute the following command in the terminal. It references the request.json file you just created.

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method PATCH `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout?updateMask=defaultGameServerConfig" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.gaming.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Overriding the config for certain realms

If you want to target specific realms with a different config, create a separate override config and then select one or more realms that will receive this override config (and not the default config).

Console

1. In the console, go to the Game Server Deployments page.

   Go to Game Servers

2. Find a deployment in the table. In the last table column, click the ellipses and select List configs. You can view the active and inactive configs for the deployment from this page.

3. Click Manage Rollout.

4. (Optional) In the Select a config list, choose a default config that applies to all realms that don't match an override config.

5. Under Override configs, you can specify one or more override configs and the realms to associate them with.

   1. Select an override config from the Config list and the realm to associate with it from the Realm list.
   2. Use the arrow buttons to change the priority ordering of the override configs in the list.
   3. Click Add.

6. Click Save.

gcloud

To apply config overrides to particular realms using the Google Cloud CLI:

1. Copy the following code into a file and replace the following placeholder values:

   • realmID is the fully-qualified identifier for a realm, such as projects/<projectID>/locations/<region>/realms/<realmID2>.
   • configID is a unique identifier for the config.

   - realmsSelector:
       realms:
           - realmID
     configVersion: configID
   

2. Run the following command after replacing the following placeholder values:

   • deploymentID is the unique identifier for the deployment.
   • configOverrideFile is the path to the file with the override config.

   gcloud game servers deployments update-rollout deploymentID --config-overrides-file configOverrideFile --dry-run
   

   The output returns the targetState so that you can preview the changes.

3. To apply the changes, run the following command:

   gcloud game servers deployments update-rollout deploymentID --config-overrides-file configOverrideFile  --no-dry-run
   

REST & CMD LINE

Before using any of the request data, make the following replacements:

• PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
• LOCATION: the region for the realm (or global)
• DEPLOYMENT_ID: a user-defined identifier for the deployment
• REALM_ID: the user-defined identifier for the realm
• OVERRIDE_CONFIG_ID: a user-defined identifier for the override configuration

Request JSON body:

{
  "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
  "gameServerConfigOverrides": [
  {
    "realmsSelector": {
      "realms": [
        "projects/PROJECT_ID/locations/LOCATION/realms/REALM_ID"
      ]
    },
    "configVersion": "OVERRIDE_CONFIG_ID"
  }
  ]
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
   Note: The following command will overwrite any existing request.json file in the current directory.

   cat > request.json << 'EOF'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
     "gameServerConfigOverrides": [
     {
       "realmsSelector": {
         "realms": [
           "projects/PROJECT_ID/locations/LOCATION/realms/REALM_ID"
         ]
       },
       "configVersion": "OVERRIDE_CONFIG_ID"
     }
     ]
   }
   EOF

2. Execute the following command in the terminal. It references the request.json file you just created.

   curl -X PATCH \
   -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout?updateMask=gameServerConfigOverrides"

PowerShell (Windows)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
   Note: The following command will overwrite any existing request.json file in the current directory.

   @'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
     "gameServerConfigOverrides": [
     {
       "realmsSelector": {
         "realms": [
           "projects/PROJECT_ID/locations/LOCATION/realms/REALM_ID"
         ]
       },
       "configVersion": "OVERRIDE_CONFIG_ID"
     }
     ]
   }
   '@  | Out-File -FilePath request.json -Encoding utf8

2. Execute the following command in the terminal. It references the request.json file you just created.

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method PATCH `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout?updateMask=gameServerConfigOverrides" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.gaming.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Clearing config overrides

Clear the override config to remove the fleet config for this deployment from the targeted realms.

Console

1. In the console, go to the Game Server Deployments page.

   Go to Game Servers

2. Find a deployment in the table. In the last table column, click the ellipses and select List configs. You can view the active and inactive configs for the deployment from this page.

3. Click Manage Rollout.

4. Under Override configs, click the trash can icon next to the override configs you want to clear.

5. Click Save.

gcloud

To clear the config overrides of a Game Servers rollout using the Google Cloud CLI:

1. Run the following command after replacing the following placeholder value:

   • deploymentID is the unique identifier for the deployment.

   gcloud game servers deployments update-rollout deploymentID --clear-config-overrides --dry-run
   

   The output returns the targetState so that you can preview the changes.

2. To apply the changes, run the following command:

   gcloud game servers deployments update-rollout deploymentID --clear-config-overrides --no-dry-run
   

REST & CMD LINE

Before using any of the request data, make the following replacements:

• PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
• DEPLOYMENT_ID: a user-defined identifier for the deployment

Request JSON body:

{
  "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
  "gameServerConfigOverrides": []
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
   Note: The following command will overwrite any existing request.json file in the current directory.

   cat > request.json << 'EOF'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
     "gameServerConfigOverrides": []
   }
   EOF

2. Execute the following command in the terminal. It references the request.json file you just created.

   curl -X PATCH \
   -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout?updateMask=gameServerConfigOverrides"

PowerShell (Windows)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
   Note: The following command will overwrite any existing request.json file in the current directory.

   @'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
     "gameServerConfigOverrides": []
   }
   '@  | Out-File -FilePath request.json -Encoding utf8

2. Execute the following command in the terminal. It references the request.json file you just created.

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method PATCH `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout?updateMask=gameServerConfigOverrides" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.gaming.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Viewing details about a rollout

Console

1. In the console, go to the Game Server Deployments page.

   Go to Game Servers

2. Find a deployment in the table. In the last table column, click the ellipses and select List configs. You can view the active and inactive configs for the deployment from this page.

3. Click Manage Rollout.

gcloud

You can view details about a rollout, such as the configs in use, using the Google Cloud CLI:

To view the details of a rollout, run the following command after replacing the following placeholder value:

• deploymentID is the unique identifier for the parent deployment.

gcloud game servers deployments describe-rollout deploymentID

The output displays the details of the rollout.

You can also view the state of the game server clusters after the rollout has been applied, using the Google Cloud CLI:

gcloud game servers deployments fetch-state deploymentID

The output displays the changes applied by the rollout on each game server cluster.

REST & CMD LINE

Before using any of the request data, make the following replacements:

• PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
• DEPLOYMENT_ID: a user-defined identifier for the deployment

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

Execute the following command:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout"

PowerShell (Windows)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path for your service account private key file.

Execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/rollout",
  "createTime": CREATE_TIME,
  "updateTime": UPDATE_TIME,
  "defaultGameServerConfig": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/configs/CONFIG_ID",
  "gameServerConfigOverrides": [
    {
      "realmsSelector": {
        "realms": [
          "projects/PROJECT_ID/locations/LOCATION/realms/REALM_ID"
        ]
      },
      "configVersion": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID/configs/OVERRIDE_CONFIG_ID"
    }
  ],
  "etag": "cN31kxa6fWHtaZWUnUZ7LfamUN7Ggz13DWS58Sc5jIQ"
}

Troubleshooting rollouts

This section describes why Game Servers might not being able to update game server clusters. A common cause can be due to the misconfiguration of Game Servers or game server clusters. You can work through the following checklist to help you diagnose potential problems you encounter:

• Check that the following prerequisites for an Agones cluster are met:
  1. Make sure that the cluster is running and that Agones is installed. To verify that the agones-controller pod is in the Running state, run the following command:

     kubectl get pods -n agones-system -l agones.dev/role=controller
     

  2. Make sure that the game server namespace has the required role-based access controls (RBAC) permissions for the Agones controller.
  3. Make sure that the installed version of Agones is supported by Game Servers.
• Check the Agones troubleshooting guide.
• Check that the Game Servers deployment resource is correctly configured:
  1. If you're using an override config, make sure that the deployment applies to the realm with the target cluster.
  2. Make sure that the fleet specification is correctly configured. To validate your fleet specification, try to bring up a game server manually.
  3. If a scheduled change didn't happen, make sure that the schedule is correctly configured. A schedule's timezone follows the realm's timezone.

What's next

Learn how to delete a config.