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 Cloud SDK 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

To install gcloud, install the Cloud SDK, which includes the gcloud command-line tool.

Verify that you have set desired default project for gcloud command-line tool (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 SDK. Game Servers requires version 306.0.0 or higher of the SDK.

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 Cloud 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 gcloud command-line tool:

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 below, 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
}

Go

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	gaming "cloud.google.com/go/gaming/apiv1"
	gamingpb "google.golang.org/genproto/googleapis/cloud/gaming/v1"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
)

// updateRolloutDefaultConfig sets the default config for a game deployment.
func updateRolloutDefaultConfig(w io.Writer, projectID, deploymentID, configID string) error {
	// projectID := "my-project"
	// deploymentID := "mydeployment"
	// configID := "myconfig"
	ctx := context.Background()
	client, err := gaming.NewGameServerDeploymentsClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerDeploymentsClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.UpdateGameServerDeploymentRolloutRequest{
		Rollout: &gamingpb.GameServerDeploymentRollout{
			Name: fmt.Sprintf("projects/%s/locations/global/gameServerDeployments/%s", projectID, deploymentID),

			DefaultGameServerConfig: configID,
		},
		UpdateMask: &fieldmaskpb.FieldMask{
			Paths: []string{
				"default_game_server_config",
			},
		},
	}

	op, err := client.UpdateGameServerDeploymentRollout(ctx, req)
	if err != nil {
		return fmt.Errorf("UpdateGameServerDeploymentRollout: %v", err)
	}
	resp, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("Wait: %v", err)
	}

	fmt.Fprintf(w, "Deployment rollout updated: %v", resp.Name)
	return nil
}

Node.js

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

const {
  GameServerDeploymentsServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerDeploymentsServiceClient();

async function rolloutDefaultGameServerDeployment() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  // const deploymentId = 'A unique ID for the Game Server Deployment';
  // const configId = 'A unique ID for the Game Server Config';
  const request = {
    rollout: {
      name: client.gameServerDeploymentPath(
        projectId,
        'global',
        deploymentId
      ),
      defaultGameServerConfig: configId,
    },
    updateMask: {
      paths: ['default_game_server_config'],
    },
  };

  const [operation] = await client.updateGameServerDeploymentRollout(request);
  const [deployment] = await operation.promise();

  console.log(`Deployment updated: ${deployment.name}`);
}

rolloutDefaultGameServerDeployment();

Python

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

def update_rollout_default(project_id, deployment_id, config_id):
    """Update the rollout of a game server deployment to set the default config."""

    client = gaming.GameServerDeploymentsServiceClient()

    # Location is hard coded as global, as game server deployments can
    # only be created in global.  This is done for all operations on
    # game Server deployments, as well as for its child resource types.
    request = game_server_deployments.UpdateGameServerDeploymentRolloutRequest()
    request.rollout.name = f"projects/{project_id}/locations/global/gameServerDeployments/{deployment_id}"
    request.rollout.default_game_server_config = config_id
    request.update_mask = field_mask.FieldMask(paths=["default_game_server_config"])

    operation = client.update_game_server_deployment_rollout(request)
    print(f"Update deployment rollout operation: {operation.operation.name}")
    operation.result(timeout=120)

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 Cloud 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 gcloud command-line tool:

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 below, 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
}

Go

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	gaming "cloud.google.com/go/gaming/apiv1"
	gamingpb "google.golang.org/genproto/googleapis/cloud/gaming/v1"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
)

// updateRolloutClearDefaultConfig removes the default config for a game deployment.
func updateRolloutClearDefaultConfig(w io.Writer, projectID, deploymentID string) error {
	// projectID := "my-project"
	// deploymentID := "mydeployment"
	ctx := context.Background()
	client, err := gaming.NewGameServerDeploymentsClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerDeploymentsClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.UpdateGameServerDeploymentRolloutRequest{
		Rollout: &gamingpb.GameServerDeploymentRollout{
			Name: fmt.Sprintf("projects/%s/locations/global/gameServerDeployments/%s", projectID, deploymentID),

			DefaultGameServerConfig: "",
		},
		UpdateMask: &fieldmaskpb.FieldMask{
			Paths: []string{
				"default_game_server_config",
			},
		},
	}

	op, err := client.UpdateGameServerDeploymentRollout(ctx, req)
	if err != nil {
		return fmt.Errorf("UpdateGameServerDeploymentRollout: %v", err)
	}
	resp, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("Wait: %v", err)
	}

	fmt.Fprintf(w, "Deployment rollout updated: %v", resp.Name)
	return nil
}

