Pré-requisitos para registrar um cluster

Nesta página, descrevemos os pré-requisitos e requisitos para registrar um cluster do Kubernetes com o Google Cloud, incluindo a configuração de rede, do Google Cloud e do Kubernetes, bem como os requisitos de recursos do agente do Connect.

Resumo

A seguir, estão todos necessários para registrar um cluster, incluindo a garantia de que você tem os papéis relevantes de controle de acesso (RBAC, na sigla em inglês) do IAM e do Kubernetes.

  1. Ative as APIs necessárias no seu projeto do Google Cloud:
  2. Verifique a conectividade de rede para acessar a API do Google Cloud e os endpoints do serviço. Se você estiver registrando um cluster do GKE em execução no Google Cloud, isso será feito por padrão.

  3. Configuração do Google Cloud

  4. Configuração do Kubernetes

Ative as APIs

É preciso ativar as seguintes APIs no projeto do Google Cloud:

  • container.googleapis.com
  • gkeconnect.googleapis.com
  • gkehub.googleapis.com
  • cloudresourcemanager.googleapis.com

Os pods no cluster precisam ser capazes de acessar os endereços googleapis.com e gkeconnect.googleapis.com, seja diretamente ou usando um servidor proxy configurado.

Se você quiser registrar o cluster usando a identidade da carga de trabalho, também precisará ativar o seguinte:

  • iam.googleapis.com

Os proprietários que não são do projeto precisam receber a permissão serviceusage.services.enable antes de ativar APIs.

Para ativar essas APIs, execute o seguinte comando:

gcloud

gcloud services enable \
 --project=[HUB_PROJECT_ID] \
 container.googleapis.com \
 gkeconnect.googleapis.com \
 gkehub.googleapis.com \
 cloudresourcemanager.googleapis.com

onde:

Para listar as APIs ativadas nos projetos, siga as instruções em Como listar serviços na documentação do Service Usage.

Garantir conectividade de rede

Para registrar seu cluster, verifique se os domínios abaixo estão acessíveis com seu cluster do Kubernetes. Se você estiver registrando um cluster do GKE em execução no Google Cloud, isso será feito por padrão.

  • cloudresourcemanager.googleapis.com resolve os metadados referentes ao projeto do Google Cloud a que o cluster está sendo conectado.
  • oauth2.googleapis.com para receber tokens OAuth de curta duração para operações de agente em gkeconnect.googleapis.com.
  • gkeconnect.googleapis.com para estabelecer o canal usado para receber solicitações do Google Cloud e enviar respostas.
  • gkehub.googleapis.com para criar recursos de assinatura do hub do Google Cloud que correspondam ao cluster que você está conectando ao Google Cloud.
  • www.googleapis.com para autenticar tokens de serviço das solicitações de serviço recebidas do Google Cloud.
  • gcr.io para extrair a imagem do agente do GKE Connect.

Para registrar o cluster usando a identidade da carga de trabalho, os seguintes domínios também precisam ser acessíveis:

  • securetoken.googleapis.com
  • iamcredentials.googleapis.com
  • sts.googleapis.com

Se você estiver usando um proxy para o Connect, também será necessário atualizar a lista de permissões do proxy com esses domínios.

Se você usa o gcloud para registrar o cluster do Kubernetes, esses domínios também precisam ser acessados no ambiente em que você executa os comandos do gcloud.

Como usar VPC Service Controls

Se você quiser usar o VPC Service Controls para aumentar a segurança dos dados no aplicativo, será preciso garantir que os seguintes serviços estejam no perímetro do serviço:

  • API Resource Manager (cloudresourcemanager.googleapis.com)
  • API GKE Connect (gkeconnect.googleapis.com)
  • API GKE Hub (gkehub.googleapis.com)

Se você estiver usando a identidade da carga de trabalho para registrar o cluster, também precisará dos seguintes serviços:

  • API IAM Service Account Credentials (iamcredentials.googleapis.com)
  • API Security Token Service (sts.googleapis.com)

