Registering a cluster

This page explains how to register, list, and view details of a Game Servers cluster in a realm.

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:

Set up default gcloud settings using one of the following methods:

  • Using gcloud init, if you want to be walked through setting defaults.
  • Using gcloud config, to individually set your project ID.

Using gcloud init

  1. Run gcloud init and follow the directions:

    gcloud init

    If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

    gcloud init --console-only
  2. Follow the instructions to authorize gcloud to use your Google Cloud account.
  3. Create a new configuration or select an existing one.
  4. Choose a Google Cloud project.
  5. Choose a default Compute Engine zone.

Using gcloud config

  • Set your default project ID:
    gcloud config set project [PROJECT_ID]
  • Update gcloud to the latest version:
    gcloud components update

Registering a cluster

Make sure you have created a Game Servers realm.

If you don't have a Google Kubernetes Engine (GKE) cluster with Agones installed, follow the guides for Creating a Google Kubernetes Engine cluster and Installing Agones. Make sure you install Agones in the agones-system namespace and the game server namespace is correctly setup.

Setting Cloud IAM Permissions

When you create Game Servers resources in a Google Cloud project, Game Servers also creates a Game Servers Google-managed service account that takes the form serviceAccount:service-projectNumber@gcp-sa-gameservices.iam.gserviceaccount.com. After you have a GKE cluster with Agones installed, you need to grant the pre-defined GKE roles/container.developer role to the Game Servers Google-managed service account. This role gives the Google-managed service account the necessary permissions to manage the GKE cluster you're registering.

To learn more about Cloud Identity and Access Management (Cloud IAM) roles for GKE, see Predefined GKE roles on the "Creating Cloud IAM policies" page.

The following command shows the syntax for granting the service account the GKE roles/container.developer role:

gcloud projects add-iam-policy-binding gkeProjectId --role roles/container.developer --member serviceAccount:service-projectNumber@gcp-sa-gameservices.iam.gserviceaccount.com

where:

  • gkeProjectId the ID of the project containing the Google Kubernetes Engine cluster.
  • projectNumber can be retrieved by running gcloud projects describe projectId. You can get projectId by running gcloud config get-value project.

If you're managing all your GKE clusters in a separate dedicated Google Cloud project, the associated Google-managed service account from the Google Cloud project you are using to manage your Game Servers resources also requires the roles/gameservices.serviceAgent role. To grant the role, run the following command:

gcloud projects add-iam-policy-binding gkeProjectId --role roles/gameservices.serviceAgent --member serviceAccount:service-projectNumber@gcp-sa-gameservices.iam.gserviceaccount.com

If the permissions aren't set correctly, you'll see the following error:

Cannot connect to the provided Kubernetes cluster "projects/projectId/locations/location/clusters/gkeCluster", check the name and make sure that "service-projectNumber@gcp-sa-gameservices.iam.gserviceaccount.com" has been granted the required permissions to access the cluster

In this case, double-check the previous steps in this section for setting Cloud IAM permissions.

Registering a global game server cluster

You can register a Game Servers cluster in a realm using the gcloud command-line tool. To register a global game server cluster:

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

    gcloud beta game servers clusters create gscID --realm=realmID --gke-cluster=gkeCluster --namespace=default --dry-run
    

    The output returns the targetState so that you can preview the new cluster before registering it.

  2. To register and create the global cluster, run the following command:

    gcloud beta game servers clusters create gscID --realm=realmID --gke-cluster gkeCluster --namespace=default --no-dry-run
    

Registering a regional game server cluster

To register a regional game server cluster:

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

    gcloud beta game servers clusters create gscID --realm=realmID --gke-cluster gkeCluster --location=region --namespace=default --dry-run
    

    The output returns the targetState so that you can preview the new cluster before creating it.

  2. To register and create the regional cluster, run the following command:

    gcloud beta game servers clusters create gscID --realm=realmID --gke-cluster gkeCluster --location=region --namespace=default --no-dry-run
    

If Game Servers can't validate the cluster that you are trying to attach, you might encounter the error:

Cannot connect to the provided Kubernetes cluster "projects/project/locations/location/clusters/gkeCluster, check the name and make sure that the cluster exists

In this case, make sure gkeCluster is correctly formatted, the cluster exists in project and at location.

The variable placeholders correspond to the following descriptions:

  • gscID is a unique identifier that you can specify for this cluster.
  • realmID is the unique identifier for the realm where you want to store the cluster.
  • gkeCluster is the fully-qualified resource path of a GKE cluster, such as projects/<projectId>/locations/<location>/clusters/<clusterId>.
  • region is the region for the cluster. Pick the same region as the parent realm.

After you create a game server cluster, Game Servers creates Agones fleets and autoscalers as required. Game Servers doesn't alter manually-created Agones fleets.

Listing clusters

You can list global or regional clusters using the gcloud command-line tool.

To list both global and regional clusters, run the following command:

gcloud beta game servers clusters list

To list only clusters in a region, run the following command and replace region with the region that you want to list the clusters in:

gcloud beta game servers clusters list --location=region

To list all clusters in a realm, run the following command and replace realmID with the parent realm and region with the region that you want to list the clusters in:

gcloud beta game servers clusters list --realm=realmID --location=region

Viewing details about a cluster

You find details about a cluster, such as the creation time or GKE cluster details, using the gcloud command-line tool:

To view the details of a cluster, run the following command and replace the placeholder values, such as realmID, with appropriate values:

gcloud beta game servers clusters describe gscID --realm realmID --location=region

The output gives you the details of the cluster.

The variable placeholders correspond to the following descriptions:

  • gscID is the unique identifier that you specified for this game server cluster.
  • realmID is a unique identifier for the realm where your cluster is stored.
  • region is the region for the cluster. Pick the same region as the parent realm.

What's next

Learn how to delete a cluster.