Configurar contas de serviço de nós do GKE

Os nós do Google Kubernetes Engine (GKE) usam contas de serviço do Identity and Access Management (IAM) para tarefas como geração de registros e extração de imagens de contêiner para cargas de trabalho. Este documento mostra aos administradores de plataforma e engenheiros de segurança como conceder papéis a contas de serviço para casos de uso específicos e como criar contas de serviço personalizadas em vez de usar uma conta de serviço padrão. Para mais informações, consulte Contas de serviço de nós.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

• Ativar a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Se você quiser usar a CLI do Google Cloud para essa tarefa, instale e inicialize a gcloud CLI. Se você instalou a gcloud CLI anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da gcloud CLI não sejam compatíveis com a execução dos comandos neste documento.
  Observação: em instalações prévias da gcloud CLI, defina a propriedade compute/region. Se você usa principalmente clusters zonais, defina compute/zone. Ao definir um local padrão, é possível evitar erros na gcloud CLI como: One of [--zone, --region] must be supplied: Please specify location. Talvez seja necessário especificar o local em determinados comandos se o local do cluster for diferente do padrão definido.

Funções exigidas

Para ter as permissões necessárias para gerenciar contas de serviço e papéis do IAM, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Administrador de segurança (roles/iam.securityAdmin) no projeto do cluster
• Configure as contas de serviço em um projeto separado: Administrador de segurança (roles/iam.securityAdmin) no projeto da conta de serviço

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder o papel mínimo necessário para o GKE

O GKE usa contas de serviço do IAM anexadas aos nós para executar tarefas do sistema, como geração de registros e monitoramento. No mínimo, essas contas de serviço de nó precisam ter o papel Conta de serviço de nó padrão do Kubernetes Engine (roles/container.defaultNodeServiceAccount) no seu projeto. Por padrão, o GKE usa a conta de serviço padrão do Compute Engine, que é criada automaticamente no seu projeto, como a conta de serviço do nó.

Se a organização aplicar a restrição da política da organização iam.automaticIamGrantsForDefaultServiceAccounts, a conta de serviço padrão do Compute Engine no projeto talvez não receba automaticamente as permissões necessárias para o GKE.

Observação: se a organização foi criada em 3 de maio de 2024 ou depois dessa data, essa restrição será aplicada por padrão.

As seções a seguir mostram como conceder o papel roles/container.defaultNodeServiceAccount à conta de serviço padrão do Compute Engine ou a uma nova conta de serviço personalizada que você criar.

Prática recomendada:

Crie uma conta de serviço personalizada para seus nós em vez de usar a conta de serviço padrão do Compute Engine.

Configurar a conta de serviço padrão do Compute Engine

Para conceder o papel roles/container.defaultNodeServiceAccount à conta de serviço padrão do Compute Engine, siga estas etapas:

Console

1. Acesse a página Boas-vindas:

   Acessar "Boas-vindas"

2. No campo Número do projeto, clique em Copiar para a área de transferência.
3. Acesse a página do IAM:

   Acessar IAM

4. Clique em Conceder acesso.
5. No campo Novos principais, especifique o seguinte valor:

   [e-mail]

   Substitua PROJECT_NUMBER pelo número do projeto que você copiou.
6. No menu Selecionar um papel, escolha o papel Conta de serviço de nó padrão do Kubernetes Engine.
7. Clique em Salvar.

gcloud

1. Encontre o Google Cloud número do projeto:

   gcloud projects describe PROJECT_ID \
       --format="value(projectNumber)"

   Substitua PROJECT_ID pela ID do seu projeto.

   O resultado será o seguinte:

   12345678901
   

2. Conceda o papel roles/container.defaultNodeServiceAccount à conta de serviço padrão do Compute Engine:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:[e-mail]" \
       --role="roles/container.defaultNodeServiceAccount"

   Substitua PROJECT_NUMBER pelo número do projeto da etapa anterior.

Configurar uma conta de serviço de nó personalizada

Para criar uma conta de serviço personalizada e conceder a ela o papel necessário para o GKE, siga estas etapas:

Console

1. Acessar a página Contas de serviço

   Acesse as Contas de serviço

