Como usar o gateway do Connect

Nesta página, você verá como usar o gateway do Connect para se conectar a um cluster registrado. Antes de ler este guia, você precisa conhecer os conceitos da nossa visão geral. O guia considera que o administrador do projeto já configurou o gateway e que você recebeu as funções e permissões necessárias.

Antes de começar

  • Verifique se você tem as seguintes ferramentas de linha de comando instaladas:

    • A versão mais recente do SDK do Cloud, que inclui a gcloud, a ferramenta de linha de comando para interagir com o Google Cloud.
    • kubectl

    Se você estiver usando o Cloud Shell como ambiente shell para interagir com o Google Cloud, essas ferramentas estarão instaladas.

  • Verifique se você inicializou a ferramenta de linha de comando gcloud para usar com seu projeto.

Faça login na sua conta do Google Cloud

Use sua própria conta do Google Cloud ou uma conta de serviço do Google Cloud para interagir com os clusters conectados por meio da API do gateway.

Siga as instruções em Como autorizar ferramentas do SDK do Cloud para fazer login na sua conta de usuário. O gateway do Connect é compatível com a falsificação de identidade da conta de serviço. Portanto, mesmo que você esteja conectado em sua própria conta de usuário, use uma conta de serviço para interagir com clusters, como verá nas seções a seguir.

Selecione um cluster registrado

Se você não souber o nome do cluster que quer acessar, poderá ver todos os clusters registrados do seu ambiente atual executando o seguinte comando:

gcloud container hub memberships list

Ele lista todos os clusters do ambiente, incluindo os nomes de associação e IDs externos. Cada cluster em um ambiente tem um nome de assinatura exclusivo. Para clusters do GKE, o nome da assinatura geralmente corresponde ao nome que você atribuiu ao criar o cluster, a menos que o nome do cluster não seja exclusivo no projeto em registro.

Acesse o gateway kubeconfig do cluster

Use o comando a seguir para conseguir o kubeconfig que você precisa para interagir com o cluster especificado, substituindo MEMBERSHIP_NAME pelo nome da assinatura de ambiente do cluster. Esse comando retorna um Conectar-se específico ao gatewaykubeconfig especial que permite a conexão com o cluster por meio do gateway.

# Fetch cluster credential used to interact with Connect gateway
gcloud beta container hub memberships get-credentials MEMBERSHIP_NAME

Se você quiser usar uma conta de serviço em vez da sua conta do Google Cloud, use gcloud config para definir auth/impersonate_service_account como o endereço de e-mail da conta de serviço. Saiba mais sobre como permitir que os usuários falsifiquem a identidade uma conta de serviço em Como gerenciar a falsificação de identidade da conta de serviço.

# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud beta container hub memberships get-credentials MEMBERSHIP_NAME

Executar comandos no cluster

Quando você tiver as credenciais necessárias, será possível executar comandos usando kubectl ou um go-client, como normalmente faria para qualquer cluster do Kubernetes. A resposta será semelhante a esta:

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

Os comandos kubectl a seguir não são compatíveis com o gateway:

  • exec
  • proxy

Solução de problemas

Se você tiver problemas para se conectar a um cluster pelo gateway, você ou seu administrador poderão verificar os seguintes problemas comuns.

  • O servidor não tem um tipo de recurso "namespaces": esta mensagem de erro pode ser exibida quando um comando simples, como kubectl get ns, falha. Há vários motivos possíveis para esse erro. Execute os comandos kubectl no modo detalhado para ver mais detalhes, por exemplo, kubectl get ns -v 10.
  • O URL solicitado não foi encontrado neste servidor: você poderá ver esse erro quando kubeconfig tiver um endereço de servidor incorreto. Verifique se a versão do SDK do Cloud que você está usando é a versão mais recente e tente gerar o gateway kubeconfig novamente. Não edite manualmente o arquivo kubeconfig, o que causará erros inesperados.
  • A identidade do usuário não tem permissões suficientes para usar a API do gateway: você precisa do papel role/gkehub.gatewayAdmin para usar a API. Consulte Conceder permissões de IAM no guia de configuração de gateway para mais detalhes.
  • O agente do Connect não está autorizado a enviar as solicitações do usuário: o agente do Connect precisa ter autorização para encaminhar solicitações em seu nome, o que é especificado usando uma política de falsificação de identidade no cluster. Consulte Configurar políticas de RBAC no guia de configuração de gateway para ver um exemplo de como adicionar um usuário ao papel gateway-impersonate.
  • A identidade do usuário não tem permissões RBAC suficientes para executar a operação: você precisa ter as permissões apropriadas no cluster para executar as operações escolhidas. Consulte Configurar políticas de RBAC no guia de configuração de gateway para ver um exemplo de como adicionar um usuário ao ClusterRole apropriado.
  • O agente do Connect não está íntegro: consulte a página "Solução de problemas do Connect" para garantir que o cluster esteja conectado.

A seguir