Configurar secrets

O job pode precisar de dependências que demandem chaves de API, senhas ou outras informações confidenciais. Para o Cloud Run, o Google recomenda que você armazene esse tipo de informação confidencial em um secret criado no Secret Manager.

É possível disponibilizar um secret de contêineres de duas maneiras:

  • Ative cada secret como um volume, o que torna o secret disponível para o contêiner como arquivos. A leitura de um volume sempre busca o valor do Secret Manager para que possa ser usado com a versão latest. 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 a mais recente.

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

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

Durante a criação do job, todos os secrets usados, seja como variável de ambiente ou montados como volume, são verificados para garantir que a conta de serviço usada para executar o contêiner tenha acesso a eles. Se alguma verificação falhar, a criação do job falhará.

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

  • Se o secret for uma variável de ambiente, o valor dele será recuperado antes de iniciar a instância. Portanto, se a recuperação falhar, a instância não será iniciada.
  • Se o secret for ativado como um volume, nenhuma verificação será realizada 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 falharão.

A propriedade do volume varia por ambiente de execução e tipo de implantação

Quando você monta um volume usando o ambiente de execução de segunda geração, que é o caso de jobs, o volume é de propriedade da raiz.

Antes de começar

É possível usar um secret atual do Secret Manager ou criar um novo 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:

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

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 o job do Cloud Run interagir com APIs do Google Cloud, como 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 ao job usando o console do Google Cloud, a CLI do Google Cloud ou o YAML:

Console

  1. No console do Google Cloud, acesse a página de jobs do Cloud Run:

    Acessar o Cloud Run

  2. Clique em Implantar contêiner e selecione Job para preencher a página inicial de configurações do job. Se você estiver configurando um job, clique nele e em Editar.

  3. Clique em Contêiner, variáveis e secrets, conexões e segurança para expandir a página de propriedades do job.

  4. Clique na guia Variáveis e secrets.

    imagem

    • Na guia "Variáveis e secrets":
      • Em Secrets, clique em Adicionar uma referência de secret
      • Selecione o secret que você quer usar na lista suspensa Secret.
      • No menu suspenso Método de referência, selecione a maneira como você quer usar o secret, montado como um volume ou exposto como variáveis de ambiente.
      • Se você estiver ativando o secret como um volume,
        1. Em Caminho de ativação, especifique o caminho de ativação que você está usando para secrets.
        2. Por padrão, a versão mais recente é selecionada. É possível selecionar uma versão específica, se quiser. Em Caminhos especificados para versões do secret, especifique o caminho para a versão e o número da versão.
        3. Clique em Concluído.
      • Se você está expondo o secret como uma variável de ambiente:
        1. Forneça o Nome da variável e selecione a versão do secret ou a mais recente para sempre usar a versão do secret atual.
        2. Clique em Concluído.
  5. Clique em Criar ou Atualizar.

gcloud

  • Para especificar o secret em uma variável de ambiente ao criar um novo job:

    gcloud run jobs create JOB_NAME \
    --image IMAGE_URL \
    --set-secrets ENV_VAR_NAME=SECRET_NAME:VERSION

    Substituir

    • JOB_NAME pelo nome do job.
    • ENV_VAR_NAME pelo nome da variável de ambiente a ser usada para o secret.
    • SECRET_NAME pelo nome do secret no mesmo projeto, por exemplo, mysecret.
    • VERSION pela versão do secret Use latest para a versão mais recente ou um número, por exemplo, 2.
    • IMAGE_URL por uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest;

    É possível especificar vários pares de variáveis/secrets do ambiente usando uma lista separada por vírgulas.

  • Para especificar o secret em uma variável de ambiente ao atualizar um job:

    gcloud run jobs update JOB_NAME \
    --set-secrets ENV_VAR_NAME=SECRET_NAME:VERSION
  • Para montar o secret como um volume ao criar um job:

    gcloud run jobs create JOB_NAME \
    --image IMAGE_URL \
    --set-secrets=PATH=SECRET_NAME:VERSION

    Substitua:

    • JOB_NAME pelo nome do job.
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest;
    • PATHpelo caminho de ativação do volume e do nome de arquivo do secret. Ele precisa começar com uma barra inicial, por exemplo: /etc/secrets/dbconfig/password, em que /etc/secrets/dbconfig/ é o caminho de ativação do volume e password é o nome do arquivo do secret.
    • SECRET_NAME pelo nome do secret no mesmo projeto, por exemplo, mysecret.
    • VERSION pela versão do secret Use latest para a versão mais recente ou um número, por exemplo, 2.
  • Para atualizar um secret em um job atual, siga estas etapas:

    gcloud run jobs update JOB_NAME \
    --update-secrets=PATH=SECRET_NAME:VERSION

