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:

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:

Go to Google Cloud console.

Google Cloud console
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:

Create a service account.
Download a private key as a JSON file.
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.

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, do the following:

Create a public Google Kubernetes Engine cluster and firewall rule for Agones. Make sure to enable the Kubernetes Engine API.

Note that Game Servers does not support private clusters.

Verify that the firewall rule for Agones is enabled:

gcloud compute firewall-rules list --filter="name~'game-server.*'"

You should see the following output:

NAME                               NETWORK  DIRECTION  PRIORITY  ALLOW    DENY  DISABLED
game-server-firewall-test-cluster  default  INGRESS    1000      udp:7000-8000  False

Install Agones.
Make sure your Agones and Kubernetes cluster versions are compliant, and you have installed Agones in the agones-system namespace (see Confirming Agones Installation for more information).

Registering a game server cluster

Console

In the Google Cloud console, go to the Realms & Clusters page.

Go to Game Servers
Click Add Game Server Cluster.
Select the realm the game server cluster will belong to from the Realms to choose from list. You can click the Create a Realm button to create a realm if needed.
Click Continue.
In the Game server cluster ID box, enter a unique identifier for this game server cluster.
In the Kubernetes cluster list, select a Kubernetes cluster with Agones installed.
Click Create.

gcloud CLI

You can register a Game Servers cluster in a realm using the Google Cloud CLI.

Registering a global game server cluster

To register a global game server cluster:

Run the following command and replace the placeholder values, such as realmID, with appropriate values:
```
gcloud 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.

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

gcloud 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:

Run the following command and replace the placeholder values, such as realmID, with appropriate values:
```
gcloud 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.

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

gcloud 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 you're trying to attach, you might see the following error:

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

If so, make sure gkeCluster is correctly formatted and that 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.

REST

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

PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
REALM_LOCATION: the region for the realm, or global, in which to store this cluster
REALM_ID: the identifier for the realm in which to store this cluster
GS_CLUSTER_ID: a user-defined identifier for the cluster
GKE_CLUSTER_LOCATION: the region of the GKE cluster
GKE_CLUSTER_ID: the identifier for a GKE cluster

Request JSON body:

{
  "name": "projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID",
  "connectionInfo": {
    "namespace": "default",
    "gkeClusterReference": {
      "cluster": "projects/PROJECT_ID/locations/GKE_CLUSTER_LOCATION/clusters/GKE_CLUSTER_ID"
    }
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by executing gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by executing gcloud auth list.

Save the request body in a file called request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "name": "projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID",
  "connectionInfo": {
    "namespace": "default",
    "gkeClusterReference": {
      "cluster": "projects/PROJECT_ID/locations/GKE_CLUSTER_LOCATION/clusters/GKE_CLUSTER_ID"
    }
  }
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters?gameServerClusterId=GS_CLUSTER_ID"

PowerShell (Windows)

Save the request body in a file called request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "name": "projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID",
  "connectionInfo": {
    "namespace": "default",
    "gkeClusterReference": {
      "cluster": "projects/PROJECT_ID/locations/GKE_CLUSTER_LOCATION/clusters/GKE_CLUSTER_ID"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters?gameServerClusterId=GS_CLUSTER_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/REALM_LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.gaming.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

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

Console

In the Google Cloud console, go to the Realms & Clusters page.

Go to Game Servers
Expand a realm to see the game server clusters that belong to it.
You can use the filter box to filter the realms and clusters list by different properties.

gcloud CLI

You can list global or regional clusters using the Google Cloud CLI.

To list both global and regional clusters, run the following command. Add the optional --view=FULL flag to display the versions of Agones and Kubernetes installed on the clusters.

gcloud game servers clusters list [--view=FULL; default="BASIC"]

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 game servers clusters list --location=region [--view=FULL; default="BASIC"]

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 game servers clusters list --realm=realmID --location=region [--view=FULL; default="BASIC"]

REST

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

PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
REALM_LOCATION: the region for the realm or global
REALM_ID: the user-defined identifier for the realm

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters?view=full"

PowerShell (Windows)

Execute the following command:

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters?view=full" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "gameServerClusters": [
    {
      "name": "projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/my-gs-cluster-1",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "connectionInfo": {
        "namespace": "default",
        "gkeClusterReference": {
          "cluster": "projects/PROJECT_ID/locations/GKE_CLUSTER_LOCATION/clusters/my-gke-cluster-1"
        }
      },
      "etag": "8mBC7IJJFvY40k-rBabOOaGR6sSRG3dP6pI-frTuu9Y",
      "clusterState": {
        "agonesVersionInstalled": "1.15.0",
        "kubernetesVersionInstalled": "1.18.20-gke.900",
        "installationState": "AGONES_KUBERNETES_VERSION_SUPPORTED",
        "provider": "gke"
      }
    },
    {
      "name": "projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/my-gs-cluster-2",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "connectionInfo": {
        "namespace": "default",
        "gkeClusterReference": {
          "cluster": "projects/PROJECT_ID/locations/GKE_CLUSTER_LOCATION/clusters/my-gke-cluster-2"
        }
      },
      "etag": "8mBC7IJJFvY40k-rBabOOaGR6sSRG3dP6pI-frTuu9Y",
      "clusterState": {
        "agonesVersionInstalled": "1.15.0",
        "kubernetesVersionInstalled": "1.18.20-gke.900",
        "installationState": "AGONES_KUBERNETES_VERSION_SUPPORTED",
        "provider": "gke"
      }
    }
  ]
}

Viewing details about a cluster

Console

In the Google Cloud console, go to the Realms & Clusters page.

Go to Game Servers
Expand a realm to see the game server clusters that belong to it.
In the last table column for the realm, click the ellipses and select View details.

gcloud CLI

You find details about a cluster, such as the creation time or GKE cluster details, using the Google Cloud CLI.

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

gcloud game servers clusters describe gscID --realm realmID --location=region [--view=FULL; default="BASIC"]

The output gives you the details of the cluster. Add the optional --view=FULL flag to display the versions of Agones and Kubernetes installed on 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.

REST

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

PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
REALM_LOCATION: the region for the realm or global
REALM_ID: the user-defined identifier for the realm
GS_CLUSTER_ID: the user-defined identifier for the cluster

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID?view=full"

PowerShell (Windows)

Execute the following command:

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID?view=full" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID",
  "createTime": CREATE_TIME,
  "updateTime": UPDATE_TIME,
  "connectionInfo": {
    "namespace": "default",
    "gkeClusterReference": {
      "cluster": "projects/PROJECT_ID/locations/GKE_CLUSTER_LOCATION/clusters/MY_GKE_CLUSTER"
    }
  },
  "etag": "8mBC7IJJFvY40k-rBabOOaGR6sSRG3dP6pI-frTuu9Y",
  "clusterState": {
    "agonesVersionInstalled": "1.15.0",
    "kubernetesVersionInstalled": "1.18.20-gke.900",
    "installationState": "AGONES_KUBERNETES_VERSION_SUPPORTED",
    "provider": "gke"
  }
}

Updating a cluster

gcloud CLI

To update a field for a cluster, run the gcloud game servers clusters update command after replacing the identifiers for an existing cluster. The following command updates the description field for a cluster.

gcloud game servers clusters update gscID \
    --realm=realmID --location=region \
    --description="My updated description" --no-dry-run

To find the flags for other cluster fields, see the gcloud reference.

REST

The following sample updates the description field. To update other fields, add the field names to the ?updateMask= query parameter and request JSON body.

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

PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
REALM_LOCATION: the region for the realm, or global
REALM_ID: the identifier for the realm
GS_CLUSTER_ID: the user-defined identifier for the cluster

Request JSON body:

{
  "description": "My updated description"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file called request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "description": "My updated description"
}
EOF

Then execute the following command to send your REST request:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID?updateMask=description"

PowerShell (Windows)

Save the request body in a file called request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "description": "My updated description"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth 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/REALM_LOCATION/realms/REALM_ID/gameServerClusters/GS_CLUSTER_ID?updateMask=description" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

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

Troubleshooting

IAM permissions error

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", make sure that "service-projectNumber@gcp-sa-gameservices.iam.gserviceaccount.com" has been granted the required permissions to access the cluster

If this occurs, complete the step in this section for setting 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. This service account is automatically granted the predefined Game Servers roles/gameservices.serviceAgent role. This role gives the Google-managed service account the necessary permissions to manage the GKE cluster you're registering. If you revoke it, you will see the above error message.

The following command shows the syntax for granting the service account the Game Servers roles/gameservices.serviceAgent role:

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

where:

projectId is the ID of the project. You can get projectId by running gcloud config get-value project.
projectNumber can be retrieved by running gcloud projects describe projectId.

What's next

Learn how to delete a cluster.