Usar o complemento Secret Manager com o Google Kubernetes Engine

A integração entre o Secret Manager e o Google Kubernetes Engine (GKE) permite armazenar dados sensíveis, como senhas e certificados usados pelos clusters do GKE, como segredos no Secret Manager.

Esta página explica como usar o complemento do Secret Manager para acessar os secrets armazenados no Secret Manager como volumes montados em pods do Kubernetes.

Esse processo envolve as seguintes etapas:

1. Ative o complemento Secret Manager em um cluster do GKE novo ou atual.
2. Configure os aplicativos para autenticação na API Secret Manager.
3. Defina quais segredos serão montados nos pods do Kubernetes usando um arquivo YAML SecretProviderClass.
4. Crie um volume em que os secrets serão montados. Depois que o volume é anexado, os aplicativos no contêiner podem acessar os dados no sistema de arquivos do contêiner.

O complemento do Secret Manager é derivado do driver CSI do Secrets Store do Kubernetes de código aberto e do provedor do Google Secret Manager. Se você estiver usando o driver CSI do Secrets Store de código aberto para acessar secrets, migre para o complemento do Secret Manager. Para mais informações, consulte Migrar do driver CSI da Secrets Store.

Importante: este documento usa o termo secret para se referir a dados sensíveis armazenados no Secret Manager, e não ao objeto Secret na API do GKE.

Vantagens

O complemento do Secret Manager oferece os seguintes benefícios:

• É possível usar uma solução totalmente gerenciada e com suporte para acessar segredos do Secret Manager no GKE sem qualquer sobrecarga operacional.
• Não é necessário escrever um código personalizado para acessar os secrets armazenados no Secret Manager.
• É possível armazenar e gerenciar todos os seus secrets de forma centralizada no Secret Manager e acessar seletivamente os secrets dos pods do GKE usando o complemento do Secret Manager. Ao fazer isso, você pode usar os recursos oferecidos pelo Secret Manager, como a criptografia CMEK, o controle de acesso refinado, a rotação gerenciada, o gerenciamento de ciclo de vida e os registros de auditoria, além de usar recursos do Kubernetes, como a transmissão de segredos para contêineres na forma de volumes montados.
• O complemento Secret Manager é compatível com clusters padrão e do Autopilot.
• O complemento do Secret Manager oferece suporte a nós que usam o Container-Optimized OS ou imagens de nó do Ubuntu.

Limitações

O complemento do Secret Manager tem as seguintes limitações:

• O complemento do Secret Manager não oferece suporte aos seguintes recursos que estão disponíveis no driver CSI da Secrets Store de código aberto:

  • Rotação automática de secrets
  • Sincronizar como secret do Kubernetes

• O complemento do Secret Manager não é compatível com nós do Windows Server.

Antes de começar

• Enable the Secret Manager and Google Kubernetes Engine APIs.

  Enable the APIs

• Se você quiser usar a Google Cloud CLI para essa tarefa, instale e inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update.

  Não é possível configurar manualmente o complemento do Secret Manager usando o SDK ou o console do Google Cloud.

  Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como o seguinte: One of [--zone, --region, --location] must be supplied: Please specify location.

• Verifique se o cluster executa o GKE versão 1.27.14-gke.1042001 ou mais recente com uma imagem de nó do Linux.

• Se você usa um cluster do GKE Standard, verifique se a federação de identidade da carga de trabalho para o GKE está ativada. A federação de identidade da carga de trabalho para o GKE é ativada por padrão em um cluster do Autopilot. Os pods do Kubernetes usam a federação de identidade da carga de trabalho para o GKE para autenticar na API Secret Manager.

Ativar o complemento do Secret Manager

É possível ativar o complemento Secret Manager nos clusters padrão e Autopilot.

Ativar o complemento Secret Manager em um novo cluster do GKE

Para ativar o complemento do Secret Manager na criação do cluster, faça o seguinte:

Console

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

   Acessar o Google Kubernetes Engine