Também é necessário configurar a conectividade particular para acessar as APIs relevantes. Saiba como fazer isso em Configurar a conectividade particular.

Configuração e definição do Google Cloud

Instale o Cloud SDK

Instale o SDK do Cloud, que inclui o gcloud, a interface de linha de comando (CLI) do Google Cloud.

Autorize o gcloud a acessar o Google Cloud

Depois de instalar o SDK do Cloud, execute o seguinte comando para fazer login no Google Cloud:

gcloud auth login

Instalar o gcloud beta (opcional)

Instale o componente gcloud beta, se você planeja testar recursos Alfa ou Beta do Connect:

 gcloud components install beta 

Conceder os papéis necessários do IAM ao usuário que registra o cluster

Ter roles/owner no seu projeto oferece controle total e permite concluir as tarefas de registro.

Se você não tiver roles/owner em seu projeto, será necessário receber papéis específicos do IAM antes de conectar clusters ao Google. Consulte Conectar papéis do IAM.

Os papéis do IAM a seguir garantem que você possa registrar e se conectar a clusters usando uma conta de serviço:

  • roles/gkehub.admin
  • roles/iam.serviceAccountAdmin
  • roles/iam.serviceAccountKeyAdmin
  • roles/resourcemanager.projectIamAdmin

Somente para clusters do GKE, também é possível adicionar o papel a seguir para receber permissões de administrador no cluster, caso ainda não tenha feito isso. É provável que a conta de usuário tenha acesso a ele, caso tenha sido criado:

  • roles/container.admin

Para clusters do GKE, esse papel do IAM inclui o controle de acesso baseado em papéis (RBAC, na sigla em inglês) do Kubernetes.cluster-admin usuário. Para outros ambientes de cluster, você precisa conceder esse papel do RBAC usando kubectl, conforme descrito em Configuração do Kubernetes. Saiba mais sobre a relação entre os papéis de IAM e RBAC no GKE na documentação do GKE.

Se você estiver registrando um cluster usando a Identidade da carga de trabalho, basta ter o seguinte papel do IAM:

  • roles/gkehub.admin

gcloud

gcloud projects add-iam-policy-binding [HUB_PROJECT_ID] \
 --member user:[GCP_EMAIL_ADDRESS] \
 --role=roles/gkehub.admin \
 --role=roles/iam.serviceAccountAdmin \
 --role=roles/iam.serviceAccountKeyAdmin \
 --role=roles/resourcemanager.projectIamAdmin

onde:

  • [HUB_PROJECT_ID] é o ID do projeto do Google Cloud em que você quer registrar clusters. Saiba como encontrar esse valor.
  • [GCP_EMAIL_ADDRESS] é o registro de conta usado pelos usuários para fazer login no Google Cloud.

Para saber mais sobre como conceder papéis do IAM, consulte Como conceder, alterar e revogar o acesso a recursos na documentação do IAM.

Conceder papéis somente leitura a outros usuários

Os usuários autenticados com os papéis a seguir podem visualizar clusters de usuário registrados no Console do Cloud. Estes papéis fornecem acesso somente leitura:

  • roles/gkehub.viewer
  • roles/container.viewer

Por exemplo, para conceder ao usuário os papéis roles/gkehub.viewer e roles/container.viewer, execute o comando a seguir:

gcloud

gcloud projects add-iam-policy-binding [HUB_PROJECT_ID] \
 --member user:[USER_EMAIL_ADDRESS] \
 --role roles/gkehub.viewer \
 --role=roles/container.viewer

onde:

  • [HUB_PROJECT_ID] é o ID do projeto do Google Cloud em que você quer registrar clusters. Saiba como encontrar esse valor.
  • [USER_EMAIL_ADDRESS] é o endereço de e-mail de usuários autenticados.

Configurar identidade

Todas as opções de registro de cluster manual exigem que você especifique uma identidade para o agente do Connect usar ao autenticar no Google. Geralmente, essa é uma conta de serviço do Google Cloud, a menos que você esteja registrando um cluster do GKE usando a identidade da carga de trabalho.

