Usar o gateway do Connect

Esta página explica como usar o gateway Connect para se ligar a um cluster registado. Antes de ler esta página, certifique-se de que conhece os conceitos na nossa vista geral. Este guia pressupõe que o administrador do projeto já configurou a entrada e lhe atribuiu as funções e as autorizações necessárias.

Antes de começar

  • Certifique-se de que tem as seguintes ferramentas de linha de comandos instaladas:

    Se estiver a usar o Cloud Shell como ambiente de shell para interagir com o Google Cloud, estas ferramentas são instaladas automaticamente.

  • Certifique-se de que inicializou a CLI gcloud para utilização com o seu projeto.

Inicie sessão na sua Google Cloud conta

Pode usar a sua própria conta Google Cloud ou uma Google Cloud conta de serviço para interagir com clusters ligados através da Gateway API.

Siga as instruções em Autorizar ferramentas da CLI Google Cloud para iniciar sessão na sua conta de utilizador. A gateway Connect suporta a representação de contas de serviço, pelo que, mesmo que tenha sessão iniciada na sua própria conta de utilizador, pode usar uma conta de serviço para interagir com clusters, como verá nas secções seguintes.

Selecione um cluster registado

Se não souber o nome do cluster ao qual quer aceder, pode ver todos os clusters registados da sua frota atual executando o seguinte comando:

gcloud container fleet memberships list

Esta página apresenta todos os clusters da sua frota, incluindo os respetivos nomes de associação e IDs externos. Cada cluster numa frota tem um nome de associação único. Para clusters do GKE, o nome da associação corresponde geralmente ao nome que lhe atribuiu quando criou o cluster, a menos que o nome do cluster não fosse único no respetivo projeto no momento do registo.

Obtenha o gateway do cluster kubeconfig

Use o seguinte comando para obter o kubeconfig de que precisa para interagir com o cluster especificado:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Substitua MEMBERSHIP_NAME pelo nome da associação da frota do cluster.

Este comando devolve um Connect gateway-specific kubeconfig especial que lhe permite ligar-se ao cluster através do Connect gateway.

Se quiser usar uma conta de serviço em vez da sua própria Google Cloud conta, use gcloud config para definir auth/impersonate_service_account para o endereço de email da conta de serviço.

Para obter a credencial do cluster usada para interagir com o gateway do Connect através de uma conta de serviço, execute os seguintes comandos: Tenha em atenção o seguinte:

  • Clusters do Google Distributed Cloud (apenas software) em bare metal e VMware: o nome da associação é igual ao nome do cluster.

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

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

Pode saber mais sobre como permitir que os utilizadores se façam passar por uma conta de serviço em Gerir o 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 email da conta de serviço. Pode saber mais sobre como permitir que os utilizadores se façam passar por uma conta de serviço em Gerir o acesso às contas de serviço.

Executar comandos no cluster

Quando tiver as credenciais necessárias, pode executar comandos através do kubectl ou de um go-client, como faria normalmente para qualquer cluster do Kubernetes. O resultado deve ter um aspeto semelhante ao seguinte:

# 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 do kubectl são comandos de streaming e têm requisitos adicionais:

  • attach
  • cp
  • exec
  • port-forward

Tenha em atenção os seguintes requisitos:

  • Os clusters têm de estar na versão 1.30 ou posterior para os comandos attach, cp e exec, e na versão 1.31 ou posterior para o comando port-forward.

  • O cliente kubectl tem de ter a versão 1.31 ou posterior.

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

Os utilizadores e as contas de serviço com a roles/gkehub.gatewayAdminfunção de IAM e o cluster-admin ClusterRole têm as autorizações necessárias para executar os comandos attach, cp, exec e port-forward. Se os utilizadores e as contas de serviço tiverem recebido uma função do IAM personalizada ou uma função do RBAC personalizada, pode ter de conceder autorizações adicionais. Consulte as secções seguintes para ver informações adicionais.

Conceda uma autorização adicional, se necessário

A autorização de IAM gkehub.gateway.stream é necessária para executar os comandos attach, cp, exec e port-forward através do gateway Connect. Esta autorização está incluída no roles/gkehub.gatewayAdmin.

Para utilizadores que não sejam proprietários do projeto ou para utilizadores ou contas de serviço aos quais não tenha sido concedida a função roles/gkehub.gatewayAdmin no projeto, tem de lhes conceder a função roles/gkehub.gatewayAdmin ou criar uma função personalizada que inclua as outras funções necessárias e a autorização gkehub.gateway.stream. Para obter informações sobre como criar uma função personalizada, consulte o artigo Crie e faça a gestão de funções personalizadas na documentação do IAM.

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

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

No mínimo, são necessárias as seguintes regras 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

Resolução de problemas

