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: 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.

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 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

Limitações

Os comandos kubectl a seguir não são compatíveis com o gateway usando o comando gcloud container fleet memberships get-credentials:

  • attach
  • cp
  • exec
  • port-forward

Visualizar o suporte aos comandos

Os comandos attach, cp e exec (mas não port-forward) são compatíveis com o comando Beta gcloud beta container fleet memberships get-credentials. Esse comando permite usar um recurso de pré-lançamento do gateway do Connect.

Observe os requisitos abaixo:

  • O GKE no Google Cloud não é compatível com a visualização.

  • Os clusters precisam estar na versão 1.30 ou mais recente.

  • O cliente kubectl precisa estar na versão 1.29 ou mais recente. Se você usar a versão 1.29, defina a seguinte variável de ambiente:

    export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

    As versões 1.30 e mais recentes do kubectl não exigem a variável de ambiente.

    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 e exec. 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 ver 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 e exec 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 e exec.

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"]
  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 do kubectl exec/cp/attach

O erro retornado pela execução do comando geralmente não é claro o suficiente para depurar o problema. Nesse caso, execute o comando novamente com um nível de registro de verboseidade mais alto, por exemplo: kubectl exec -v 5 ....

A faixa Beta do gateway do Connect não está sendo usada

Se você receber um erro 400 Bad Request, gere novamente o arquivo kubeconfig do gateway de conexão usando a faixa Beta da CLI gcloud para ver se isso corrige o erro:

gcloud beta container fleet memberships get-credentials my-membership`

Se o erro 400 Bad Request ainda aparecer, siga as etapas na próxima seção.

A flag do ambiente kubectl não está definida

Se a versão do cliente kubectl que você está usando for 1.29, a variável de ambiente KUBECTL_REMOTE_COMMAND_WEBSOCKETS precisa ser ativada. Se essa opção não estiver ativada, você vai receber um erro 400 Bad Request. Para saber se a variável de ambiente está ativada, execute o seguinte comando:

 echo $KUBECTL_REMOTE_COMMAND_WEBSOCKETS`

Se a variável não estiver definida, ative-a definindo a seguinte variável de ambiente:

export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

O kubectl versão 1.30 e mais recentes não exige essa flag, porque ela é ativada por padrão.

A versão do kubectl anterior à 1.29 não funciona com esse recurso.

Permissões do IAM ausentes

Se você receber a mensagem error: error reading from error stream..., 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.

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

Permissões RBAC necessárias ausentes

Se a mensagem de erro nos registros do agente do Connect contiver 403 Forbidden, isso indica que você não tem permissões de RBAC. Você tem um conjunto de permissões do RBAC no cluster para executar esses comandos kubectl. Consulte a seção Políticas de RBAC para configurar as permissões de RBAC necessárias.

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: 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 cerca de 5 a 10 minutos da sessão ativa, essa é uma limitação esperada do recurso. A conexão precisa ser restabelecida.

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