Usar secrets

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Seu serviço ou job pode precisar de dependências que exigem 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 Gerenciador de secrets.

É 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 Gerenciador de secrets.

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

Durante a implantação do serviço ou a criação do job, todas as chaves de secrets usadas, como variável de ambiente ou montadas como um volume, são verificadas para garantir que a conta de serviço usada para executar o contêiner tenha acesso a eles. Se alguma verificação falhar, a implantação ou 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.

Permitir que o Cloud Run acesse um secret

É possível usar um secret atual do Gerenciador de secrets ou criar um novo secret. No entanto, para permitir que um serviço do Cloud Run acesse o secret, conceda o papel de acessador de recursos do Secret Manager ao conta de serviço do Cloud Run:

  1. Acesse a página Secret Manager no Console do Google Cloud:

  2. Selecione o secret e, na guia de permissões do lado direito, clique em Adicionar principal.

  3. Na caixa de texto Novos principais, insira o e-mail da conta de serviço para seu serviço do Cloud Run.

  4. Conceda a ele o papel de Acessador de secrets do Gerenciador de secrets.

Tornar um secret acessível ao Cloud Run

É possível disponibilizar secrets para serviços e jobs.

Para serviços do Cloud Run

Qualquer mudança na configuração leva à criação de uma nova revisão. As próximas revisões também recebem automaticamente essa configuração, a menos que você faça atualizações explícitas para alterá-la.

É possível tornar um secret acessível ao seu serviço usando o Console do Google Cloud, a Google Cloud CLI ou um arquivo YAML ao implantar um novo serviço ou atualizar um serviço atual e implantar uma revisão:

Console

  1. Acessar o Cloud Run

  2. Clique em Criar serviço se estiver configurando um novo serviço em que fará uma implantação. Se você estiver configurando um serviço atual, clique nele e em Editar e implantar nova revisão.

  3. Se você estiver configurando um novo serviço, preencha a página inicial de configurações de serviço conforme desejado e clique em Contêiner, conexões, segurança para expandir a página de configuração do serviço.

  4. Clique na guia Variáveis e secrets.

    imagem

  5. Na guia "Variáveis e secrets":

    • Em Secrets, clique em Reference a 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.

  6. Clique em Criar ou Implantar.

Linha de comando

Para tornar um secret acessível ao serviço, digite um dos comandos a seguir.

  • Para ativar o secret como um volume ao implantar um serviço, siga as etapas a seguir:

    gcloud run deploy SERVICE --image IMAGE_URL  \
    --update-secrets=PATH=SECRET_NAME:VERSION

    Substitua:

    • SERVICE pelo nome do serviço;
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello: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 expor o secret como uma variável de ambiente ao implantar um serviço, siga estas etapas:

    gcloud run deploy SERVICE --image IMAGE_URL --update-secrets=ENV_VAR_NAME=SECRET_NAME:VERSION

    Substitua:

    • SERVICE pelo nome do serviço;
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest;
    • ENV_VAR_NAME pelo nome da variável de ambiente que você quer usar com 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.
  • É possível atualizar vários secrets ao mesmo tempo. Para fazer isso, 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 existentes, digite o seguinte comando:

    gcloud run deploy SERVICE --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 ao serviço, use a sinalização --set-secrets:

    gcloud run services update SERVICE \
    --set-secrets="ENV_VAR_NAME=SECRET_NAME:VERSION"
    

YAML