Se estiver a ter problemas ao estabelecer ligação a um cluster através do gateway, pode verificar os seguintes problemas comuns, ou o seu administrador pode fazê-lo.

  • O servidor não tem um tipo de recurso: pode ver esta mensagem de erro quando o comando kubectl get ns falha. Existem vários motivos potenciais para este erro. Execute os seus comandos kubectl no modo de verbosidade para ver mais detalhes, por exemplo, kubectl get ns -v 10.
  • Não é possível encontrar ligações ativas para o cluster(projeto: 12345, associação: my-cluster): pode ver este erro quando o agente Connect perde a conetividade ou não está instalado corretamente (apenas clusters externos Google Cloud ). Para resolver este problema, tem de verificar se o espaço de nomes gke-connect existe no cluster. Se o espaço de nomes gke-connect existir no cluster, consulte a página de resolução de problemas de ligação para corrigir os problemas de conetividade.
  • Não foi possível encontrar o URL pedido neste servidor: pode ver este erro quando o kubeconfig contém um endereço de servidor incorreto. Certifique-se de que a versão da CLI Google Cloud que está a usar é a mais recente e tente novamente gerar o gateway kubeconfig. Não edite manualmente o ficheiro kubeconfig, pois isso causa erros inesperados.
  • A identidade do utilizador não tem autorizações suficientes para usar a API de gateway: precisa da função roles/gkehub.gatewayAdmin roles/gkehub.gatewayReader ou roles/gkehub.gatewayEditor para usar a API. Consulte o artigo Conceda funções de IAM aos utilizadores no guia de configuração da gateway para mais detalhes.
  • O agente Connect não está autorizado a enviar os pedidos do utilizador: o agente Connect tem de ter autorização para encaminhar pedidos em seu nome, o que é especificado através de uma política de roubo de identidade no cluster. Consulte o artigo Configure a autorização RBAC no guia de configuração do gateway para ver um exemplo de como adicionar um utilizador à função gateway-impersonate.
  • A identidade do utilizador não tem autorizações RBAC suficientes para realizar a operação: tem de ter as autorizações adequadas no cluster para executar as operações escolhidas. Consulte a secção Configure a autorização RBAC no guia de configuração da gateway para ver um exemplo de como adicionar um utilizador ao ClusterRole adequado.
  • A identidade do utilizador não tem autorizações suficientes para realizar a operação quando usa o Google Groups ou o apoio técnico de terceiros: consulte o artigo Recolher registos do serviço de identidade do GKE para obter instruções sobre como inspecionar registos relacionados com informações de identidade.
  • O agente do Connect não está em bom estado: consulte a página de resolução de problemas do Connect para se certificar de que o cluster está ligado.
  • executable gke-gcloud-auth-plugin not found ou no Auth Provider found for name gcp: as versões 1.26 e posteriores do kubectl podem apresentar este erro devido a alterações à autenticação do kubectl a partir da versão 1.26 do GKE. Instale o gke-gcloud-auth-plugin e volte a executar o gcloud container fleet memberships get-credentials MEMBERSHIP_NAME com a versão mais recente da Google Cloud CLI.

  • As ligações ao gateway falham com versões mais antigas da CLI gcloud: para clusters do GKE, o agente Connect já não é necessário para o funcionamento do gateway, pelo que não é instalado por predefinição durante o registo de membros. As versões anteriores da CLI Google Cloud (399.0.0 e inferiores) pressupõem a existência do agente Connect no cluster. A tentativa de usar o gateway com estas versões anteriores pode falhar em clusters registados com uma versão mais recente da CLI do Google Cloud. Para resolver este problema, atualize o cliente da CLI do Google Cloud para uma versão mais recente ou execute novamente o comando de registo de subscrição com a flag --install-connect-agent.

  • O tamanho dos grupos devolvidos no grupo gke-security-groups excede o limite de tamanho do cabeçalho HTTP de 8 KB. Reorganize a hierarquia de grupos e tente novamente: embora não exista um limite rígido para o número de grupos, os nomes de grupos longos podem fazer com que o pedido exceda o limite de tamanho do cabeçalho HTTP de 8 KB e resultem em erros que podem exigir que reestruture a hierarquia de grupos.

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

O erro devolvido pela execução do comando é frequentemente um erro 400 Bad Request genérico que não é suficientemente claro para depurar o problema. Para devolver mensagens de erro mais detalhadas, use a versão 1.32 ou posterior do cliente kubectl para executar o comando com um nível de detalhe 4 ou superior, por exemplo: kubectl exec -v 4 ....

Nos registos devolvidos, pesquise o registo 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 de algumas das mensagens de erro comuns que pode receber do comando kubectl exec -v 4 ..., consulte a secção seguinte.

Autorizações de IAM em falta

Se a mensagem de erro contiver generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource, isto pode indicar que não lhe foram concedidas as autorizações de IAM necessárias para executar o comando. Esta funcionalidade requer que os utilizadores tenham a gkehub.gateway.stream autorização do IAM, que está incluída por predefinição na função roles/gkehub.gatewayAdmin. Consulte a secção de autorizações de IAM para ver instruções.

Autorizações RBAC necessárias em falta

Se a mensagem de erro contiver ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden..., indica que não tem autorizações de RBAC. Precisa de um conjunto de autorizações RBAC no cluster para executar estes comandos kubectl. Para mais informações sobre a configuração das autorizações RBAC necessárias, consulte o artigo Crie e aplique políticas RBAC adicionais, se necessário.

Mensagem de erro generic::resource_exhausted: Gateway's active_streams quota exhausted

Existe um limite de quota de 10 streams ativas por projeto de anfitrião de frota. Esta é definida na quota connectgateway.googleapis.com/active_streams. Consulte o artigo Ver e gerir quotas para obter instruções sobre a gestão das suas quotas.

Mensagem de erro generic::failed_precondition: error encountered within the cluster

Se receber o erro generic::failed_precondition: error encountered within the cluster, verifique os registos do agente de ligação no cluster para identificar a causa subjacente:

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

O registo a procurar no agente de ligação é failed to create the websocket connection....

Mensagem de erro generic::failed_precondition: connection to Agent failed/terminated

Se encontrar este erro imediatamente ao executar o comando, existe um problema com a ligação do cluster ao Google. Consulte o guia de resolução de problemas geral para mais informações.

Se encontrar este erro depois de a sessão estar ativa durante cerca de 20 a 30 minutos, trata-se de uma limitação esperada por motivos de segurança. A ligação tem de ser restabelecida.

O que se segue?