Creating a deployment

This page explains how to create, list, and describe Game Servers deployments. A deployment manages one or more software versions that you can deploy to any or all realms. To see an end-to-end example of how to create a deployment, add a config, and then roll it out, see Configuring cluster scaling behavior.

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

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 deployment

Console

1. In the Cloud Console, go to the Game Server Deployments page.

   Go to Game Servers

2. Click Create Deployment.

3. In the Name box, enter a unique identifier for this deployment.

4. (Optional) In the Description box, enter a description for this deployment.

5. Click Create.

gcloud

You can create a deployment using the gcloud command-line tool.

To create a deployment, run the following command and replace the deploymentID, with an appropriate value:

gcloud game servers deployments create deploymentID

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
• DEPLOYMENT_ID: a user-defined identifier for the deployment

Request JSON body:

{
  "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
}

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'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
   }
   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/global/gameServerDeployments?deploymentId=DEPLOYMENT_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.

   @'
   {
     "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
   }
   '@  | 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/global/gameServerDeployments?deploymentId=DEPLOYMENT_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

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

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	gaming "cloud.google.com/go/gaming/apiv1"
	gamingpb "google.golang.org/genproto/googleapis/cloud/gaming/v1"
)

// createGameServerDeployment creates a game server deployment.
func createGameServerDeployment(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()

	// 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.
	req := &gamingpb.CreateGameServerDeploymentRequest{
		Parent:       fmt.Sprintf("projects/%s/locations/global", projectID),
		DeploymentId: deploymentID,
		GameServerDeployment: &gamingpb.GameServerDeployment{
			Description: "My Game Server Deployment",
		},
	}

	op, err := client.CreateGameServerDeployment(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateGameServerDeployment: %v", err)
	}
	resp, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("Wait: %v", err)
	}

	fmt.Fprintf(w, "Deployment created: %v", resp.Name)
	return nil
}

Java

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

View on GitHub Feedback

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.gaming.v1.CreateGameServerDeploymentRequest;
import com.google.cloud.gaming.v1.GameServerDeployment;
import com.google.cloud.gaming.v1.GameServerDeploymentsServiceClient;
import com.google.cloud.gaming.v1.OperationMetadata;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateDeployment {
  public static void createGameServerDeployment(String projectId, String deploymentId)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // String projectId = "your-project-id";
    // String deploymentId = "your-game-server-deployment-id";
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (GameServerDeploymentsServiceClient client = GameServerDeploymentsServiceClient.create()) {

      // Build a spec as shown at https://agones.dev/site/docs/reference/gameserver/
      JsonObject container = new JsonObject();
      container.addProperty("name", "default");
      container.addProperty("image", "gcr.io/agones-images/default:1.0");

      JsonArray containers = new JsonArray();
      containers.add(container);

      JsonObject spec = new JsonObject();
      spec.add("containers", containers);

      JsonObject template = new JsonObject();
      template.add("spec", spec);

      JsonObject port = new JsonObject();
      port.addProperty("name", "default");

      JsonArray ports = new JsonArray();
      ports.add(port);

      JsonObject specObject = new JsonObject();
      specObject.add("ports", ports);
      specObject.add("template", template);

      String parent = String.format("projects/%s/locations/global", projectId);
      String deploymentName = String.format("%s/gameServerDeployments/%s", parent, deploymentId);

      GameServerDeployment gameServerDeployment =
          GameServerDeployment.newBuilder().setName(deploymentName).build();

      CreateGameServerDeploymentRequest request =
          CreateGameServerDeploymentRequest.newBuilder()
              .setParent(parent)
              .setDeploymentId(deploymentId)
              .setGameServerDeployment(gameServerDeployment)
              .build();

      OperationFuture<GameServerDeployment, OperationMetadata> call =
          client.createGameServerDeploymentAsync(request);

      GameServerDeployment created = call.get(1, TimeUnit.MINUTES);
      System.out.println("Game Server Deployment created: " + created.getName());
    }
  }
}

Node.js

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

View on GitHub Feedback

