Creating a realm

This page explains how to create, list, describe, and update Game Servers realms. A realm is a user-defined grouping of game server clusters based on the game's latency requirements for player populations.

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:

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

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:

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.

Creating a realm

Realms can be global or regional. A global realm is a good option if the clusters registered to a realm are from regions that span over various geographical locations, such as North America and South America or Europe and Asia. A regional realm is a good option if clusters are in the same region, such as Europe West. In the event of a network outage between regions, a global realm might not be able to manage clusters in every region. To increase the resiliency against network outages between regions, make sure you create regional realms in regions as close as possible to the associated game server clusters.

For example, if you create clusters in the europe-west1, europe-west2, and europe-west3 regions to serve users in the west of Europe, you can also create a regional realm in one of these regions. This configuration ensures the realm can continue to manage clusters in the event these regions can't be reached from regions in other parts of the world due to a network outage.

If you aren't sure where to create your realm, you can create it as a global realm. As your requirements change, you can create a new realm in a region that is closer to the clusters that it needs to manage. You can then move existing clusters to the new regional realm by first deleting and unregistering clusters from the global realm and then registering them in the new regional realm.

Console

1. In the console, go to the Realms & Clusters page.

   Go to Game Servers

2. Click Create Realm.

3. In the Realm name box, enter a unique identifier for this realm.

4. In the Timezone box, select a time zone for this realm. When you schedule time-based events, such as scaling policies, it is for this time zone.

5. Click Create.

gcloud

You can create realms using the Google Cloud CLI. To create a global realm, run the following command and replace the placeholder values, such as realmID, with appropriate values:

gcloud game servers realms create realmID --time-zone tz

To create a regional realm, run the following command and replace the placeholder values, such as realmID, with appropriate values:

gcloud game servers realms create realmID --time-zone tz --location=region

The variable placeholders correspond to the following descriptions:

• realmID is a unique identifier that you can specify for this realm.
• tz is the time zone for this realm. When you schedule time based events, such as scaling policies, it is for this time zone.
• region is the region for the realm. If you want to control failure domains, specify a region. We recommend that you create a global realm and omit this option.

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
• LOCATION: The region for the realm. If you want to control failure domains, specify a region from the list of supported locations. We recommend that you specify a global realm.
• REALM_ID: a user-defined identifier for the new realm
• TIME_ZONE: The time zone for this realm (for example, US/Eastern). You schedule time-based events, such as scaling policies, for this time zone.

Request JSON body:

{
  "timeZone": "TIME_ZONE"
}

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'
   {
     "timeZone": "TIME_ZONE"
   }
   EOF

2. Execute the following command in the terminal. It references the request.json file you just created.

   curl -X POST \
   -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/LOCATION/realms?realmId=REALM_ID"

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.

   @'
   {
     "timeZone": "TIME_ZONE"
   }
   '@  | 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 POST `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://gameservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/realms?realmId=REALM_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

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

Listing realms

Console

1. In the console, go to the Realms & Clusters page.

   Go to Game Servers

2. You can use the filter box to filter the realms list by different properties.

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
• LOCATION: the region for the realms or global

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/LOCATION/realms/"

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/LOCATION/realms/" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "realms": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/realms/realm1",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "timeZone": "US/Eastern",
      "etag": "PlXtLrUJ5pHQoZk0Lz-pWkPFN_dt3PXhIpRrJ5HHWu8"
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/realms/realm2",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "timeZone": "America/Eirunepe",
      "etag": "ay1tXqeujLSsSd93n6uhlZwlxdNTOfG7El992Tsiz98"
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/realms/realm3",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "timeZone": "Asia/Anadyr",
      "etag": "cBxzV2AWK_zgijSmYA-oXPWv3giwhUzssoWcqjPZFuk"
    }
  ]
}

gcloud

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

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

gcloud game servers realms list

To list realms in a specific location run the following command and replace region with either global or a Google Cloud region:

gcloud game servers realms list --location=region

Describing realms

Console

1. In the console, go to the Realms & Clusters page.

   Go to Game Servers

2. You can use the filter box to filter the realms list by different properties.

3. In the last table column, click the ellipses and select View details.

gcloud

You can obtain details about a realm, such as the creation time or time zone, using the Google Cloud CLI.

To describe a global realm, run the following command and replace realmID with the identifier for a realm you have previously created:

gcloud game servers realms describe realmID

If you created one or more realms that weren't global, you can describe details about a realm in a specific region. To describe a realm in a region, replace realmID with the identifier for a realm you have previously created and region with the region that the realm is in:

gcloud game servers realms describe realmID --location=region

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
• LOCATION: the region for the realm or global
• REALM_ID: a user-defined identifier for the realm

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/LOCATION/realms/REALM_ID"

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/LOCATION/realms/REALM_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/realms/REALM_ID",
  "createTime": CREATE_TIME,
  "updateTime": UPDATE_TIME,
  "timeZone": "Asia/Anadyr",
  "etag": "cBxzV2AWK_zgijSmYA-oXPWv3giwhUzssoWcqjPZFuk"
}

Updating a realm

gcloud

To update a field for a realm, run the gcloud game servers realms update command after replacing realmID and region for an existing realm. The following command updates the time zone value for a realm. Replace tz with a supported time zone value.

gcloud game servers realms update realmID --location=region \
    --time-zone=tz --no-dry-run

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

REST & CMD LINE

The following sample updates the timeZone 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
• LOCATION: the region for the realm
• REALM_ID: the user-defined identifier for the realm
• TIME_ZONE: The updated time zone for this realm (for example, US/Eastern). You schedule time-based events, such as scaling policies, for this time zone.

Request JSON body:

{
  "timeZone": "TIME_ZONE"
}

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'
   {
     "timeZone": "TIME_ZONE"
   }
   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/LOCATION/realms/REALM_ID?updateMask=timeZone"

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.

   @'
   {
     "timeZone": "TIME_ZONE"
   }
   '@  | 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/LOCATION/realms/REALM_ID?updateMask=timeZone" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

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

What's next

• Learn how to register a cluster.
• Learn how to delete a realm.