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 confidenciais para as dependências. Para o Cloud Run, o Google recomenda armazenar essas informações confidenciais em um secret criado em Secret Manager.

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

• Quando você ativa cada secret como um volume, o Cloud Run o disponibiliza para o contêiner como arquivos. Ao ler um volume, o Cloud Run sempre busca o valor do Secret Manager para usar o valor com a versão mais recente. Esse método também funciona bem com a rotação de secret.
• 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 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 secret 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 ativado vão falhar.

Propriedade do volume

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

Quando você ativa 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. Ativar a API Secret Manager.

   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 pela função Proprietário (roles/owner). Caso contrário, você pode receber essa permissão pela função Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder funções.

   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 usar configurar secrets, peça ao administrador para conceder a você os papéis do IAM a seguir:

• 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 interage com Google Cloud APIs, 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 à instância usando a Google Cloud CLI ou o YAML ao implantar uma nova instância ou atualizar uma instância:

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 atual, 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 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 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 para o volume.
   • MOUNT_PATH: o caminho relativo em que você está ativando 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 fazer referência a 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 atual, 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 instância do Cloud Run.
   • SECRET_LOOKUP_NAME: qualquer nome que tenha uma sintaxe de nome de secret válida, por exemplo, my-secret. Ele pode ser o mesmo que 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 instância do Cloud Run.
   • SECRET_LOOKUP_NAME: qualquer nome que tenha uma sintaxe de nome de secret válida , por exemplo, my-secret. Ele pode ser o mesmo que 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 para o volume.
   • MOUNT_PATH: o caminho relativo em que você está ativando 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, faça o seguinte:

gcloud

1. Use o comando a seguir:

   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 a serem removidos.

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 flag --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 confidenciais com o Secret Manager.

Limitações

As seções a seguir descrevem as limitações que se aplicam à ativação 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 oferece suporte a 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.