Como registrar um cluster

Nesta página, explicamos como registrar, listar e visualizar os detalhes de um cluster do Game Servers em um realm.

Antes de começar

Antes de começar, recomendamos que você se familiarize com os principais conceitos na Visão geral do Game Servers. Verifique se você também realizou as seguintes tarefas:

  • Verifique se você ativou a API Game Services.
  • Ativar a API Game Services
  • Escolha um shell com o SDK do Cloud instalado ou use um cliente de API:
  • Cloud Shell

    Para iniciar o Cloud Shell, execute os seguintes passos:

    1. Acesse o Console do Google Cloud.

      Console do Google Cloud

    2. No canto superior direito do console, clique no botão Ativar Cloud Shell:

    Uma sessão do Cloud Shell é aberta dentro de um quadro inferior no console. Use esse shell para executar comandos gcloud.

    Shell local

    Para instalar gcloud, instale o SDK do Cloud, que inclui a ferramenta de linha de comando gcloud.

    Verifique se você definiu o projeto padrão desejado para a ferramenta de linha de comando do gcloud (caso contrário, você precisará especificar a sinalização --project explicitamente para cada comando mais tarde):

    gcloud config list project
    

    Caso contrário, execute o seguinte comando para definir um projeto padrão, substituindo project-id pelo ID do projeto que você quer:

    gcloud config set project project-id
    

    Execute o seguinte comando para verificar sua versão do SDK do Google Cloud. O Game Servers requer a versão 306.0.0 ou superior do SDK.

    gcloud version
    

    Para atualizar a instalação, execute o seguinte comando:

    gcloud components update
    

    Biblioteca de cliente

    O Game Servers do Google Cloud pode ser controlado de maneira programática usando uma biblioteca de cliente. Consulte Visão geral das bibliotecas de cliente para instruções sobre como usar a biblioteca e fazer a autenticação.

Como registrar um cluster

Verifique se você criou um realm do Game Servers.

Se você não tiver um cluster do Google Kubernetes Engine (GKE) com o Agones instalada, siga os guias Como criar um cluster do Google Kubernetes Engine e Como instalar o Agones. Verifique se as versões do cluster Agones e do Kubernetes estão em conformidade e se você instalou o Agones no namespace agones-system.

Como registrar um cluster de servidor de jogos

Comando gcloud

É possível registrar um cluster do Game Servers em um realm usando a ferramenta de linha de comando gcloud.

Como registrar um cluster de servidor de jogos global

Para registrar um cluster de servidor de jogos global:

  1. Execute o seguinte comando e substitua os valores do marcador, como realmID, pelos valores apropriados:

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

    A saída retorna targetState para que você possa visualizar o novo cluster antes de registrá-lo.

  2. Para registrar e criar o cluster global, execute o seguinte comando:

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

Como registrar um cluster de servidor de jogos regional

Para registrar um cluster de servidor de jogos regional:

  1. Execute o seguinte comando e substitua os valores do marcador, como realmID, pelos valores apropriados:

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

    A saída retorna targetState para que você possa visualizar o novo cluster antes de criá-lo.

  2. Para registrar e criar o cluster regional, execute o seguinte comando:

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

Se o Game Servers não puder validar o cluster que você está tentando anexar, você verá o seguinte erro:

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

Em caso afirmativo, verifique se gkeCluster está formatado corretamente e se o cluster existe em project e em location.

Os marcadores das variáveis correspondem às seguintes descrições:

  • gscID é um identificador exclusivo que pode ser especificado para esse cluster.
  • realmID é o identificador exclusivo do realm em que você quer armazenar o cluster.
  • gkeCluster é o caminho do recurso totalmente qualificado de um cluster do GKE, como projects/<projectId>/locations/<location>/clusters/<clusterId>.
  • region é a região do cluster. Escolha a mesma região do realm pai.

Go

Ver no GitHub (em inglês) Feedback

