Updating a rollout

This page explains how to update and view details of a Game Servers rollout in a deployment. A rollout maps game server configs to target 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

    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

Make sure you have created a Game Servers config.

Updating a rollout's default config

gcloud

To update the default config of a Game Servers rollout using the gcloud command-line tool:

  1. Run the following command and replace the placeholder values, such as deploymentID and configID, with appropriate values:

    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

Go

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


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. 

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. 

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

gcloud

To clear the default config of a Game Servers rollout using the gcloud command-line tool:

  1. Run the following command and replace the placeholder values, such as deploymentID and configID, with appropriate values:

    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

Go

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


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. 

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. 

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 realms

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 placeholder values, such as realmID and configID, with appropriate values:

    - realmsSelector:
    realms:
        - realmID
  configVersion: configID

  2. Run the following command and replace the placeholder values, such as deploymentID and configID, with appropriate values:

    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

Go

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


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. 

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. 

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

gcloud

To clear the config overrides of a Game Servers rollout using the gcloud command-line tool:

  1. Run the following command and replace the placeholder values, such as deploymentID and configID, with appropriate values:

    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

The variable placeholders correspond to the following descriptions:

  • configID is a unique identifier that you can specify for the config.
  • deploymentID is the unique identifier for the deployment.
  • realmID is the fully-qualified identifier for a realm, such as projects/<projectID>/locations/<region>/realms/<realmID2>.
  • configOverrideFile is the path to the file with override config.

Go

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


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. 

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. 

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

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 and replace the placeholder values, such as deploymentID, with appropriate values:

gcloud game servers deployments describe-rollout deploymentID

The deploymentID placeholder is a unique identifier for the parent deployment.

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.

Go

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


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. 

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. 

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.