2. Clique em Criar conta de serviço.
3. Insira um nome para a conta de serviço. O campo ID da conta de serviço gera automaticamente um ID exclusivo para a conta de serviço com base no nome.
4. Clique em Criar e continuar.
5. No menu Selecionar um papel, escolha o papel Conta de serviço de nó padrão do Kubernetes Engine.
6. Clique em Concluído.

gcloud

1. Crie a conta de serviço:

   gcloud iam service-accounts create SA_NAME

   Substitua SA_NAME por um nome exclusivo que identifique a conta de serviço.

2. Conceda o papel Conta de serviço de nó padrão do Kubernetes Engine (roles/container.defaultNodeServiceAccount) à conta de serviço:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --role=roles/container.defaultNodeServiceAccount

   Substitua:

   • PROJECT_ID: o ID do projeto Google Cloud .
   • SA_NAME: o nome da conta de serviço que você criou.

Terraform

Crie uma conta de serviço do IAM e conceda a ela o papel roles/container.defaultNodeServiceAccount no projeto:

resource "google_service_account" "default" {
  account_id   = "gke-node-service-account"
  display_name = "GKE node service account"
}

data "google_project" "project" {
}

resource "google_project_iam_member" "default" {
  project = data.google_project.project.project_id
  role    = "roles/container.defaultNodeServiceAccount"
  member  = "serviceAccount:${google_service_account.default.email}"
}

Config Connector

Observação: esta etapa requer o Config Connector. Siga estas instruções para instalar o Config Connector no cluster.

1. Para criar a conta de serviço, faça o download do seguinte recurso como service-account.yaml:
   apiVersion: iam.cnrm.cloud.google.com/v1beta1
   kind: IAMServiceAccount
   metadata:
     name: [SA_NAME]
   spec:
     displayName: [DISPLAY_NAME]

   Substitua:

   • [SA_NAME]: o nome da nova conta de serviço.
   • [DISPLAY_NAME]: um nome de exibição para a conta de serviço.
2. Crie a conta de serviço:

   kubectl apply -f service-account.yaml

3. Aplique o papel roles/logging.logWriter à conta de serviço:
   1. Faça o download do seguinte recurso como policy-logging.yaml.
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-logging
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/logging.logWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      Substitua:

      • [SA_NAME]: o nome da conta de serviço.
      • [PROJECT_ID]: o ID do projeto Google Cloud .
   2. Aplique o papel à conta de serviço:

      kubectl apply -f policy-logging.yaml

4. Aplique o papel roles/monitoring.metricWriter à conta de serviço:
   1. Faça o download do seguinte recurso como policy-metrics-writer.yaml. Substitua [SA_NAME] e [PROJECT_ID] pelas suas informações.
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-metrics-writer
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/monitoring.metricWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      Substitua:

      • [SA_NAME]: o nome da conta de serviço.
      • [PROJECT_ID]: o ID do projeto Google Cloud .
   2. Aplique o papel à conta de serviço:

      kubectl apply -f policy-metrics-writer.yaml

5. Aplique o papel roles/monitoring.viewer à conta de serviço:
   1. Faça o download do seguinte recurso como policy-monitoring.yaml.
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-monitoring
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/monitoring.viewer
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      Substitua:

      • [SA_NAME]: o nome da conta de serviço.
      • [PROJECT_ID]: o ID do projeto Google Cloud .
   2. Aplique o papel à conta de serviço:

      kubectl apply -f policy-monitoring.yaml

6. Aplique o papel roles/autoscaling.metricsWriter à conta de serviço:
   1. Faça o download do seguinte recurso como policy-autoscaling-metrics-writer.yaml.
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-autoscaling-metrics-writer
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/autoscaling.metricsWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      Substitua:

      • [SA_NAME]: o nome da conta de serviço.
      • [PROJECT_ID]: o ID do projeto Google Cloud .
   2. Aplique o papel à conta de serviço:

      kubectl apply -f policy-autoscaling-metrics-writer.yaml

Também é possível usar essa conta de serviço para recursos em outros projetos. Para instruções, consulte Como ativar a representação da conta de serviço em projetos.

Permitir que os principais anexem contas de serviço personalizadas

É possível anexar uma conta de serviço personalizada ao criar um cluster ou um pool de nós. Para permitir que um principal (como um administrador da plataforma) use uma conta de serviço personalizada para criar recursos do GKE, conceda a função Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço personalizada a esse principal. Para conceder essa função, selecione uma das seguintes opções:

Console