import (
	"context"
	"fmt"
	"io"

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

// createCluster registers a game server cluster.
func createCluster(w io.Writer, projectID, location, realmID, clusterID, gkeClusterName string) error {
	// projectID := "my-project"
	// location := "global"
	// realmID := "myrealm"
	// clusterID := "mycluster"
	// gkeClusterName := "projects/1234/locations/us-central1/clusters/gke-cluster"
	ctx := context.Background()
	client, err := gaming.NewGameServerClustersClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerClustersClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.CreateGameServerClusterRequest{
		Parent:              fmt.Sprintf("projects/%s/locations/%s/realms/%s", projectID, location, realmID),
		GameServerClusterId: clusterID,
		GameServerCluster: &gamingpb.GameServerCluster{
			ConnectionInfo: &gamingpb.GameServerClusterConnectionInfo{
				Namespace: "default",
				ClusterReference: &gamingpb.GameServerClusterConnectionInfo_GkeClusterReference{
					GkeClusterReference: &gamingpb.GkeClusterReference{
						Cluster: gkeClusterName,
					},
				},
			},
			Description: "My Game Server Cluster",
		},
	}

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

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

Node.js

Ver no GitHub (em inglês) Feedback
const {
  GameServerClustersServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerClustersServiceClient();

async function createGameServerCluster() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  // const location = 'A Compute Engine region, e.g. "us-central1"';
  // const realmId = 'The ID of the realm to locate this cluster in';
  // const gameClusterId = 'A unique ID for this Game Server Cluster';
  // const gkeClusterName= 'The full resource name of the GKE cluster to use';
  const request = {
    // Provide full resource name of a Game Server Realm
    parent: client.realmPath(projectId, location, realmId),
    gameServerClusterId: gameClusterId,
    gameServerCluster: {
      description: 'My Game Server Cluster',
      connectionInfo: {
        gkeClusterReference: {
          // Provide full resource name of a Kubernetes Engine cluster
          // In the form of 'projects/<project-id>/locations/<location>/clusters/<gke-cluster-name>'
          cluster: gkeClusterName,
        },
        namespace: 'default',
      },
    },
  };

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

  console.log('Game Server Cluster created:');
  console.log(`\tCluster name: ${result.name}`);
  console.log(`\tCluster description: ${result.description}`);
  console.log(
    `\tGKE cluster: ${result.connectionInfo.gkeClusterReference.cluster}`
  );
}

createGameServerCluster();

Python

Ver no GitHub (em inglês) Feedback
def create_cluster(project_id, location, realm_id, cluster_id, gke_cluster_name):
    """Creates a game server cluster."""

    client = gaming.GameServerClustersServiceClient()

    gke_cluster_reference = game_server_clusters.GkeClusterReference(
        cluster=gke_cluster_name,
    )
    request = game_server_clusters.CreateGameServerClusterRequest(
        parent=f"projects/{project_id}/locations/{location}/realms/{realm_id}",
        game_server_cluster_id=cluster_id,
        game_server_cluster=game_server_clusters.GameServerCluster(
            description="My Game Server Cluster",
            connection_info=game_server_clusters.GameServerClusterConnectionInfo(
                gke_cluster_reference=gke_cluster_reference,
                namespace="default",
            ),
        ),
    )

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

Depois de criar um cluster do servidor de jogos, o Game Servers cria frotas do Agones e escalonadores automáticos, conforme necessário. O Game Servers não altera as frotas do Agones criadas manualmente.

Como listar clusters

Comando gcloud

Você pode listar clusters globais ou regionais usando a ferramenta de linha de comando gcloud.

Para listar clusters globais e regionais, execute o seguinte comando:

gcloud game servers clusters list

Para listar somente clusters em uma região, execute o comando a seguir e substitua region pela região em que você quer listar os clusters:

gcloud game servers clusters list --location=region

Para listar todos os clusters em um realm, execute o seguinte comando e substitua realmID pelo realm pai e region pela região em que você quer listar os clusters:

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

Go

Ver no GitHub (em inglês) 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"
)

// listGameServerClusters lists the clusters registered with a realm.
func listGameServerClusters(w io.Writer, projectID, location, realmID string) error {
	// projectID := "my-project"
	// location := "global"
	// realmID := "myrealm"
	ctx := context.Background()
	client, err := gaming.NewGameServerClustersClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerClustersClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.ListGameServerClustersRequest{
		Parent: fmt.Sprintf("projects/%s/locations/%s/realms/%s", projectID, location, realmID),
	}

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

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

	return nil
}

Node.js

Ver no GitHub (em inglês) Feedback
const {
  GameServerClustersServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerClustersServiceClient();

async function listGameServerClusters() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  // const location = 'A Compute Engine region, e.g. "us-central1"';
  // const realmId = 'The ID of the realm to locate this cluster in';
  const request = {
    // Provide full resource name of a Game Server Realm
    parent: client.realmPath(projectId, location, realmId),
  };

  const results = await client.listGameServerClusters(request);
  const [clusters] = results;

  for (const cluster of clusters) {
    console.log('Game Server Cluster:');
    console.log(`\tCluster name: ${cluster.name}`);
    console.log(`\tCluster description: ${cluster.description}`);
    console.log(
      `\tGKE cluster: ${cluster.connectionInfo.gkeClusterReference.cluster}`
    );
  }
}

listGameServerClusters();

Python

Ver no GitHub (em inglês) Feedback
def list_clusters(project_id, location, realm_id):
    """Lists the existing game server clusters."""

    client = gaming.GameServerClustersServiceClient()

    response = client.list_game_server_clusters(
        parent=f"projects/{project_id}/locations/{location}/realms/{realm_id}"
    )

    for cluster in response.game_server_clusters:
        print(f"Name: {cluster.name}")

    return response.game_server_clusters

Como ver detalhes de um cluster

Comando gcloud

Para encontrar detalhes de um cluster, como horário de criação ou detalhes do cluster do GKE, use a ferramenta de linha de comando gcloud:

Para ver os detalhes de um cluster, execute o comando a seguir e substitua os valores do marcador, como realmID, pelos valores apropriados:

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

A resposta mostra os detalhes do cluster.

Os marcadores das variáveis correspondem às seguintes descrições:

  • gscID é o identificador exclusivo que você especificou para esse cluster de servidor de jogos.
  • realmID é um identificador exclusivo do realm em que o cluster está armazenado.
  • region é a região do cluster. Escolha a mesma região do realm pai.

Go

Ver no GitHub (em inglês) Feedback

import (
	"context"
	"fmt"
	"io"

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

// getGameServerCluster retrieves info on a game server cluster.
func getGameServerCluster(w io.Writer, projectID, location, realmID, clusterID string) error {
	// projectID := "my-project"
	// location := "global"
	// realmID := "myrealm"
	// clusterID := "mycluster"
	ctx := context.Background()
	client, err := gaming.NewGameServerClustersClient(ctx)
	if err != nil {
		return fmt.Errorf("NewGameServerClustersClient: %v", err)
	}
	defer client.Close()

	req := &gamingpb.GetGameServerClusterRequest{
		Name: fmt.Sprintf("projects/%s/locations/%s/realms/%s/gameServerClusters/%s", projectID, location, realmID, clusterID),
	}

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

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

Node.js

Ver no GitHub (em inglês) Feedback
const {
  GameServerClustersServiceClient,
} = require('@google-cloud/game-servers');

const client = new GameServerClustersServiceClient();

async function getGameServerCluster() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const projectId = 'Your Google Cloud Project ID';
  // const location = 'A Compute Engine region, e.g. "us-central1"';
  // const realmId = 'The ID of the realm to locate this cluster in';
  // const gameClusterId = 'The unique ID for this Game Server Cluster';
  const request = {
    // Provide full resource name of a Game Server Realm
    name: client.gameServerClusterPath(
      projectId,
      location,
      realmId,
      gameClusterId
    ),
  };

  const [cluster] = await client.getGameServerCluster(request);

  console.log('Game Server Cluster:');
  console.log(`\tCluster name: ${cluster.name}`);
  console.log(`\tCluster description: ${cluster.description}`);
  console.log(
    `\tGKE cluster: ${cluster.connectionInfo.gkeClusterReference.cluster}`
  );
}

getGameServerCluster();

Python

Ver no GitHub (em inglês) Feedback
def get_cluster(project_id, location, realm_id, cluster_id):
    """Gets a game server cluster."""

    client = gaming.GameServerClustersServiceClient()

    request = game_server_clusters.GetGameServerClusterRequest(
        name=f"projects/{project_id}/locations/{location}/realms/{realm_id}/gameServerClusters/{cluster_id}",
    )

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

Solução de problemas

Erro de permissões do IAM

Se as permissões não estiverem definidas corretamente, você verá o seguinte erro:

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

Se isso ocorrer, conclua a etapa nesta seção para definir permissões do IAM.

Quando você cria recursos do Game Servers em um projeto do Google Cloud, esse Game Servers também cria uma conta de serviço gerenciada pelo Google do Game Servers que assume a forma serviceAccount:service-projectNumber@gcp-sa-gameservices.iam.gserviceaccount.com. Essa conta de serviço recebe automaticamente o papel predefinido roles/gameservices.serviceAgentdos servidores de jogos. Esse papel fornece à conta de serviço gerenciada pelo Google as permissões necessárias para gerenciar o cluster do GKE que você está registrando. Se você revogar a mensagem, verá a mensagem de erro acima.

O comando a seguir mostra a sintaxe para conceder à conta de serviço o papel roles/gameservices.serviceAgent dos servidores de jogos:

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

onde:

  • projectId é o código do projeto. Para receber projectId, execute gcloud config get-value project.
  • projectNumber pode ser recuperado executando gcloud projects describe projectId.

A seguir

Saiba como excluir um cluster.