Configurar segredos para instâncias

Prévia — instâncias do Cloud Run

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

A instância pode exigir chaves de API, senhas, certificados ou outras informações sensíveis para as dependências. Para o Cloud Run, o Google recomenda armazenar essas informações sensíveis em um secret criado no Secret Manager.

Disponibilize um secret para os contêineres de uma das seguintes maneiras:

• Quando você ativa cada secret como um volume, o Cloud Run disponibiliza o secret para o contêiner como arquivos. Ao ler um volume, o Cloud Run sempre busca o valor do secret no Secret Manager para usar o valor com a versão mais recente. Esse método também funciona bem com a rotação de secrets.
• Transmita um secret usando variáveis de ambiente. As variáveis de ambiente são resolvidas no momento da inicialização da instância. Portanto, se você usar esse método, o Google recomenda que você fixe o secret em uma versão específica em vez de usar latest como a versão.

Para mais informações, consulte as práticas recomendadas do Secret Manager.

Como os secrets são verificados na implantação e no ambiente de execução

Durante a implantação da instância, o Cloud Run verifica todos os secrets que você usa. A verificação garante que a conta de serviço que executa o contêiner tenha permissão para acessar esses secrets.

Durante o tempo de execução, quando as instâncias são iniciadas:

• Se o secret for uma variável de ambiente, o Cloud Run vai recuperar o valor dele antes de iniciar a instância. Se o processo de recuperação de secrets falhar, a instância não será iniciada.
• Se você ativar o secret como um volume, o Cloud Run não vai realizar nenhuma verificação durante a inicialização da instância. No entanto, durante o tempo de execução, se um secret estiver inacessível, as tentativas de ler o volume montado vão falhar.

Propriedade do volume

A propriedade de um volume secreto do Cloud Run varia de acordo com o ambiente de execução e o tipo de implantação.

Quando você monta um volume de secret usando o ambiente de execução de segunda geração, que é sempre o caso da instância, a raiz é proprietária do volume.

Antes de começar

1. Ative a API Secret Manager, se ainda não tiver feito isso.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

2. Use um secret atual ou crie um no Secret Manager, conforme descrito em Criar secret.

Funções exigidas

Para receber as permissões necessárias para configurar secrets, peça ao administrador que conceda a você os seguintes papéis do IAM:

• Administrador do Cloud Run (roles/run.admin) na instância do Cloud Run
• Usuário da conta de serviço (roles/iam.serviceAccountUser) na identidade do serviço

Para permitir que o Cloud Run acesse o secret, a identidade do serviço precisa ter o seguinte papel:

• Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor)

Para instruções sobre como adicionar o principal de identidade de serviço ao papel Acessador de Secrets do Secret Manager, consulte Gerenciar o acesso aos secrets.

Para uma lista de papéis e permissões do IAM associados ao Cloud Run, consulte Papéis do IAM do Cloud Run e Permissões do IAM do Cloud Run. Se a instância do Cloud Run interagir com APIsGoogle Cloud , como as bibliotecas de cliente do Cloud, consulte o guia de configuração de identidade de serviço. Para mais informações sobre como conceder papéis, consulte permissões de implantação e gerenciar acesso.

Tornar um secret acessível ao Cloud Run

É possível tornar um secret acessível à sua instância usando a Google Cloud CLI ou YAML ao implantar uma nova instância ou atualizar uma instância atual:

gcloud

• Para expor o secret como uma variável de ambiente ao implantar uma instância, execute o seguinte comando:

  gcloud beta run instances deploy INSTANCE \
    --image IMAGE_URL \
    --update-secrets=ENV_VAR_NAME=SECRET_NAME:VERSION

  Substitua:

  • INSTANCE: o nome da instância.
  • IMAGE_URL: uma referência à imagem de contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.
  • ENV_VAR_NAME: o nome da variável de ambiente que você quer usar com o secret.
  • SECRET_NAME: o nome do secret no mesmo projeto, por exemplo, mysecret.
  • VERSION: a versão do secret. Use latest para a versão mais recente ou um número, por exemplo, 2.

• Para atualizar vários secrets ao mesmo tempo, separe as opções de configuração de cada secret com uma vírgula. O comando a seguir atualiza um secret ativado como um volume e outro secret exposto como uma variável de ambiente. Para atualizar os secrets atuais, execute o seguinte comando:

  gcloud beta run instances deploy INSTANCE \
  --image IMAGE_URL \
  --update-secrets=PATH=SECRET_NAME:VERSION,ENV_VAR_NAME=SECRET_NAME:VERSION

