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 a CLI gcloud instalada 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

    Instale a CLI gcloud.

    Verifique se você definiu o projeto padrão desejado para a Google Cloud CLI. Caso contrário, será necessário 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 a versão da Google Cloud CLI. O Game Servers requer a versão 306.0.0 ou mais recente da CLI gcloud. 

    gcloud version

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

    gcloud components update

    curl / PowerShell

    Para usar a API REST com curl ou o Windows PowerShell, faça o seguinte:

    1. Crie uma conta de serviço.
    2. Faça o download de uma chave privada como um arquivo JSON.

    3. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

    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 instalado, faça o seguinte:

  1. Crie um cluster público do Google Kubernetes Engine e uma regra de firewall para o Agones. Ative a API Kubernetes Engine.

    O Game Servers não é compatível com clusters particulares.

  2. Verifique se a regra de firewall para o Agones está ativada:

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

    Você verá esta resposta:

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

  3. Instale o Agones.

  4. Verifique se as versões do cluster do Agones e do Kubernetes são compatíveis e você instalou o Agones no namespace agones-system. Consulte Como confirmar a instalação do Agones para mais informações.

Como registrar um cluster de servidor de jogos

Console

  1. No Console do Google Cloud, acesse a página Domínios e clusters.

    Acessar o Game Servers

  2. Clique em Adicionar cluster do Game Server.

  3. Selecione o realm a que o cluster do Game Servers pertencerá na lista Realms para escolher. Clique no botão Criar um realm para criar um realm, se necessário.

  4. Clique em Continuar.

  5. Na caixa ID do cluster do Game Servers, insira um identificador exclusivo para esse cluster do Game Servers.

  6. Na lista do cluster do Kubernetes, selecione um cluster do Kubernetes com o Agones instalado.

  7. Clique em Criar.

gcloud

É possível registrar um cluster do Game Servers em um realm usando a Google Cloud CLI.

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.

REST

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
  • REALM_LOCATION: a região do realm, ou global, em que o cluster será armazenado
  • REALM_ID: o identificador do realm em que o cluster será armazenado
  • GS_CLUSTER_ID: um identificador definido pelo usuário para o cluster
  • GKE_CLUSTER_LOCATION: a região do cluster do GKE
  • GKE_CLUSTER_ID: o identificador de um cluster do GKE

Solicitar corpo JSON: 

{
  "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"
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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
}

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

Console

  1. No Console do Google Cloud, acesse a página Domínios e clusters.

    Acessar o Game Servers

  2. Expanda um realm para ver os clusters do Game Servers que pertencem a ele.

  3. É possível usar a caixa de filtro para filtrar os realms e a lista de clusters por propriedades diferentes.

gcloud

É possível listar clusters globais ou regionais usando a Google Cloud CLI.

Para listar clusters globais e regionais, execute o seguinte comando: Adicione a sinalização opcional --view=FULL para exibir as versões do Agones e Kubernetes instalados nos clusters.

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

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 [--view=FULL; default="BASIC"]

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 [--view=FULL; default="BASIC"]

REST

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
  • REALM_LOCATION: a região do realm ou global
  • REALM_ID: o identificador definido pelo usuário para o realm

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
      }
    }
  ]
}

Como ver detalhes de um cluster

Console

  1. No Console do Google Cloud, acesse a página Domínios e clusters.

    Acessar o Game Servers

  2. Expanda um realm para ver os clusters do Game Servers que pertencem a ele.

  3. Na última coluna da tabela para o realm, clique nas reticências e selecione Visualizar detalhes.

gcloud

Você encontra detalhes sobre um cluster, como a hora da criação ou os detalhes do cluster do GKE, usando a Google Cloud CLI.

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 [--view=FULL; default="BASIC"]

A resposta mostra os detalhes do cluster. Adicione a sinalização --view=FULL opcional para exibir as versões do Agones e do Kubernetes instaladas no 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.

REST

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
  • REALM_LOCATION: a região do realm ou global
  • REALM_ID: o identificador definido pelo usuário para o realm
  • GS_CLUSTER_ID: o identificador definido pelo usuário para o cluster

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
  }
}

Atualizar um cluster

gcloud

Para atualizar um campo para um cluster, execute o comando gcloud game servers clusters update depois de substituir os identificadores de um cluster existente. O comando a seguir atualiza o campo de descrição de um cluster. 

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

Para encontrar as sinalizações de outros campos de cluster, consulte a referência do gcloud.

REST

A amostra a seguir atualiza o campo description. Para atualizar outros campos, adicione os nomes deles ao parâmetro de consulta ?updateMask= e solicite o corpo JSON.

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
  • REALM_LOCATION: a região do realm ou global
  • REALM_ID: o identificador do realm.
  • GS_CLUSTER_ID: o identificador definido pelo usuário para o cluster

Solicitar corpo JSON: 

{
  "description": "My updated description"
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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
}

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.