Node.js

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

const {
  GameServerDeploymentsServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerDeploymentsServiceClient();

async function removeRolloutDefaultGameServerDeployment() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  // const deploymentId = 'A unique ID for the Game Server Deployment';
  const request = {
    rollout: {
      name: client.gameServerDeploymentPath(
        projectId,
        'global',
        deploymentId
      ),
      defaultGameServerConfig: '',
    },
    updateMask: {
      paths: ['default_game_server_config'],
    },
  };

  const [operation] = await client.updateGameServerDeploymentRollout(request);
  const [deployment] = await operation.promise();

  console.log(`Deployment updated: ${deployment.name}`);
}

removeRolloutDefaultGameServerDeployment();

Python

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

def update_rollout_remove_default(project_id, deployment_id):
    """Update the rollout of a game server deployment to remove the default config."""

    client = gaming.GameServerDeploymentsServiceClient()

    # Location is hard coded as global, as game server deployments can
    # only be created in global.  This is done for all operations on
    # game server deployments, as well as for its child resource types.
    request = game_server_deployments.UpdateGameServerDeploymentRolloutRequest()
    request.rollout.name = f"projects/{project_id}/locations/global/gameServerDeployments/{deployment_id}"
    request.rollout.default_game_server_config = ""
    request.update_mask = field_mask.FieldMask(paths=["default_game_server_config"])

    operation = client.update_game_server_deployment_rollout(request)
    print(f"Update deployment rollout operation: {operation.operation.name}")
    operation.result(timeout=120)

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 Cloud 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 gcloud command-line tool:

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 below, 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
}

Go

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	gaming "cloud.google.com/go/gaming/apiv1"
	gamingpb "google.golang.org/genproto/googleapis/cloud/gaming/v1"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
)

// updateRolloutOverrideConfig sets the override config for a realm.
func updateRolloutOverrideConfig(w io.Writer, projectID, realmLocation, realmID, deploymentID, configID string) error {
	// projectID := "my-project"
	// realmLocation := "global"
	// realmID := "myrealm"
	// deploymentID := "mydeployment"
	// configID := "myconfig"
	ctx := context.Background()
	client, err := gaming.NewGameServerDeploymentsClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerDeploymentsClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.UpdateGameServerDeploymentRolloutRequest{
		Rollout: &gamingpb.GameServerDeploymentRollout{
			Name: fmt.Sprintf("projects/%s/locations/global/gameServerDeployments/%s", projectID, deploymentID),

			GameServerConfigOverrides: []*gamingpb.GameServerConfigOverride{
				&gamingpb.GameServerConfigOverride{
					Selector: &gamingpb.GameServerConfigOverride_RealmsSelector{
						RealmsSelector: &gamingpb.RealmSelector{
							Realms: []string{
								fmt.Sprintf("projects/%s/locations/%s/realms/%s", projectID, realmLocation, realmID),
							},
						},
					},
					Change: &gamingpb.GameServerConfigOverride_ConfigVersion{
						ConfigVersion: configID,
					},
				},
			},
		},
		UpdateMask: &fieldmaskpb.FieldMask{
			Paths: []string{
				"game_server_config_overrides",
			},
		},
	}

	op, err := client.UpdateGameServerDeploymentRollout(ctx, req)
	if err != nil {
		return fmt.Errorf("UpdateGameServerDeploymentRollout: %v", err)
	}
	resp, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("Wait: %v", err)
	}

	fmt.Fprintf(w, "Deployment rollout updated: %v", resp.Name)
	return nil
}

Node.js

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

