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 da Google Cloud CLI, 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 CLI 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 da Google Cloud CLI 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, execute o comando a seguir para ver todos os clusters registrados da frota atual:

gcloud container fleet memberships list

Ele lista todos os clusters da frota, incluindo os nomes de associação e IDs externos. Cada cluster em uma frota 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 abaixo para acessar o kubeconfig necessário para interagir com o cluster especificado:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Substitua MEMBERSHIP_NAME pelo nome da assinatura de frota do cluster.

Esse comando retorna um Conectar-se específico ao gatewaykubeconfig especial que permite a conexão com o cluster por meio do Connect gateway.

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.

Para buscar a credencial do cluster usada para interagir com o gateway do Connect usando uma conta de serviço, execute os seguintes comandos:

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Substitua SA_EMAIL_ADDRESS pelo endereço de e-mail da conta de serviço Saiba mais sobre como permitir que os usuários representem uma conta de serviço em Gerenciar acesso a contas de serviço.

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:

  • attach
  • cp
  • exec
  • port-forward

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: talvez você veja esta mensagem de erro quando o comando kubectl get ns falhar. 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.
  • Não foi possível encontrar conexões ativas para o cluster(project: 12345, membership: my-cluster): esse erro pode ocorrer quando o Connect Agent perde a conectividade ou não estiver mais instalado (apenas clusters fora do Google Cloud). Para resolver esse problema, você precisa verificar se o namespace gke-connect existe no cluster. Se o namespace gke-connect existir no cluster, consulte a página Solução de problemas do Connect para corrigir os problemas de conectividade.
  • 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 da Google Cloud CLI que você está usando é a mais recente e tente gerar o gateway do kubeconfig novamente. Não edite manualmente o arquivo kubeconfig, porque isso causará erros inesperados.
  • A identidade do usuário não tem permissões suficientes para usar a API do gateway: você precisa do papel roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader ou roles/gkehub.gatewayEditorpara usar a API. Consulte Conceder papéis do IAM aos usuários no guia de configuração do gateway para saber 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.
  • A identidade do usuário não tem permissões suficientes para realizar a operação ao usar os Grupos do Google ou o suporte de terceiros: consulte Como coletar registros do serviço de identidade do GKE para instruções sobre como inspecionar registros relacionados a informações de identidade.
  • 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.
  • executável gke-gcloud-auth-plugin não encontrado ou nenhum provedor de autenticação encontrado para o nome gcp: o kubectl versões 1.26 e posteriores pode exibir esse erro devido a mudanças no kubectl Authentication a partir do GKE v1.26. Instale o gke-gcloud-auth-plugin e execute o gcloud container fleet memberships get-credentials MEMBERSHIP_NAME novamente com a versão mais recente da CLI do Google Cloud.
  • As conexões com o gateway falham com versões mais antigas da Google Cloud CLI: para clusters do GKE, o agente do Connect não é mais necessário para que o gateway funcione, portanto, ele não é instalado por padrão durante o registro da assinatura. As versões mais antigas da CLI do Google Cloud (399.0.0 e anteriores) presumem a existência do agente do Connect no cluster. A tentativa de usar o gateway com essas versões mais antigas pode falhar em clusters registrados com uma versão mais recente da CLI do Google Cloud. Para resolver isso, faça upgrade do cliente do Google Cloud CLI para uma versão mais recente ou execute novamente o comando de registro de associação com a sinalização --install-connect-agent.

A seguir