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 esta página, confira se você conhece 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 Google Cloud.
    • kubectl

    Se você estiver usando o Cloud Shell como ambiente shell para interagir com 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 Google Cloud ou uma Google Cloud conta de serviço para interagir com clusters conectados pela API 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: Observe o seguinte:

  • Clusters do Google Distributed Cloud (somente software) em bare metal e VMware: o nome da assinatura é igual ao nome do cluster.

  • GKE na AWS: use gcloud container aws clusters get-credentials.

  • GKE no Azure: use gcloud container azure clusters get-credentials.

Saiba mais sobre como permitir que os usuários representem uma conta de serviço em Gerenciar acesso a contas de serviço.

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

Comandos kubectl exec/cp/attach/port-forward

Os seguintes comandos kubectl são de streaming e têm requisitos adicionais:

  • attach
  • cp
  • exec
  • port-forward

Observe os requisitos abaixo:

  • Os clusters precisam estar na versão 1.30 ou mais recente para os comandos attach, cp e exec, e na versão 1.31 ou mais recente para o comando port-forward.

  • O cliente kubectl precisa estar na versão 1.31 ou mais recente.

    Para verificar a versão do cliente, analise a saída do comando kubectl version. Para instalar uma versão mais recente do kubectl, consulte Instalar ferramentas.

Usuários e contas de serviço com o papel do IAM roles/gkehub.gatewayAdmin e o cluster-admin ClusterRole têm as permissões necessárias para executar os comandos attach, cp, exec e port-forward. Se os usuários e as contas de serviço tiverem recebido um papel personalizado do IAM ou da RBAC, talvez seja necessário conceder outras permissões. Consulte as seções a seguir para mais informações.

Conceder uma permissão extra, se necessário

A permissão gkehub.gateway.stream do IAM é necessária para executar os comandos attach, cp, exec e port-forward pelo gateway do Connect. Essa permissão está incluída em roles/gkehub.gatewayAdmin.

Para usuários que não são proprietários do projeto ou para usuários ou contas de serviço que não receberam roles/gkehub.gatewayAdmin no projeto, é necessário conceder roles/gkehub.gatewayAdmin ou criar um papel personalizado que inclua os outros papéis necessários e a permissão gkehub.gateway.stream. Para saber como criar um papel personalizado, consulte Criar e gerenciar papéis personalizados na documentação do IAM.

Crie e aplique outras políticas de RBAC, se necessário

Os usuários e as contas de serviço com o ClusterRole cluster-admin têm as permissões necessárias para executar os comandos attach, cp, exec e port-forward.

As seguintes regras são necessárias para executar os comandos:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE  # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach", "pods/portforward"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE  # Specify the namespace
roleRef:
   apiGroup: "rbac.authorization.k8s.io"
   kind: Role
   name: stream-role
subjects:
- kind: User
  name: EMAIL # Specify the user that should have stream access
  namespace: NAMESPACE  # Specify the namespace

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, verifique 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.

  • O tamanho dos grupos retornados em gke-security-groups excede o limite de tamanho de cabeçalho HTTP de 8 KB. Reorganize a hierarquia de grupos e tente de novo: embora não haja um limite absoluto para o número de grupos, nomes longos podem fazer com que a solicitação exceda o limite de tamanho de cabeçalho HTTP de 8 KB e cause erros que podem exigir a reestruturação da hierarquia de grupos.

Solução de problemas do kubectl exec/cp/attach/port-forward

O erro retornado pela execução do comando geralmente é um erro genérico 400 Bad Request que não é claro o suficiente para depurar o problema. Para retornar mensagens de erro mais detalhadas, use a versão 1.32 ou mais recente do cliente kubectl para executar o comando com um nível de detalhamento 4 ou superior. Por exemplo: kubectl exec -v 4 ....

Nos registros retornados, procure o que contém as seguintes respostas:

  • Para o comando kubectl exec/cp/attach: RemoteCommand fallback:
  • Para o comando kubectl port-forward: fallback to secondary dialer from primary dialer err:

Para resolver problemas com algumas das mensagens de erro comuns que você pode receber do comando kubectl exec -v 4 ..., consulte a seção a seguir.

Permissões do IAM ausentes

Se a mensagem de erro contiver generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource, isso pode indicar que você não recebeu as permissões do IAM necessárias para executar o comando. Esse recurso exige que os usuários tenham a permissão IAM gkehub.gateway.stream, que é incluída por padrão no papel roles/gkehub.gatewayAdmin. Consulte a seção de permissões do IAM para ver instruções.

Permissões RBAC necessárias ausentes

Se a mensagem de erro contiver ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden..., isso indica que você não tem permissões de RBAC. Você precisa de um conjunto de permissões do RBAC no cluster para executar esses comandos kubectl. Para mais informações sobre como configurar as permissões de RBAC necessárias, consulte Criar e aplicar outras políticas de RBAC, se necessário.

Mensagem de erro generic::resource_exhausted: a cota de active_streams do gateway foi esgotada.

Há um limite de cota de 10 streams ativos por projeto host da frota. Isso é definido na cota connectgateway.googleapis.com/active_streams. Consulte Ver e gerenciar cotas para instruções sobre como gerenciar suas cotas.

Mensagem de erro generic::failed_precondition: ocorreu um erro no cluster

Se você receber o erro generic::failed_precondition: error encountered within the cluster, verifique os registros do agente do Connect no cluster para identificar a causa:

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

O registro a ser procurado no agente do Connect é failed to create the websocket connection....

Mensagem de erro generic::failed_precondition: a conexão com o agente falhou/foi encerrada

Se você encontrar esse erro imediatamente ao executar o comando, há um problema com a conexão do cluster ao Google. Consulte o guia de solução de problemas para mais informações.

Se você encontrar esse erro após a sessão ficar ativa por cerca de 20 a 30 minutos, essa é uma limitação esperada por motivos de segurança. A conexão precisa ser restabelecida.

A seguir