Criar uma conta de serviço do Google Cloud usando gcloud

Para registrar manualmente um cluster usando uma conta de serviço do Google Cloud, você precisa de um arquivo JSON contendo as credenciais da conta de serviço. Para seguir o princípio do menor privilégio, recomendamos que você crie uma conta de serviço distinta para cada cluster do Kubernetes registrado e vincule os papéis do IAM a ela no cluster correspondente.

Para criar esse arquivo, execute as seguintes etapas:

gcloud

Execute o seguinte comando para criar uma conta de serviço:

gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] --project=[HUB_PROJECT_ID]

Liste todas as contas de serviço de um projeto executando o seguinte comando:

gcloud iam service-accounts list --project=[HUB_PROJECT_ID]

Se você estiver criando uma conta de serviço distinta para cada cluster do Kubernetes registrado, vincule o papel do GKE gkehub.connect à conta de serviço do cluster correspondente a uma Condição do IAM no nome da assinatura do cluster:

MEMBERSHIP_NAME=[MEMBERSHIP_NAME]
HUB_PROJECT_ID=[HUB_PROJECT_ID]
SERVICE_ACCOUNT_NAME=[SERVICE_ACCOUNT_NAME]
gcloud projects add-iam-policy-binding ${HUB_PROJECT_ID} \
 --member="serviceAccount:${SERVICE_ACCOUNT_NAME}@${HUB_PROJECT_ID}.iam.gserviceaccount.com" \
 --role="roles/gkehub.connect" \
 --condition "expression=resource.name == \
'projects/${HUB_PROJECT_ID}/locations/global/memberships/${MEMBERSHIP_NAME}',\
title=bind-${SERVICE_ACCOUNT_NAME}-to-${MEMBERSHIP_NAME}"

Caso contrário, vincule o papel à conta de serviço para todos os clusters no projeto sem a condição.

HUB_PROJECT_ID=[HUB_PROJECT_ID]
gcloud projects add-iam-policy-binding ${HUB_PROJECT_ID} \
 --member="serviceAccount:[SERVICE_ACCOUNT_NAME]@${HUB_PROJECT_ID}.iam.gserviceaccount.com" \
 --role="roles/gkehub.connect"

Faça o download do arquivo JSON da chave privada da conta de serviço. Você usa esse arquivo ao registrar um cluster:

HUB_PROJECT_ID=[HUB_PROJECT_ID]
gcloud iam service-accounts keys create [LOCAL_KEY_PATH] \
  --iam-account=[SERVICE_ACCOUNT_NAME]@${HUB_PROJECT_ID}.iam.gserviceaccount.com \
  --project=${HUB_PROJECT_ID}

onde:

  • [HUB_PROJECT_ID] é o ID do projeto do Google Cloud em que você quer registrar clusters. Saiba como encontrar esse valor.
  • [SERVICE_ACCOUNT_NAME] é o nome de exibição escolhido para a conta de serviço.
  • [MEMBERSHIP_NAME] é o nome da assinatura que você escolhe para representar o cluster de maneira exclusiva enquanto o registra.
  • [LOCAL_KEY_PATH] é um caminho de arquivo local onde você quer salvar a chave privada da conta de serviço, um arquivo JSON. Recomendamos que você nomeie o arquivo usando o nome da conta de serviço e o ID do projeto, como: /tmp/creds/[SERVICE_ACCOUNT_NAME]-[HUB_PROJECT_ID].json

Ativar a Identidade da carga de trabalho

Para clusters do GKE, é possível optar por registrar o cluster usando a identidade da carga de trabalho em vez de uma conta de serviço. Você precisa garantir que a identidade da carga de trabalho do GKE esteja ativada no cluster antes do registro. Registrar um cluster usando a Identidade da carga de trabalho sem ter a Identidade da carga de trabalho do GKE ativada no cluster pode causar inconsistências na forma como a identidade é declarada por cargas de trabalho no cluster, além de não ser uma configuração compatível. Saiba mais sobre as vantagens do registro usando a Identidade da carga de trabalho em Como registrar um cluster.