const {
  GameServerDeploymentsServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerDeploymentsServiceClient();

async function rolloutGameServerDeploymentOverride() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  // const deploymentId = 'A unique ID for the Game Server Deployment';
  // const configId = 'A unique ID for the Game Server Config';
  // const realmId = 'A unique ID for the realm'
  // const realmLocation = 'compute engine region for realm location'
  const request = {
    rollout: {
      name: client.gameServerDeploymentPath(
        projectId,
        'global',
        deploymentId
      ),
      gameServerConfigOverrides: [
        {
          realmsSelector: {
            realms: [client.realmPath(projectId, realmLocation, realmId)],
          },
          configVersion: configId,
        },
      ],
    },
    updateMask: {
      paths: ['game_server_config_overrides'],
    },
  };

  const [operation] = await client.updateGameServerDeploymentRollout(request);
  const [deployment] = await operation.promise();

  console.log(`Deployment updated: ${deployment.name}`);
}

rolloutGameServerDeploymentOverride();

Python

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

def update_rollout_override(project_id, deployment_id, config_id, realm_location, realm_id):
    """Update the rollout of a game server deployment to set the override config."""

    client = gaming.GameServerDeploymentsServiceClient()

    # Location is hard coded as global, as game server deployments can
    # only be created in global.  This is done for all operations on
    # game Server deployments, as well as for its child resource types.
    request = game_server_deployments.UpdateGameServerDeploymentRolloutRequest()
    request.rollout.name = f"projects/{project_id}/locations/global/gameServerDeployments/{deployment_id}"
    realm_name = f"projects/{project_id}/locations/{realm_location}/realms/{realm_id}"
    config_override = game_server_deployments.GameServerConfigOverride(
        realms_selector=common.RealmSelector(realms=[realm_name]),
        config_version=config_id,
    )
    request.rollout.game_server_config_overrides = [config_override]
    request.update_mask = field_mask.FieldMask(paths=["game_server_config_overrides"])

    operation = client.update_game_server_deployment_rollout(request)
    print(f"Update deployment rollout operation: {operation.operation.name}")
    operation.result(timeout=120)

Clearing config overrides

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

Console

1. In the Cloud 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 gcloud command-line tool:

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 below, 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
}

Go

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	gaming "cloud.google.com/go/gaming/apiv1"
	gamingpb "google.golang.org/genproto/googleapis/cloud/gaming/v1"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
)

// updateRolloutClearOverrideConfig removes any config overrides on a game
// server deployment.
func updateRolloutClearOverrideConfig(w io.Writer, projectID, deploymentID string) error {
	// projectID := "my-project"
	// deploymentID := "mydeployment"
	ctx := context.Background()
	client, err := gaming.NewGameServerDeploymentsClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerDeploymentsClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.UpdateGameServerDeploymentRolloutRequest{
		Rollout: &gamingpb.GameServerDeploymentRollout{
			Name: fmt.Sprintf("projects/%s/locations/global/gameServerDeployments/%s", projectID, deploymentID),
		},
		UpdateMask: &fieldmaskpb.FieldMask{
			Paths: []string{
				"game_server_config_overrides",
			},
		},
	}

	op, err := client.UpdateGameServerDeploymentRollout(ctx, req)
	if err != nil {
		return fmt.Errorf("UpdateGameServerDeploymentRollout: %v", err)
	}
	resp, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("Wait: %v", err)
	}

	fmt.Fprintf(w, "Deployment rollout updated: %v", resp.Name)
	return nil
}

Node.js

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

const {
  GameServerDeploymentsServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerDeploymentsServiceClient();

async function removeRolloutGameServerDeploymentOverride() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  // const deploymentId = 'A unique ID for the Game Server Deployment';
  const request = {
    rollout: {
      name: client.gameServerDeploymentPath(
        projectId,
        'global',
        deploymentId
      ),
    },
    updateMask: {
      paths: ['game_server_config_overrides'],
    },
  };

  const [operation] = await client.updateGameServerDeploymentRollout(request);
  const [deployment] = await operation.promise();

  console.log(`Deployment updated: ${deployment.name}`);
}

removeRolloutGameServerDeploymentOverride();

Python

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