2. Clique em Criar.

3. Na caixa de diálogo Criar cluster, clique em Configurar.

4. No menu de navegação, na seção Cluster, clique em Segurança.

5. Marque a caixa de seleção Ativar o Gerenciador de secrets.

6. Marque a caixa de seleção Ativar identidade de carga de trabalho.

7. Continue configurando o cluster e clique em Criar.

gcloud

{ Standard cluster}

Para ativar o complemento do Secret Manager em um novo cluster padrão, execute o seguinte comando:

Antes de usar os dados do comando abaixo, faça estas substituições:

• CLUSTER_NAME: o nome do cluster.
• LOCATION: a região do Compute Engine para o cluster, como us-central1.
• VERSION: a versão específica do GKE que você quer usar. Verifique se o cluster executa o GKE versão 1.27.14-gke.1042001 ou mais recente. Se o canal de lançamento padrão não incluir essa versão, use a flag --release-channel para escolher um canal de lançamento que a inclua.
• PROJECT_ID: o ID do seu projeto do Google Cloud.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters create CLUSTER_NAME \
    --enable-secret-manager \
    --location=LOCATION \
    --cluster-version=VERSION \
    --workload-pool=PROJECT_ID.svc.id.goog

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters create CLUSTER_NAME `
    --enable-secret-manager `
    --location=LOCATION `
    --cluster-version=VERSION `
    --workload-pool=PROJECT_ID.svc.id.goog

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters create CLUSTER_NAME ^
    --enable-secret-manager ^
    --location=LOCATION ^
    --cluster-version=VERSION ^
    --workload-pool=PROJECT_ID.svc.id.goog

{ Autopilot cluster}

Para ativar o complemento do Secret Manager em um novo cluster do Autopilot, execute o seguinte comando:

Antes de usar os dados do comando abaixo, faça estas substituições:

• CLUSTER_NAME: o nome do cluster.
• VERSION: a versão específica do GKE que você quer usar. Verifique se o cluster executa o GKE versão 1.27.14-gke.1042001 ou mais recente. Para definir uma versão específica, consulte Definir a versão e o canal de lançamento de um novo cluster do Autopilot.
• LOCATION: a região do Compute Engine para o cluster, como us-central1.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters create-auto CLUSTER_NAME \
    --enable-secret-manager \
    --cluster-version=VERSION \
    --location=LOCATION

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters create-auto CLUSTER_NAME `
    --enable-secret-manager `
    --cluster-version=VERSION `
    --location=LOCATION

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters create-auto CLUSTER_NAME ^
    --enable-secret-manager ^
    --cluster-version=VERSION ^
    --location=LOCATION

Depois de ativar o complemento do Secret Manager, é possível usar o driver CSI do Secrets Store em volumes do Kubernetes usando o nome do driver e do provisionador: secrets-store-gke.csi.k8s.io.

Ativar o complemento Secret Manager em um cluster do GKE

Para ativar o complemento Secret Manager em um cluster atual, faça o seguinte:

Console

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

   Acessar o Google Kubernetes Engine

2. Na lista de clusters, clique no nome do cluster que você quer modificar.

3. Na página de detalhes do cluster, na seção Segurança, clique em Secret Manager.

4. Na caixa de diálogo Editar Gerenciador de secrets, marque a caixa de seleção Ativar Gerenciador de secrets.

5. Clique em Salvar alterações.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

• CLUSTER_NAME: o nome do cluster.
• LOCATION: a região do Compute Engine para o cluster, como us-central1

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters update CLUSTER_NAME \
    --enable-secret-manager \
    --location=LOCATION \

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters update CLUSTER_NAME `
    --enable-secret-manager `
    --location=LOCATION `

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters update CLUSTER_NAME ^
    --enable-secret-manager ^
    --location=LOCATION ^

Verificar a instalação do complemento do Secret Manager