Para verificar se o cluster tem a Identidade da carga de trabalho ativada, execute o seguinte comando para listar o pool de Identidade da carga de trabalho do cluster:

gcloud container clusters describe GKE_CLUSTER --format="value(workloadIdentityConfig.workloadPool)"

Substitua:

  • GKE_CLUSTER: o name do cluster do GKE.

Se aparecer um resultado semelhante ao seguinte, a Identidade da carga de trabalho já estará ativada no cluster do GKE.

GKE_PROJECT_ID.svc.id.goog

Se não houver resultados, a identidade da carga de trabalho não será ativada. Para ativar a Identidade da carga de trabalho, siga as instruções em Como ativar a Identidade da carga de trabalho.

Como registrar um cluster do GKE em um projeto diferente

Na primeira vez que você registrar um cluster do GKE no projeto (GKE_PROJECT) para um projeto diferente (HUB_PROJECT), primeiro conceda as permissões necessárias. A conta de serviço padrão HUB_PROJECT gcp-sa-gkehub requer o papel Agente de serviço do hub no projeto GKE_PROJECT. O Agente de serviço do hub é um papel do IAM que concede à conta de serviço as permissões para gerenciar recursos de cluster.

Confirme se gcp-sa-gkehub tem o papel necessário usando a ferramenta gcloud ou o Console do Cloud. Se o comando ou o painel não exibe gcp-sa-gkehub, isso significa que o papel necessário está ausente. Se você vir gcp-sa-gkehub, ele terá o formato service-[HUB-PROJECT-NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com.

gcloud

Execute este comando:

gcloud projects get-iam-policy [GKE_PROJECT_ID]

Para conceder o papel gcp-sa-gkehub Agente de serviço do Hub, primeiro é necessário garantir que a conta de serviço padrão do Hub existe. Se você já registrou clusters neste projeto antes, a conta de serviço já deve existir.

Para criar gcp-sa-gkehub, execute o seguinte comando:

gcloud beta services identity create --service=gkehub.googleapis.com --project=[HUB_PROJECT_ID]

Esse comando gera o resultado a seguir:

Service identity created: service-[HUB_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com

Quando a conta de serviço gcp-sa-gkehub existir, execute o seguinte comando para conceder a ela o papel roles/gkehub.serviceAgent:

GKE_PROJECT_ID=[GKE_PROJECT_ID]
HUB_PROJECT_ID=[HUB_PROJECT_ID]
HUB_PROJECT_NUMBER=$(gcloud projects describe "${HUB_PROJECT_ID}" --format "value(projectNumber)")
gcloud projects add-iam-policy-binding "${HUB_PROJECT_ID}" \
--member "serviceAccount:service-${HUB_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
--role roles/gkehub.serviceAgent
gcloud projects add-iam-policy-binding "${GKE_PROJECT_ID}" \
--member "serviceAccount:service-${HUB_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
--role roles/gkehub.serviceAgent

onde:

  • [GKE_PROJECT_ID] é o ID do projeto do Google Cloud do cluster do GKE.
  • [HUB_PROJECT_ID] é o ID do projeto do Google Cloud em que você quer registrar clusters. Saiba como encontrar esse valor.

Para confirmar se a vinculação de papel foi concedida:

  gcloud projects get-iam-policy [GKE_PROJECT_ID]
  

Se o nome da conta de serviço estiver com a função gkehub.serviceAgent, a vinculação de papel foi concedida. Exemplo:

  - members:
    - serviceAccount:service-[HUB_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com
    role: roles/gkehub.serviceAgent

Configuração e definição do Kubernetes

Instalar o kubectl

.

Recomendamos instalar o kubectl com o SDK do Cloud.

Para verificar a versão do kubectl:

kubectl version

A versão do cliente é indicada por "gitVersion" da saída.

Para instalar o kubectl:

gcloud components install kubectl

Conceder o papel RBAC de administrador do cluster ao usuário que o registra

O é um controle de acesso baseado em papéis (RBAC, na sigla em inglês) do cluster-admin. Ele concede a você as permissões necessárias para conectar os clusters ao Google. Se o cluster que você quer registrar estiver no Google Cloud, será possível conseguir as mesmas permissões usando o papel roles/container.admin do IAM, conforme descrito em Configuração do Google Cloud e configuração.

Se você criou o cluster, é provável que já tenha esse papel. Para verificar, execute o seguinte comando:

kubectl auth can-i '*' '*' --all-namespaces

Se você ou outro usuário precisar do papel, crie um recurso "ClusterRoleBinding" no cluster:

kubectl create clusterrolebinding [BINDING_NAME] --clusterrole cluster-admin --user [USER] 

onde:

  • [BINDING_NAME] é um nome que você escolhe para o recurso "ClusterRoleBinding";
  • [USER] é a identidade usada para se autenticar no cluster.

Para mais informações sobre o papel cluster-admin, consulte a documentação do Kubernetes.

Como usar controles de admissão

Como parte do registro do cluster no Google Cloud, o agente do Connect é instalado no cluster. Dependendo da plataforma de contêiner e do controlador de admissão, talvez seja necessário criar políticas de admissão que permitam a instalação do agente.

Políticas de segurança de pods (PSP)

Uma PodSecurityPolicy é um recurso controlador de admissão opcional que valida solicitações para criar e atualizar pods no cluster. As políticas de segurança de pods são aplicadas somente quando o plug-in do controlador de admissão da PSP está ativado.

Se o cluster usar o plug-in do controlador de admissão da PSP, não será necessário criar políticas adicionais para usar o agente do Connect, porque políticas específicas do agente do Connect e os papéis do RBAC são instalados automaticamente como parte do registro do cluster.

Use os seguintes comandos para finalizar a política de PSP e RBACs instalados:

$ kubectl get psp | grep connect
$ kubectl get role,rolebindings -n gke-connect | grep psp

Restrições de contexto de segurança (SCC, na sigla em inglês)

Nos clusters OpenShift OKE e OKD, os administradores podem usar SCCs para controlar as permissões dos pods. Para permitir a instalação do agente do Connect no cluster, você precisa criar uma SCC personalizada.

A amostra de definição de SCC a seguir especifica o conjunto de condições que o agente do Connect precisa executar para ser aceito no cluster:

# Connect Agent SCC
apiVersion: v1
kind: SecurityContextConstraints
metadata:
  name: gke-connect-scc
allowPrivilegeEscalation: false
# This is redundant with non-root + disallow privilege escalation,
# but we provide it for defense in depth.
requiredDropCapabilities:
- ALL
runAsUser:
  type: MustRunAsNonRoot
seLinuxContext:
  type: RunAsAny
supplementalGroups:
  type: MustRunAs
  ranges:
  - min: 1
    max: 65535
fsGroup:
  type: MustRunAs
  ranges:
  - min: 1
    max: 65535
volumes:
- secret
readOnlyRootFilesystem: true
seccompProfiles:
- docker/default
users:
groups:
  # Grants all service accounts in the gke-connect namespace access to this SCC
  - system:serviceaccounts:gke-connect

Supondo que você salvou a definição de SCC como gke-connect-scc.yaml, use a ferramenta de linha de comando oc do OpenShift para criar a SCC gke-connect-scc para o cluster da seguinte maneira:

$ oc create -f gke-connect-scc.yaml

Para verificar se a SCC personalizada foi criada, execute o seguinte comando oc:

$ oc get scc | grep gke-connect-scc

Uso de recursos e requisitos

Normalmente, o agente do Connect instalado no registro usa 500 m de CPU e 200 Mi de memória. No entanto, esse uso pode variar dependendo do número de solicitações feitas ao agente por segundo e do tamanho dessas solicitações. Isso pode ser afetado por vários fatores, incluindo o tamanho do cluster, o número de usuários que acessam o cluster pelo Console do Cloud (quanto mais usuários e/ou cargas de trabalho, mais solicitações) e o número de recursos ativados pelo ambiente no cluster.

A seguir