É possível fazer o download e ver a configuração do serviço atual usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

  1. Para ver e fazer o download da configuração:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Para secrets expostos como variáveis de ambiente, em env, atualize ENV_VAR, VERSION e/ou SECRET_NAME conforme desejado. Se você tiver vários secrets montados como variáveis de ambiente, terá vários desses atributos.

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
        metadata:
          name: REVISION
        spec:
          containers:
          - image: IMAGE_URL
            env:
            - name: ENV_VAR
              valueFrom:
                secretKeyRef:
                  key: VERSION
                  name: SECRET_NAME
  3. Para secrets ativados como caminhos de arquivo, atualize MOUNT_PATH, VOLUME_NAME, VERSION, FILENAME e/ou SECRET_NAME conforme desejado. Se você tiver vários secrets ativados como caminhos de arquivo, terá múltiplos desses atributos.

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
        metadata:
          name: REVISION
        spec:
          containers:
          - image: IMAGE_URL
            volumeMounts:
            - mountPath: MOUNT_PATH
              name: VOLUME_NAME
          volumes:
          - name: VOLUME_NAME
            secret:
              items:
              - key: VERSION
                path: FILENAME
              secretName: SECRET_NAME

    Observe que VOLUME_NAME pode ser definido como qualquer nome.

    Substituir

    • SERVICE pelo nome do serviço do Cloud Run;
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest;
    • REVISION por um novo nome de revisão ou excluí-lo (se houver). Se você fornecer um novo nome de revisão, ele precisará atender aos seguintes critérios:
      • Começa com SERVICE-
      • Contém apenas letras minúsculas, números e -
      • Não termina com um -
      • Não excede 63 caracteres
  4. Substitua o serviço pela nova configuração usando o seguinte comando:

    gcloud run services replace service.yaml

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. Acessar o Cloud Run

  2. Clique em Criar serviço se estiver configurando um novo serviço em que fará uma implantação. Se você estiver configurando um serviço atual, clique nele e em Editar e implantar nova revisão.

  3. Se você estiver configurando um novo serviço, preencha a página inicial de configurações de serviço conforme desejado e clique em Contêiner, conexões, segurança para expandir a página de configuração do serviço.

  4. Clique na guia Variáveis e secrets.

    imagem

  5. Na guia "Variáveis e secrets":

    • Em Secrets, clique em Reference a Secret.
    • Selecione Não vê seu secret? Insira o código do recurso secret do Secret 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.

  6. Clique em Criar ou Implantar.

Linha de comando

  • Para ativar o secret como um volume ao implantar um serviço, siga as etapas a seguir:

    gcloud run deploy SERVICE --image IMAGE_URL  \
    --update-secrets=PATH=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION

    Substitua:

    • SERVICE pelo nome do serviço;
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello: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.
    • 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

É possível fazer o download e ver a configuração do serviço atual usando o comando gcloud run services describe --format export, que produz resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run services replace. Modifique os campos somente conforme documentado.

  1. Para ver e fazer o download da configuração:

    gcloud run services describe SERVICE --format export > service.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: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
          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: VERSION
                  name: SECRET_LOOKUP_NAME

    Substitua:

    • SERVICE pelo nome do serviço;
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest;
    • ENV_VAR
    • 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.
    • 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: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
          run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
        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:

    • SERVICE pelo nome do serviço;
    • IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello: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.
    • 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.
    • 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.

Para jobs do Cloud Run

É possível tornar um secret acessível para o job usando o Console do Google Cloud ou a Google Cloud CLI:

Console

  1. Acesse o Cloud Run

  2. Se você estiver configurando um novo job, clique na guia Jobs e preencha a página inicial de configurações do job conforme quiser. 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.

    image

  5. Na guia "Variáveis e secrets":

    • Em Secrets, clique em Reference a 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.

  6. Clique em Criar ou Atualizar.

Linha de comando

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

    gcloud beta 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 beta 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 beta 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 beta run jobs update JOB_NAME \
    --update-secrets=PATH=SECRET_NAME:VERSION

Ver configurações de secrets

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

Console

  1. Acesse o Cloud Run

  2. Clique no serviço de seu interesse para abrir a página Detalhes do serviço.

  3. Clique na guia Revisões.

  4. No painel de detalhes à direita, a configuração de secrets é listada na guia Variables & Secrets.

Linha de comando

  1. Use o comando a seguir:

    gcloud run services describe SERVICE
  2. Localize a configuração de secret na configuração retornada.

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

Console

  1. 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.

Linha de comando

  1. Use o comando a seguir:

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

Usar secrets no código

Para exemplos de como acessar segredos 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.

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.