• Para limpar os secrets atuais e tornar um novo secret acessível à instância, use a flag --set-secrets:

  gcloud beta run instances update INSTANCE \
   --set-secrets="ENV_VAR_NAME=SECRET_NAME:VERSION"

YAML

1. Se você estiver criando uma nova instância, pule esta etapa. Se você estiver atualizando uma instância, baixe a configuração YAML correspondente:

   gcloud beta run instances describe INSTANCE --format export > instance.yaml

2. Para secrets expostos como variáveis de ambiente:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     containers:
     - image: IMAGE_URL
       env:
       - name: ENV_VAR
         valueFrom:
           secretKeyRef:
             key: SECRET_VERSION
             name: SECRET_NAME

   Substitua:

   • INSTANCE: o nome da sua instância do Cloud Run.
   • IMAGE_URL: uma referência à imagem de contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.
   • ENV_VAR: o nome da variável de ambiente.
   • SECRET_VERSION: a versão do secret. Use latest para a versão mais recente ou um número, por exemplo, 2.
   • SECRET_NAME: o nome do secret, por exemplo, mysecret.

3. Para secrets montados como caminhos de arquivo:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     containers:
     - image: IMAGE_URL
       volumeMounts:
       - name: VOLUME_NAME
         mountPath: MOUNT_PATH
     volumes:
     - name: VOLUME_NAME
       secret:
         secretName: SECRET_NAME
         items:
         - key: SECRET_VERSION
           path: SECRET_NAME

   Substitua:

   • INSTANCE: o nome da sua instância do Cloud Run.
   • IMAGE_URL: uma referência à imagem de contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.
   • VOLUME_NAME: qualquer nome que você queira dar ao volume.
   • MOUNT_PATH: o caminho relativo em que você está montando o volume, por exemplo, /mnt/my-volume.
   • SECRET_NAME: o nome do secret, por exemplo, mysecret.
   • SECRET_VERSION: a versão do secret. Use latest para a versão mais recente ou um número, por exemplo, 2.

4. Substitua a instância pela nova configuração usando o seguinte comando:

   gcloud beta run services replace service.yaml

Fazer referência a secrets de outros projetos

Para fazer referência a um secret de outro projeto, verifique se a conta de instância do projeto tem acesso ao secret.

gcloud

Para referenciar um secret como uma variável de ambiente, execute o seguinte comando:

gcloud beta run instances deploy INSTANCE \
    --image IMAGE_URL \
    --update-secrets=ENV_VAR_NAME=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION

Substitua:

• INSTANCE: o nome da instância.
• IMAGE_URL: uma referência à imagem de contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.
• PROJECT_NUMBER: o número do projeto em que o secret foi criado.
• SECRET_NAME: o nome do secret, por exemplo, mysecret.
• VERSION: a versão do secret. Use latest para a versão mais recente ou um número, por exemplo, 2.

YAML

1. Se você estiver criando uma nova instância, pule esta etapa. Se você estiver atualizando uma instância, baixe a configuração YAML correspondente:

   gcloud beta run instances describe INSTANCE --format export > instance.yaml

2. Para secrets expostos como variáveis de ambiente:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
       metadata:
         annotations:
           run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
       spec:
         containers:
         - image: IMAGE_URL
           env:
           - name: ENV_VAR
             valueFrom:
               secretKeyRef:
                 key: SECRET_VERSION
                 name: SECRET_LOOKUP_NAME

   Substitua:

   • INSTANCE: o nome da sua instância do Cloud Run.
   • SECRET_LOOKUP_NAME: qualquer nome que tenha uma sintaxe válida de nome de secret, por exemplo, my-secret. Ele pode ser igual a SECRET_NAME.
   • PROJECT_NUMBER: o número do projeto em que o secret foi criado.
   • SECRET_NAME: o nome do secret, por exemplo, mysecret.
   • IMAGE_URL: uma referência à imagem de contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.
   • ENV_VAR: o nome da variável de ambiente.
   • SECRET_VERSION: a versão do secret. Use latest para a versão mais recente ou um número, por exemplo, 2.