const {
  GameServerDeploymentsServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerDeploymentsServiceClient();

async function createGameServerDeployment() {
  /**
   * 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 = {
    parent: `projects/${projectId}/locations/global`,
    deploymentId: deploymentId,
    gameServerDeployment: {
      description: 'nodejs test deployment',
    },
  };

  const [operation] = await client.createGameServerDeployment(request);
  const [result] = await operation.promise();

  console.log('Game Server Deployment created:');
  console.log(`\t Deployment name: ${result.name}`);
  console.log(`\t Deployment description: ${result.description}`);
}

createGameServerDeployment();

Python

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

View on GitHub Feedback

def create_deployment(project_id, deployment_id):
    """Creates 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.CreateGameServerDeploymentRequest(
        parent=f"projects/{project_id}/locations/global",
        deployment_id=deployment_id,
        game_server_deployment=game_server_deployments.GameServerDeployment(
            description="My Game Server Deployment"
        ),
    )

    operation = client.create_game_server_deployment(request)
    print(f"Create deployment operation: {operation.operation.name}")
    operation.result(timeout=120)

Listing deployments

Console

1. In the Cloud Console, go to the Game Server Deployments page.

   Go to Game Servers

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

gcloud

You can list deployments using the gcloud command-line tool.

To list deployments, run the following command:

gcloud game servers deployments list

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

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/global/gameServerDeployments"

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/global/gameServerDeployments" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "gameServerDeployments": [
    {
      "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/my-deployment-1",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "etag": "RI8hTm3ZaMNZ3qRVeKVcxcN3W26_oR559JYofnFi69A"
    },
    {
      "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/my-deployment-2",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "etag": "az38kwIY4X3WdP2SA0fkTGib9hwVj7iXLFXAtIzMLpc"
    }
  ]
}

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	gaming "cloud.google.com/go/gaming/apiv1"
	"google.golang.org/api/iterator"
	gamingpb "google.golang.org/genproto/googleapis/cloud/gaming/v1"
)

// listGameServerDeployments lists the game server deployments.
func listGameServerDeployments(w io.Writer, projectID string) error {
	// projectID := "my-project"
	// realmID := "myrealm"
	ctx := context.Background()
	client, err := gaming.NewGameServerDeploymentsClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerDeploymentsClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.ListGameServerDeploymentsRequest{
		Parent: fmt.Sprintf("projects/%s/locations/global", projectID),
	}

	it := client.ListGameServerDeployments(ctx, req)
	for {
		resp, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("Next: %v", err)
		}

		fmt.Fprintf(w, "Deployment listed: %v\n", resp.Name)
	}

	return nil
}

Java

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

View on GitHub Feedback

import com.google.cloud.gaming.v1.GameServerDeployment;
import com.google.cloud.gaming.v1.GameServerDeploymentsServiceClient;
import com.google.cloud.gaming.v1.GameServerDeploymentsServiceClient.ListGameServerDeploymentsPagedResponse;
import com.google.cloud.gaming.v1.ListGameServerDeploymentsRequest;
import com.google.common.base.Strings;
import java.io.IOException;

public class ListDeployments {
  public static void listGameServerDeployments(String projectId) throws IOException {
    // String projectId = "your-project-id";
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (GameServerDeploymentsServiceClient client = GameServerDeploymentsServiceClient.create()) {
      String parent = String.format("projects/%s/locations/global", projectId);

      ListGameServerDeploymentsPagedResponse response = client.listGameServerDeployments(parent);
      for (GameServerDeployment deployment : response.iterateAll()) {
        System.out.println("Game Server Deployment found: " + deployment.getName());
      }

      while (!Strings.isNullOrEmpty(response.getNextPageToken())) {
        ListGameServerDeploymentsRequest request =
            ListGameServerDeploymentsRequest.newBuilder()
                .setParent(parent)
                .setPageToken(response.getNextPageToken())
                .build();
        response = client.listGameServerDeployments(request);
        for (GameServerDeployment deployment : response.iterateAll()) {
          System.out.println("Game Server Deployment found: " + deployment.getName());
        }
      }
    }
  }
}

Node.js

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

View on GitHub Feedback

const {
  GameServerDeploymentsServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerDeploymentsServiceClient();

async function listGameServerDeployments() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  const request = {
    parent: `projects/${projectId}/locations/global`,
  };

  const [results] = await client.listGameServerDeployments(request);
  for (const deployment of results) {
    console.log(`Deployment name: ${deployment.name}`);
    console.log(`Deployment description: ${deployment.description}`);

    const createTime = deployment.createTime;
    const createDate = new Date(createTime.seconds * 1000);
    console.log(
      `Deployment created on: ${createDate.toLocaleDateString()}\n`
    );
  }
}

listGameServerDeployments();

Python

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

View on GitHub Feedback

def list_deployments(project_id):
    """Lists the existing game server deployments."""

    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.
    response = client.list_game_server_deployments(
        parent=f"projects/{project_id}/locations/global"
    )

    for deployment in response.game_server_deployments:
        print(f"Name: {deployment.name}")

    return response.game_server_deployments

Describing a deployment

Console

1. In the Cloud Console, go to the Game Server Deployments page.

   Go to Game Servers

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

3. In the last table column, click the ellipses and select List configs. You can view the active and inactive configs for the deployment from this page.

4. To create a new config for the deployment, click Create Config. To update the rollout, click Manage Rollout.

gcloud

You can obtain details about a deployment, such as the creation time or update time, using the gcloud command-line tool.

To describe a deployment, run the following command and replace deploymentID with the identifier for a deployment you have previously created:

gcloud game servers deployments describe deploymentID

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
• DEPLOYMENT_ID: the user-defined identifier for the deployment

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/global/gameServerDeployments/DEPLOYMENT_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/global/gameServerDeployments/DEPLOYMENT_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/global/gameServerDeployments/DEPLOYMENT_ID",
  "createTime": CREATE_TIME,
  "updateTime": UPDATE_TIME,
  "etag": "RI8hTm3ZaMNZ3qRVeKVcxcN3W26_oR559JYofnFi69A"
}

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	gaming "cloud.google.com/go/gaming/apiv1"
	gamingpb "google.golang.org/genproto/googleapis/cloud/gaming/v1"
)

// getGameServerDeployment retrieves info on a game server deployment.
func getGameServerDeployment(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.GetGameServerDeploymentRequest{
		Name: fmt.Sprintf("projects/%s/locations/global/gameServerDeployments/%s", projectID, deploymentID),
	}

	resp, err := client.GetGameServerDeployment(ctx, req)
	if err != nil {
		return fmt.Errorf("GetGameServerDeployment: %v", err)
	}

	fmt.Fprintf(w, "Deployment retrieved: %v", resp.Name)
	return nil
}

Java

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

View on GitHub Feedback

import com.google.cloud.gaming.v1.GameServerDeployment;
import com.google.cloud.gaming.v1.GameServerDeploymentsServiceClient;
import java.io.IOException;

public class GetDeployment {
  public static void getGameServerDeployment(String projectId, String deploymentId)
      throws IOException {
    // String projectId = "your-project-id";
    // String deploymentId = "your-game-server-deployment-id";
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (GameServerDeploymentsServiceClient client = GameServerDeploymentsServiceClient.create()) {
      String deploymentName =
          String.format(
              "projects/%s/locations/global/gameServerDeployments/%s", projectId, deploymentId);

      GameServerDeployment deployment = client.getGameServerDeployment(deploymentName);

      System.out.println("Game Server Deployment found: " + deployment.getName());
    }
  }
}

Node.js

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

View on GitHub Feedback

const {
  GameServerDeploymentsServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerDeploymentsServiceClient();

async function getGameServerDeployment() {
  /**
   * 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 [deployment] = await client.getGameServerDeployment(request);
  console.log(`Deployment name: ${deployment.name}`);
  console.log(`Deployment description: ${deployment.description}`);

  const createTime = deployment.createTime;
  const createDate = new Date(createTime.seconds * 1000);
  console.log(`Deployment created on: ${createDate.toLocaleDateString()}\n`);
}

getGameServerDeployment();

Python

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

View on GitHub Feedback

def get_deployment(project_id, deployment_id):
    """Gets 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.GetGameServerDeploymentRequest(
        name=f"projects/{project_id}/locations/global/gameServerDeployments/{deployment_id}",
    )

    response = client.get_game_server_deployment(request)
    print(f"Get deployment response:\n{response}")
    return response

What's next

• Learn how to create a config.
• Learn how to create or update a rollout.
• Learn how to delete a deployment.