1. No console Google Cloud , acesse a página Contas de serviço:

   Acesse as Contas de serviço

   No seletor de recursos, escolha o projeto que contém sua conta de serviço personalizada.

2. Marque a caixa de seleção da conta de serviço personalizada que você criou para usar com os nós do GKE.

3. Clique em Gerenciar acesso. O painel Gerenciar acesso é aberto.

4. Clique em adicionar conta principal. O painel Conceder acesso será aberto.

5. No campo Novos principais, especifique o principal, como um grupo de administradores.

6. No menu suspenso Selecionar um papel, escolha o papel Usuário da conta de serviço.

7. Clique em Salvar. O painel Conceder acesso será fechado.

8. Feche o painel Gerenciar acesso.

gcloud

Conceda o papel roles/iam.serviceAccountUser:

gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
    --member=PRINCIPAL \
    --role=roles/iam.serviceAccountUser

Substitua:

• SA_NAME: o nome da conta de serviço personalizada.
• SERVICE_ACCOUNT_PROJECT_ID: o ID do projeto que contém a conta de serviço personalizada.
• PRINCIPAL: o identificador principal, como user:[e-mail].

Config Connector

Observação: esta etapa requer o Config Connector. Siga as instruções de instalação para instalar o Config Connector no cluster.

Aplique o papel iam.serviceAccountUser à sua conta de serviço. Faça o download do seguinte recurso como policy-service-account-user.yaml. Substitua [SA_NAME] e [PROJECT_ID] por suas próprias informações.

apiVersion: iam.cnrm.cloud.google.com/v1beta1
kind: IAMPolicyMember
metadata:
  name: policy-service-account-user
spec:
  member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
  role: roles/iam.serviceAccountUser
  resourceRef:
    kind: Project
    name: [PROJECT_ID]

kubectl apply -f policy-service-account-user.yaml

Depois de conceder o papel à conta de serviço, esses principais poderão usar essa conta para criar clusters e pools de nós. Para mais informações, consulte os seguintes documentos:

• Criar um cluster do Autopilot
• Como criar um cluster regional
• Adicionar um pool de nós a um cluster padrão

Configurar o uso da conta de serviço em vários projetos

Se a conta de serviço do nó não estiver no mesmo projeto do cluster, os agentes de serviço no projeto do cluster vão precisar de mais permissões na conta de serviço. Para mais informações, consulte Contas de serviço de nós e agentes de serviço de projetos.

Para conceder os papéis necessários em contas de serviço de nós que não estão no projeto do cluster, siga estas etapas:

1. Para ativar a vinculação de conta de serviço entre projetos, atualize as políticas da organização.

2. Para conceder os papéis necessários na conta de serviço personalizada aos agentes de serviço no projeto do cluster, selecione uma das seguintes opções:

   Console

   1. No console Google Cloud , acesse a página Contas de serviço.

      Acesse as Contas de serviço

   2. Marque a caixa de seleção da conta de serviço personalizada que você criou para usar com nós do GKE.

   3. Clique em Gerenciar acesso. O painel Gerenciar acesso é aberto.

   4. Conceda o papel Criador de token da conta de serviço ao agente de serviço do Compute Engine no projeto do cluster:

      1. No painel Gerenciar acesso, clique em Adicionar principal. O painel Conceder acesso é aberto.

      2. No campo Novos principais, especifique o endereço de e-mail do agente de serviço do Compute Engine no projeto do cluster:

         [e-mail]
         

         Substitua CLUSTER_PROJECT_NUMBER pelo número do projeto do cluster.

      3. No menu Selecionar papel, escolha o papel Criador de token de conta de serviço.

      4. Clique em Salvar. O painel Conceder acesso será fechado.

   5. Conceda o papel de usuário da conta de serviço ao agente de serviço do GKE no projeto de cluster:

      1. No painel Gerenciar acesso, clique em Adicionar principal. O painel Conceder acesso é aberto.

      2. No campo Novos principais, especifique o endereço de e-mail do agente de serviço do GKE no projeto do cluster:

         [e-mail]
         

      3. No menu Selecionar um papel, escolha o papel Usuário da conta de serviço.

      4. Clique em Salvar. O painel Conceder acesso será fechado.

   6. Feche o painel Gerenciar acesso.

   gcloud

   1. Confira o número do projeto do cluster:

      gcloud projects describe CLUSTER_PROJECT_ID \
          --format='value(projectNumber)'
      

      Substitua CLUSTER_PROJECT_ID pelo ID do projeto do cluster.

      A saída é semelhante a 123456789.

   2. Conceda o papel roles/iam.serviceAccountTokenCreator na conta de serviço personalizada ao agente de serviço do Compute Engine no projeto do cluster:

      gcloud iam service-accounts add-iam-policy-binding \
          SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
          --member=[e-mail] \
          --role=roles/iam.serviceAccountTokenCreator
      

      Substitua:

      • SA_NAME: o nome da conta de serviço personalizada.
      • SERVICE_ACCOUNT_PROJECT_ID: o ID do projeto que contém sua conta de serviço personalizada.
      • CLUSTER_PROJECT_NUMBER: o número do projeto do cluster.

   3. Conceda o papel roles/iam.serviceAccountUser na conta de serviço personalizada ao agente de serviço do GKE no projeto do cluster:

      gcloud iam service-accounts add-iam-policy-binding \
          SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
          --member=[e-mail] \
          --role=roles/iam.serviceAccountUser
      

