Pré-requisitos para clusters do GKE no Google Cloud

Se você estiver registrando um cluster do GKE no Google Cloud, talvez seja necessário realizar uma ou mais das ações a seguir antes de registrar o cluster, dependendo da opção de registro escolhida. Neste guia, pressupomos que você já tenha cumprido os pré-requisitos gerais para registro de cluster.

Ativar a federação de identidade da carga de trabalho do GKE

Recomendamos registrar seus clusters do GKE com a federação de identidade da carga de trabalho da frota ativada, que oferece uma maneira consistente para aplicativos nos clusters se autenticarem nos serviços e APIs do Google Cloud. Saiba mais sobre as vantagens de ativar a federação de identidade da carga de trabalho da frota em Usar a federação de identidade da carga de trabalho da frota.

Para usar esse recurso, verifique se a federação de identidade da carga de trabalho para GKE está ativada no cluster antes do registro. Registrar um cluster do GKE com a federação de identidade da carga de trabalho da frota sem ativar a federação de identidade da carga de trabalho para GKE pode gerar inconsistências na forma como a identidade é declarada pelas cargas de trabalho no cluster e não é uma configuração aceita. Os clusters do Autopilot têm a federação de identidade da carga de trabalho do GKE ativada por padrão.

gcloud

Para verificar se o cluster está com a federação de identidade da carga de trabalho para GKE ativada, execute o seguinte comando para listar o pool de Identidade da carga de trabalho do cluster. Se você ainda não tiver especificado uma zona ou região padrão para gcloud, talvez seja necessário especificar uma sinalização --region ou --zone ao executar este comando.

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

Substitua:

CLUSTER_NAME: o name do cluster do GKE.

Se você vir um resultado semelhante ao apresentado a seguir, a federação de identidade da carga de trabalho para GKE já está ativada no seu cluster:

GKE_PROJECT_ID.svc.id.goog

Quando não há resultados, a federação de identidade da carga de trabalho para GKE não está ativada. Siga as instruções em Como ativar a federação de identidade da carga de trabalho para GKE.

Console

Para verificar se o cluster tem a federação de identidade da carga de trabalho para GKE ativada:

Acesse a página do Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na lista de clusters, clique no nome do cluster.
Na página de detalhes do cluster, na seção Segurança, confirme se a Identidade da carga de trabalho está listada como Ativada.

Se a Identidade da carga de trabalho estiver Desativada e você quiser ativar esse recurso:

Na página de detalhes do cluster, clique em Editar a Identidade da carga de trabalho.
Na caixa de diálogo Editar Identidade da carga de trabalho, marque a caixa de seleção Ativar Identidade da carga de trabalho.
Clique em Salvar alterações.

Conceder permissões para registrar um cluster em um projeto diferente

O registro de um cluster do GKE em um projeto próprio não requer permissões especiais além das descritas em Conceder permissões de acesso. Entretanto, se você quiser registrar um cluster do GKE partindo do próprio projeto (GKE_PROJECT) para uma frota em um projeto diferente (FLEET_HOST_PROJECT), a conta do agente de serviço gcp-sa-gkehub de FLEET_HOST_PROJECT precisará ter o papel gkehub.serviceAgent no projeto GKE_PROJECT. Este papel concede à conta de serviço as permissões para gerenciar recursos de cluster nesse projeto.

É possível verificar se a conta de serviço gcp-sa-gkehub do projeto host da frota tem o papel necessário no projeto do cluster usando a CLI gcloud ou o Console do Cloud, da seguinte maneira.

gcloud

Execute este comando:

gcloud projects get-iam-policy GKE_PROJECT_ID | grep gcp-sa-gkehub

em que GKE_PROJECT_ID é o ID do projeto do cluster.