YAML

Devido a restrições na compatibilidade da API, os locais do secret precisam ser armazenados em uma anotação.

  1. Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:

    gcloud run jobs describe JOB_NAME --format export > job.yaml
  2. Para secrets expostos como variáveis de ambiente:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - env:
                - name: SECRET_NAME
                  valueFrom:
                    secretKeyRef:
                      key: VERSION
                      name: SECRET_LOOKUP_NAME
                image: IMAGE_URL 

    Substitua:

    • JOB pelo nome do job.
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • SECRET_NAME com o nome do secret, por exemplo, mysecret.
    • VERSION pela versão do secret Use latest para a versão mais recente ou um número, por exemplo, 2.
    • SECRET_LOOKUP_NAME por qualquer nome que tenha uma sintaxe válida de nome de secret (por exemplo, my-secret) pode ser igual a SECRET_NAME.
  3. Para secrets montados como caminhos de arquivo:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB_NAME
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - image: IMAGE_URL
                volumeMounts:
                - mountPath: MOUNT_PATH
                  name: VOLUME_NAME
              volumes:
              - name: VOLUME_NAME
                secret:
                  items:
                  - key: VERSION
                    path: FILENAME
                  secretName: SECRET_LOOKUP_NAME

    Substitua:

    • JOB_NAME pelo nome do job.
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • PATHpelo caminho de ativação do volume e do nome de arquivo do secret. Ele precisa começar com uma barra inicial, por exemplo: /etc/secrets/dbconfig/password, em que /etc/secrets/dbconfig/ é o caminho de ativação do volume e password é o nome do arquivo do secret.
    • PROJECT_NUMBER pelo número do projeto em que o secret foi criado.
    • SECRET_NAME pelo nome do secret. Por exemplo, mysecret.
    • VERSION pela versão do secret Use latest para a versão mais recente ou um número, por exemplo, 2.
    • SECRET_LOOKUP_NAME por qualquer nome que tenha uma sintaxe válida de nome de secret (por exemplo, my-secret) pode ser igual a SECRET_NAME.
    • VOLUME_NAME com qualquer nome (por exemplo, my-volume) pode ser igual a SECRET_NAME.

Como fazer referência a secrets de outros projetos

É possível referenciar um secret de outro projeto, se a conta de serviço do seu projeto tiver permissão para acessar o secret.

Console

  1. No console do Google Cloud, acesse a página de jobs do Cloud Run:

    Acessar o Cloud Run

  2. Clique em Implantar contêiner e selecione Job para preencher a página inicial de configurações do job. Se você estiver configurando um job, clique nele e em Editar.

  3. Clique em Contêiner, variáveis e secrets, conexões e segurança para expandir a página de propriedades do job.

  4. Clique na guia Variáveis e secrets.

    imagem

    • Na guia "Variáveis e secrets":
      • Em Secrets, clique em Adicionar uma referência de secret
      • Selecione Inserir secret manualmente na lista suspensa Secrets para exibir o seguinte formulário:

        Chaves secretas entre projetos

      • No formulário Adicionar um secret por ID do recurso, insira o secret do outro projeto, no formato projects/PROJECT_NUMBER/secrets/SECRET_NAME. Outra opção é copiar e colar o código do recurso do outro projeto, se você tiver acesso a ele, selecionando a chave secreta, clicando nas reticências à direita do secret, e selecionando Copiar código do recurso no menu suspenso.
      • Clique em Adicionar secret.
      • No menu suspenso Método de referência, selecione a maneira como você quer usar o secret, montado como um volume ou exposto como variáveis de ambiente.
      • Se você estiver ativando o secret como um volume,
        1. Em Caminho de ativação, especifique o caminho de ativação que você está usando para secrets.
        2. Por padrão, a versão mais recente é selecionada. É possível selecionar uma versão específica, se quiser. Em Caminhos especificados para versões do secret, especifique o caminho para a versão e o número da versão.
        3. Clique em Concluído.
      • Se você está expondo o secret como uma variável de ambiente:
        1. Forneça o Nome da variável e selecione a versão do secret ou a mais recente para sempre usar a versão do secret atual.
        2. Clique em Concluído.
  5. Clique em Criar ou Atualizar.