def update_rollout_remove_override(project_id, deployment_id):
    """Update the rollout of a game server deployment to remove the override config."""

    client = gaming.GameServerDeploymentsServiceClient()

    # Location is hard coded as global, as game server deployments can
    # only be created in global.  This is done for all operations on
    # game Server deployments, as well as for its child resource types.
    request = game_server_deployments.UpdateGameServerDeploymentRolloutRequest()
    request.rollout.name = f"projects/{project_id}/locations/global/gameServerDeployments/{deployment_id}"
    request.rollout.game_server_config_overrides = []
    request.update_mask = field_mask.FieldMask(paths=["game_server_config_overrides"])

    operation = client.update_game_server_deployment_rollout(request)
    print(f"Update deployment rollout operation: {operation.operation.name}")
    operation.result(timeout=120)

Viewing details about a rollout

Console

1. In the Cloud 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 gcloud command-line tool:

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 gcloud command-line tool:

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 below, 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"
}

Go

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	gaming "cloud.google.com/go/gaming/apiv1"
	gamingpb "google.golang.org/genproto/googleapis/cloud/gaming/v1"
)

// getGameServerDeploymentRollout retrieves info on a game server deployment's rollout.
func getGameServerDeploymentRollout(w io.Writer, projectID, deploymentID string) error {
	// projectID := "my-project"
	// deploymentID := "mydeployment"
	ctx := context.Background()
	client, err := gaming.NewGameServerDeploymentsClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerDeploymentsClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.GetGameServerDeploymentRolloutRequest{
		Name: fmt.Sprintf("projects/%s/locations/global/gameServerDeployments/%s", projectID, deploymentID),
	}

	resp, err := client.GetGameServerDeploymentRollout(ctx, req)
	if err != nil {
		return fmt.Errorf("GetGameServerDeploymentRollout: %v", err)
	}

	fmt.Fprintf(w, "Rollout default: %v\n", resp.DefaultGameServerConfig)
	for _, override := range resp.GameServerConfigOverrides {
		switch override.Selector.(type) {
		case *gamingpb.GameServerConfigOverride_RealmsSelector:
			fmt.Fprint(w, "Override these realms ", override.GetRealmsSelector().Realms)
		default:
			fmt.Fprint(w, "Unknown override selector")
		}

		switch override.Change.(type) {
		case *gamingpb.GameServerConfigOverride_ConfigVersion:
			fmt.Fprint(w, "with this config: ", override.GetConfigVersion())
		default:
			fmt.Fprint(w, "with an unknown override")
		}
		fmt.Fprintln(w)
	}
	return nil
}

Node.js

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

const {
  GameServerDeploymentsServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerDeploymentsServiceClient();

async function getGameServerDeploymentRollout() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  // const deploymentId = 'A unique ID for the Game Server Deployment';
  const request = {
    // The full resource name
    name: client.gameServerDeploymentPath(projectId, 'global', deploymentId),
  };

  const [rollout] = await client.getGameServerDeploymentRollout(request);
  console.log(`Rollout name: ${rollout.name}`);
  console.log(`Rollout default: ${rollout.defaultGameServerConfig}`);
  for (const override of rollout.gameServerConfigOverrides) {
    console.log(`Rollout config overrides: ${override.configVersion}`);
    console.log(
      `Rollout realm overrides: ${JSON.stringify(override.realmsSelector)}`
    );
  }

  const updateTime = rollout.updateTime;
  const updateDate = new Date(updateTime.seconds * 1000);
  console.log(`Rollout updated on: ${updateDate.toLocaleDateString()}\n`);
}

getGameServerDeploymentRollout();

Python

To learn how to install and use the client library for Game Servers, see the Game Servers Client Libraries.

View on GitHub Feedback

def get_rollout(project_id, deployment_id):
    """Gets the rollout of a game server deployment."""

    client = gaming.GameServerDeploymentsServiceClient()

    # Location is hard coded as global, as game server deployments can
    # only be created in global.  This is done for all operations on
    # game server deployments, as well as for its child resource types.
    request = game_server_deployments.GetGameServerDeploymentRolloutRequest(
        name=f"projects/{project_id}/locations/global/gameServerDeployments/{deployment_id}",
    )

    response = client.get_game_server_deployment_rollout(request)
    print(f"Get deployment response:\n{response}")
    return response

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.