3. Para secrets montados como caminhos de arquivo:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   metadata:
     annotations:
       run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
   spec:
     containers:
     - image: IMAGE_URL
       volumeMounts:
       - name: VOLUME_NAME
         mountPath: MOUNT_PATH
     volumes:
     - name: VOLUME_NAME
       secret:
         secretName: SECRET_NAME
         items:
         - key: SECRET_VERSION
           path: SECRET_LOOKUP_NAME

   Substitua:

   • INSTANCE: o nome da sua instância do Cloud Run.
   • SECRET_LOOKUP_NAME: qualquer nome que tenha uma sintaxe válida de nome de secret, por exemplo, my-secret. Pode ser igual a SECRET_NAME.
   • PROJECT_NUMBER: o número do projeto em que o secret foi criado.
   • SECRET_NAME: o nome do secret, por exemplo, mysecret.
   • IMAGE_URL: uma referência à imagem de contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.
   • VOLUME_NAME: qualquer nome que você queira dar ao volume.
   • MOUNT_PATH: o caminho relativo em que você está montando o volume, por exemplo, /mnt/my-volume.
   • SECRET_VERSION: a versão do secret. Use latest para a versão mais recente ou um número, por exemplo, 2.

4. Substitua a instância pela nova configuração usando o seguinte comando:

   gcloud beta run instances replace instance.yaml

Ver configurações de secrets

Para ver as configurações de secrets atuais da instância do Cloud Run:

gcloud

1. Execute este comando:

   gcloud beta run instances describe INSTANCE

2. Localize a configuração de secret na configuração retornada.

Remover secrets de uma instância

É possível remover secrets de uma instância usando a CLI gcloud:

gcloud

É possível remover todos os secrets de uma instância ou especificar um ou mais secrets para remover.

Para remover todos os segredos, execute o seguinte comando:

  gcloud beta run instances deploy INSTANCE --image IMAGE_URL \
      --clear-secrets

Substitua:

• INSTANCE: o nome da instância.
• IMAGE_URL: uma referência à imagem de contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.

Para especificar uma lista de secrets a serem removidos, use a sinalização --remove-secrets. O comando a seguir remove um secret ativado como um volume e outro secret exposto como uma variável de ambiente.

  gcloud beta run instances deploy INSTANCE --image IMAGE_URL \
      --remove-secrets=ENV_VAR_NAME,SECRET_FILE_PATH

Substitua:

• INSTANCE: o nome da instância.
• IMAGE_URL: uma referência à imagem de contêiner, como us-docker.pkg.dev/cloudrun/container/hello:latest.
• ENV_VAR_NAME: o nome da variável de ambiente.

• SECRET_FILE_PATH: o caminho completo do secret. Por exemplo, /mnt/secrets/primary/latest, em que /mnt/secrets/primary/ é o caminho de ativação e latest é o caminho secreto. Também é possível especificar os caminhos de montagem e secret separadamente:

  --set-secrets MOUNT_PATH:SECRET_PATH=SECRET:VERSION

Usar secrets no código

Para exemplos de como acessar secrets no código como variáveis de ambiente, consulte o tutorial sobre autenticação de usuários finais, especialmente a seção Como lidar com configurações sensíveis com o Secret Manager.

Limitações

As seções a seguir descrevem as limitações que se aplicam à montagem de secrets.

Caminhos não permitidos

• O Cloud Run não permite ativar secrets em /dev, /proc e /sys, ou nos subdiretórios.
• O Cloud Run não permite ativar vários secrets no mesmo caminho porque duas ativações de volume não podem ser montadas no mesmo local.

Secrets regionais

O Cloud Run não é compatível com secrets regionais.

Substituição de um diretório

Se o secret for montado como um volume no Cloud Run e o último diretório no caminho de montagem do volume já existir, todos os arquivos ou pastas no diretório atual ficarão inacessíveis.

Por exemplo, se um secret chamado my-secret for ativado no caminho /etc/app_data, todo o conteúdo dentro do diretório app_data será substituído, e o único arquivo visível será /etc/app_data/my-secret.

Para evitar a substituição de arquivos em um diretório atual, crie um novo diretório para ativar o secret, por exemplo, /etc/app_data/secrets, de modo que o caminho de ativação do secret seja /etc/app_data/secrets/my-secret.