gcloud

  • Para montar um secret como um volume ao atualizar um job:

    gcloud run jobs update JOB_NAME \
    --image IMAGE_URL \
    --update-secrets=PATH=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION
    • JOB_NAME pelo nome do job.
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • PATHpelo caminho de ativação do volume e do nome de arquivo do secret. Ele precisa começar com uma barra inicial, por exemplo: /etc/secrets/dbconfig/password, em que /etc/secrets/dbconfig/ é o caminho de ativação do volume e password é o nome do arquivo do secret.
    • PROJECT_NUMBER pelo número do projeto em que o secret foi criado.
    • SECRET_NAME com o nome do secret, por exemplo, mysecret.
    • VERSION pela 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 um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:

    gcloud run jobs describe JOB_NAME --format export > job.yaml

Devido a restrições na compatibilidade da API, os locais do secret precisam ser armazenados em uma anotação.

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

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
    spec:
      template:
        metadata:
          annotations:
            run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
        spec:
          template:
            spec:
              containers:
              - env:
                - name: SECRET_NAME
                  valueFrom:
                    secretKeyRef:
                      key: VERSION
                      name: SECRET_LOOKUP_NAME
                image: IMAGE_URL 

    Substitua:

    • JOB pelo nome do job.
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • SECRET_NAME pelo nome do secret. Por exemplo, mysecret.
    • VERSION pela versão do secret Use latest para a versão mais recente ou um número, por exemplo, 2.
    • PROJECT_NUMBER pelo número do projeto em que o secret foi criado.
    • SECRET_LOOKUP_NAME por qualquer nome que tenha uma sintaxe válida de nome de secret (por exemplo, my-secret) pode ser igual a SECRET_NAME.
  2. Para secrets montados como caminhos de arquivo:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB_NAME
    spec:
      template:
        metadata:
          annotations:
            run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
        spec:
          template:
            spec:
              containers:
              - image: IMAGE_URL
                volumeMounts:
                - mountPath: MOUNT_PATH
                  name: VOLUME_NAME
              volumes:
              - name: VOLUME_NAME
                secret:
                  items:
                  - key: VERSION
                    path: FILENAME
                  secretName: SECRET_LOOKUP_NAME

    Substitua:

    • JOB_NAME pelo nome do job.
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • PATHpelo caminho de ativação do volume e do nome de arquivo do secret. Ele precisa começar com uma barra inicial, por exemplo: /etc/secrets/dbconfig/password, em que /etc/secrets/dbconfig/ é o caminho de ativação do volume e password é o nome do arquivo do secret.
    • PROJECT_NUMBER pelo número do projeto em que o secret foi criado.
    • SECRET_NAME pelo nome do secret. Por exemplo, mysecret.
    • VERSION pela versão do secret Use latest para a versão mais recente ou um número, por exemplo, 2.
    • SECRET_LOOKUP_NAME por qualquer nome que tenha uma sintaxe válida de nome de secret (por exemplo, my-secret) pode ser igual a SECRET_NAME.
    • VOLUME_NAME com qualquer nome (por exemplo, my-volume) pode ser igual a SECRET_NAME.

Ver configurações de secrets

Para ver as configurações de secrets atuais do seu job do Cloud Run, faça o seguinte:

Console

  1. No console do Google Cloud, acesse a página de jobs do Cloud Run:

    Acessar jobs do Cloud Run

  2. Clique no job em que você tem interesse para abrir a página Detalhes do job.

  3. Clique na guia Configuração.

  4. Localize a definição dos secrets nos detalhes da configuração.

gcloud

  1. Use o comando a seguir:

    gcloud run jobs describe JOB_NAME
  2. Localize a configuração de secret na configuração retornada.

Caminhos e limitações não permitidos

O Cloud Run não permite ativar secrets em /dev, /proc e /sys, ou nos subdiretórios.

Se você estiver ativando secrets em /tmp e usando o ambiente de execução de primeira geração, consulte o problema conhecido na ativação de secrets em /tmp.

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.

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.