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:
Go to Google Cloud console.
From the upper-right corner of the console, click the Activate Cloud Shell button:
- 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.
Cloud Shell
To launch Cloud Shell, perform the following steps:
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:
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
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.
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
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 & CMD LINE
Before using any of the request data, make the following replacements:
- PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
- 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:
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 }
C#
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Go
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Java
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Node.js
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Python
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
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.
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
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 & CMD LINE
Before using any of the request data, make the following replacements:
- PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
- 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:
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" } } ] }
C#
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Go
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Java
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Node.js
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Python
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Viewing details about a cluster
Console
In the Google Cloud console, go to the Realms & Clusters page.
Expand a realm to see the game server clusters that belong to it.
In the last table column for the realm, click the ellipses more_vert and select View details.
gcloud
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 & CMD LINE
Before using any of the request data, make the following replacements:
- PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
- 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:
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" } }
C#
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Go
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Java
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Node.js
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Python
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Updating a cluster
gcloud
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 & CMD LINE
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:
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 }
C#
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Go
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Java
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Node.js
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
Python
To learn how to install and use the client library for Game Servers, see Game Servers client libraries.
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.