Para verificar se o complemento do Secret Manager está instalado no cluster do Kubernetes, execute o seguinte comando:

  gcloud container clusters describe CLUSTER_NAME --location LOCATION | grep secretManagerConfig -A 1

Substitua:

• CLUSTER_NAME: o nome do cluster.
• LOCATION: o local do cluster, como us-central1

Configurar aplicativos para autenticação na API Secret Manager

O provedor do Google Secret Manager usa a identidade da carga de trabalho do pod em que um secret é montado ao autenticar na API Secret Manager. Para permitir que seus aplicativos sejam autenticados na API Secret Manager usando a Federação de Identidade da Carga de Trabalho para GKE, siga estas etapas:

• Crie uma nova conta de serviço do Kubernetes ou use uma conta de serviço do Kubernetes existente no mesmo namespace do pod em que você quer montar o secret.

• Crie uma política de permissão do Identity and Access Management (IAM) para o secret no Secret Manager.

Os pods que usam a ServiceAccount do Kubernetes configurada são autenticados automaticamente como o identificador principal do IAM que corresponde à ServiceAccount do Kubernetes ao acessar a API Secret Manager.

Criar uma nova conta de serviço do Kubernetes

1. Salve o seguinte manifesto como service-account.yaml:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: KSA_NAME
     namespace: NAMESPACE
   

   Substitua:

   • KSA_NAME: o nome da nova ServiceAccount do Kubernetes
   • NAMESPACE: o nome do namespace do Kubernetes para a ServiceAccount

2. Aplique o manifesto:

   kubectl apply -f service-account.yaml
   

3. Crie uma política de permissão do IAM que faça referência à nova conta de serviço do Kubernetes e conceda permissão para acessar o segredo:

   gcloud secrets add-iam-policy-binding SECRET_NAME \
       --role=roles/secretmanager.secretAccessor \
       --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME
   

   Substitua:

   • SECRET_NAME: o nome do secret no Secret Manager
   • PROJECT_NUMBER: o número do projeto do Google Cloud.
   • PROJECT_ID: o ID do projeto do Google Cloud que contém seu cluster do GKE
   • NAMESPACE: o nome do namespace do Kubernetes para a ServiceAccount
   • KSA_NAME: o nome da sua ServiceAccount do Kubernetes

Usar uma ServiceAccount do Kubernetes

Crie uma política de permissão do IAM que faça referência à conta de serviço do Kubernetes existente e conceda a ela permissão para acessar o secret:

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --role=roles/secretmanager.secretAccessor \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME

Substitua:

• SECRET_NAME: o nome do secret no Secret Manager
• PROJECT_NUMBER: o número do projeto do Google Cloud.
• PROJECT_ID: o ID do projeto do Google Cloud que contém seu cluster do GKE
• NAMESPACE: o nome do namespace do Kubernetes para a ServiceAccount
• KSA_NAME: o nome da sua ServiceAccount do Kubernetes

Definir quais segredos serão montados

Para especificar quais segredos serão montados como arquivos no pod do Kubernetes, crie um manifesto YAML SecretProviderClass e liste os segredos a serem montados e o nome do arquivo para montar. Siga estas etapas:

1. Salve o seguinte manifesto como app-secrets.yaml:

   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: SECRET_PROVIDER_CLASS_NAME
   spec:
     provider: gke
     parameters:
       secrets: |
         - resourceName: "projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION"
           path: "FILENAME.txt"
   

   Substitua:

   • SECRET_PROVIDER_CLASS_NAME: o nome do objeto SecretProviderClass.
   • PROJECT_ID: o ID do projeto.
   • SECRET_NAME: o nome do secret.
   • SECRET_VERSION: a versão do secret.
   • FILENAME.txt: o nome do arquivo em que o valor do secret será montado. É possível criar vários arquivos usando as variáveis resourceName e path.

2. Aplique o manifesto:

   kubectl apply -f app-secrets.yaml
   

3. Verifique se o objeto SecretProviderClass foi criado:

   kubectl get SecretProviderClasses
   