Permitir extrações de imagens de repositórios particulares

Se você tiver imagens em repositórios particulares do Artifact Registry, conceda à conta de serviço do nó acesso a esses repositórios. Mesmo que você use a conta de serviço padrão do Compute Engine, talvez seja necessário dar acesso a ela ao repositório se ele estiver em outro projeto.

Observação: as etapas nesta seção dão acesso ao repositório apenas à conta de serviço do nó. As cargas de trabalho no cluster não recebem esse acesso. Para dar às suas cargas de trabalho do GKE acesso aos recursos do Google Cloud , use a federação de identidade da carga de trabalho para o GKE.

Para extrair imagens particulares do Artifact Registry, conceda o papel de leitor do Artifact Registry (roles/artifactregistry.reader) no repositório à conta de serviço do nó.

Console

1. No console do Google Cloud , acesse a página Repositórios.

   Acessar repositórios

2. Marque a caixa de seleção do seu repositório.

3. Clique em Mostrar painel de informações. O painel de informações do repositório é aberto.

4. Na guia Permissões, clique em Adicionar principal. O painel Conceder acesso será aberto.

5. No campo Novos principais, especifique o endereço de e-mail da conta de serviço do nó.

6. Clique em Selecionar um papel para abrir a caixa de diálogo de seleção de papel.

7. Selecione o papel Leitor do Artifact Registry.

8. Clique em Salvar.

gcloud

Conceda o papel roles/artifactregistry.reader no repositório:

gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --project=REPOSITORY_PROJECT_ID \
    --role=roles/artifactregistry.reader

Substitua:

• REPOSITORY_NAME: o nome do repositório do Artifact Registry.
• SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço do nó.
• REPOSITORY_PROJECT_ID: o ID do projeto que contém seu repositório.

Config Connector

Observação: esta etapa requer o Config Connector. Siga estas instruções para instalar o Config Connector no cluster.

Observação: estas etapas pressupõem que você usa o Config Connector para gerenciar seu repositório do Artifact Registry. Se o repositório não existir como um recurso do Config Connector, essas etapas não funcionarão.

1. Salve o seguinte manifesto como policy-artifact-registry-reader.yaml:

   apiVersion: iam.cnrm.cloud.google.com/v1beta1
   kind: IAMPolicyMember
   metadata:
     name: policy-artifact-registry-reader
   spec:
     member: serviceAccount:"SA_NAME"@"PROJECT_ID".iam.gserviceaccount.com
     role: roles/artifactregistry.reader
     resourceRef:
       apiVersion: artifactregistry.cnrm.cloud.google.com/v1beta1
       kind: ArtifactRegistryRepository
       name: "REPOSITORY_NAME"

   Substitua:

   • SA_NAME: o nome da conta de serviço do IAM.
   • PROJECT_ID: o ID do projeto Google Cloud .
   • REPOSITORY_NAME: o nome do repositório do Artifact Registry.

2. Conceda o papel de leitor do Artifact Registry à conta de serviço:

   kubectl apply -f policy-artifact-registry-reader.yaml
   

A seguir

• Criar um cluster do Autopilot
• Criar um cluster regional
• Adicionar um pool de nós a um cluster padrão