Se o projeto host da frota gcp-sa-gkehub tiver os papéis necessários no projeto do cluster, ele aparecerá na saída no formato service-[FLEET_HOST-PROJECT-NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com. Exemplo:

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

Console

Com o projeto do cluster selecionado, acesse a página IAM e administrador no Console do Cloud.

Acessar a página "IAM e administrador"
Marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google para ver a política de permissão completa, incluindo os agentes de serviço.

Se a conta de serviço do projeto host da frota gcp-sa-gkehub tiver os papéis necessários no projeto do cluster, ela aparecerá nesta lista no formato service-[FLEET_HOST-PROJECT-NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com.

Se o agente de serviços não estiver listado na política de permissão do IAM do projeto, faça o seguinte para atualizar as permissões necessárias:

gcloud

Para conceder o papel gkehub.serviceAgent a gcp-sa-gkehub, primeiro verifique se essa conta de serviço existe no projeto host da frota. Se você registrou clusters neste projeto da frota antes, a conta de serviço já existe. Para verificar, consulte a política de permissão do IAM para o projeto host da frota:
```
gcloud projects get-iam-policy FLEET_HOST_PROJECT_ID | grep gcp-sa-gkehub
```

Se você precisar criar a conta de serviço gcp-sa-gkehub, execute o seguinte comando:

gcloud beta services identity create --service=gkehub.googleapis.com --project=FLEET_HOST_PROJECT_ID

Esse comando gera o resultado a seguir:

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

Execute o seguinte comando para conceder à conta de serviço o papel roles/gkehub.serviceAgent nos projetos e no roles/gkehub.crossProjectServiceAgent no projeto do cluster:

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

em que:

GKE_PROJECT_ID é o ID do projeto do Google Cloud do cluster do GKE.
FLEET_HOST_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, execute o seguinte comando novamente:

gcloud projects get-iam-policy GKE_PROJECT_ID

Quando o nome da conta de serviço é exibido com os papéis gkehub.serviceAgent e gkehub.crossProjectServiceAgent, isso significa que as vinculações de papéis foram concedidas. Exemplo:

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

Configurar uma conta de serviço para o Terraform

Se você quiser usar o Terraform para registrar um cluster do Google Kubernetes Engine, precisará criar uma conta de serviço para ele acessar a API Fleet e criar uma assinatura.

gcloud

Crie uma conta de serviço da seguinte maneira:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME --project=FLEET_HOST_PROJECT_ID

Vincule o papel gkehub.admin do IAM à conta de serviço para que o Terraform possa usá-la com a API Fleet:
```
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
   --role="roles/gkehub.admin"
```
Se você quiser criar um novo cluster com o Terraform e registrá-lo, também precisará vincular o papel roles/container.admin à conta de serviço para que o Terraform possa usar essa conta de serviço para acessar a API GKE para criar um cluster.
```
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
   --role="roles/container.admin"
```
Substitua:
- FLEET_HOST_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].
Faça o download do arquivo JSON da chave privada da conta de serviço, conforme descrito em Criar uma conta de serviço do Google Cloud usando gcloud. Você precisará desse arquivo para criar e registrar clusters usando o Terraform.

Criar uma conta de serviço para o Config Connector

Se você quiser usar o Config Connector para registrar um cluster do GKE, siga estas etapas:

gcloud

Verifique se você instalou o complemento Config Connector. É necessário ter uma versão do Config Connector acima da 1.47.0.
Siga as instruções do Config Connector para criar uma conta de serviço.
Vincule o papel de IAM gkehub.admin a esta conta de serviço para que o Config Connector possa usar essa conta de serviço para acessar a API Fleet:
```
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
   --role="roles/gkehub.admin"
```
Se você quiser criar um novo cluster com o Config Connector e registrá-lo, também precisará vincular o papel roles/container.admin à conta de serviço para que o controlador do Config Connector possa usar essa conta de serviço para acessar a API GKE e criar um cluster ,
```
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
   --role="roles/container.admin"
```
Substitua:
- FLEET_HOST_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].
Siga a instrução do Config Connector para configurar o Config Connector com essa conta de serviço.

A seguir

Siga as instruções para registrar um cluster.