Configurar um volume em que os secrets serão montados

1. Salve a configuração a seguir como my-pod.yaml:

   apiVersion: v1
   kind: Pod
   metadata:
     name: POD_NAME
     namespace: NAMESPACE
   spec:
     serviceAccountName: KSA_NAME
     containers:
     - image: IMAGE_NAME
       imagePullPolicy: IfNotPresent
       name: POD_NAME
       resources:
         requests:
           cpu: 100m
       stdin: true
       stdinOnce: true
       terminationMessagePath: /dev/termination-log
       terminationMessagePolicy: File
       tty: true
       volumeMounts:
         - mountPath: "/var/secrets"
           name: mysecret
     volumes:
     - name: mysecret
       csi:
         driver: secrets-store-gke.csi.k8s.io
         readOnly: true
         volumeAttributes:
           secretProviderClass: SECRET_PROVIDER_CLASS_NAME
   

   Substitua:

   • POD_NAME: o nome do pod do Kubernetes em que o secret é montado.
   • NAMESPACE: o nome do namespace do Kubernetes para a ServiceAccount
   • KSA_NAME: a conta de serviço do Kubernetes que você configurou na etapa Configurar aplicativos para autenticação na API Secret Manager.
   • IMAGE_NAME: nome da imagem do contêiner.
   • SECRET_PROVIDER_CLASS_NAME: o nome do objeto SecretProviderClass

2. Somente em clusters padrão, adicione o seguinte ao campo template.spec para colocar os pods em pools de nós que usam a federação de identidade da carga de trabalho para o GKE.

   Pule esta etapa nos clusters do Autopilot, que rejeitam esse nodeSeletor porque todos os nós usam a federação de identidade da carga de trabalho para o GKE.

   spec:
     nodeSelector:
       iam.gke.io/gke-metadata-server-enabled: "true"
   

3. Aplique a configuração a seu cluster.

   kubectl apply -f my-pod.yaml
   

Esta etapa monta um volume mysecret em /var/secrets usando o driver CSI (secrets-store-gke.csi.k8s.io). Esse volume faz referência ao objeto SecretProviderClass, que atua como provedor.

Migrar do driver CSI do Secrets Store

Se você estiver migrando para o complemento do Secret Manager da sua instalação atual do driver CSI do Secrets Store, atualize o manifesto do pod da seguinte maneira:

1. Atualize o nome do SecretProviderClass e do provider, conforme descrito neste manifesto:

   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: app-secrets-gke
   spec:
     provider: gke
     parameters:
       secrets: |
         - resourceName: "projects/<project_id>/secrets/<secret_name>/versions/<secret_version>"
           path: "good1.txt"
   

2. Atualize o driver e o secretProviderClass para seu volume do Kubernetes, conforme descrito no seguinte manifesto:

   volumes:
     - name: mysecret
       csi:
         driver: secrets-store-gke.csi.k8s.io
         readOnly: true
         volumeAttributes:
           secretProviderClass: "app-secrets-gke"
   

Desativar o complemento do Secret Manager

Para desativar o complemento do Secret Manager em um cluster padrão ou do Autopilot, execute o seguinte comando:

Console

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

   Acessar o Google Kubernetes Engine

2. Na lista de clusters, clique no nome do cluster que você quer modificar.

3. Na página de detalhes do cluster, na seção Segurança, clique em Secret Manager.

4. Na caixa de diálogo Edit Secret Manager, desmarque a caixa de seleção Ativar Secret Manager.

5. Clique em Salvar alterações.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

• CLUSTER_NAME: o nome do cluster.
• REGION: a região do Compute Engine para o cluster, como us-central1.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters update CLUSTER_NAME \
    --no-enable-secret-manager \
    --region=REGION \

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters update CLUSTER_NAME `
    --no-enable-secret-manager `
    --region=REGION `

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud container clusters update CLUSTER_NAME ^
    --no-enable-secret-manager ^
    --region=REGION ^