Configurar secrets

O serviço 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 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 implantação do serviço, 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 implantação do serviço 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, a identidade que detém os arquivos e os diretórios varia de acordo com o ambiente de execução da carga de trabalho e se a implantação consiste em um ou vários contêineres.

No ambiente de execução de primeira geração em que você está implantando um único contêiner, o volume pertence à identidade usada para o contêiner. Em todos os outros casos, o volume pertence à raiz. Incluindo:

• Ambiente de execução de primeira geração em que você está implantando vários contêineres
• O ambiente de segunda geração

Permitir que o Cloud Run acesse um secret

É possível usar um secret atual do Secret Manager ou criar um novo secret. No entanto, para acessá-lo, é preciso conceder o papel de acessador de secrets do Secret Manager à conta de serviço usada para sua identidade de serviço do Cloud Run.

Quando você seleciona um secret da página do Cloud Run no console do Google Cloud, uma verificação de permissão é realizada automaticamente e você recebe uma solicitação para adicionar as permissões ausentes.

Para executar essa ação manualmente:

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

   Acessar o Secret Manager

2. Clique no secret na lista.

3. Na guia Permissão, clique em Conceder acesso.

4. Na caixa de texto Novos principais, insira o e-mail da identidade do serviço do Cloud Run.

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

Tornar um secret acessível ao 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.

Importante: a conta de serviço do Cloud Run precisa de acesso de leitura ao secret.

É 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. No console do Google Cloud, acesse o Cloud Run:

   Acesse 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 do serviço conforme preferir e clique em Contêineres, volumes, rede, segurança para expandir a página de configurações do serviço.

4. Clique na guia Contêiner.

   

   • Em Secrets:
     • Clique em Referência a um 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 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. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato REGION-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.
  • 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. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
  • 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 conferir as configurações de serviço 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. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
   • 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

Terraform

1. Crie um secret e uma versão dele.

   
   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = "~> 5.13.0"
       }
     }
   }
   
   resource "google_secret_manager_secret" "default" {
     secret_id = "my-secret"
     replication {
       auto {}
     }
   }
   
   resource "google_secret_manager_secret_version" "default" {
     secret      = google_secret_manager_secret.default.name
     secret_data = "this is secret data"
   }

2. Crie uma conta de serviço e conceda a ela acesso ao secret:

   resource "google_service_account" "default" {
     account_id   = "cloud-run-service-account"
     display_name = "Service account for Cloud Run"
   }
   
   resource "google_secret_manager_secret_iam_member" "default" {
     secret_id = google_secret_manager_secret.default.id
     role      = "roles/secretmanager.secretAccessor"
     # Grant the new deployed service account access to this secret.
     member     = "serviceAccount:${google_service_account.default.email}"
     depends_on = [google_secret_manager_secret.default]
   }

3. Os secrets do Secret Manager podem ser acessados no Cloud Run como caminhos de arquivo montados ou como variáveis de ambiente.

   1. Para secrets montados como caminhos de arquivo, crie uma referência ao recurso do Secret Manager no parâmetro volumes. O name corresponde a uma entrada no parâmetro volume_mounts:

      resource "google_cloud_run_v2_service" "mounted_secret" {
        name     = "cloudrun-srv-mounted-secret"
        location = "us-central1"
        ingress  = "INGRESS_TRAFFIC_ALL"
      
        template {
          volumes {
            name = "my-service-volume"
            secret {
              secret = google_secret_manager_secret.default.secret_id
              items {
                version = "latest"
                path    = "my-secret"
                mode    = 0 # use default 0444
              }
            }
          }
          containers {
            image = "us-docker.pkg.dev/cloudrun/container/hello"
            volume_mounts {
              name       = "my-service-volume"
              mount_path = "/secrets"
            }
          }
          service_account = google_service_account.default.email
        }
        depends_on = [google_secret_manager_secret_version.default]
      }

   2. Para secrets expostos como variáveis de ambiente, crie uma referência ao recurso do Secret Manager no parâmetro env:

      resource "google_cloud_run_v2_service" "env_variable_secret" {
        name     = "cloudrun-srv-env-var-secret"
        location = "us-central1"
        ingress  = "INGRESS_TRAFFIC_ALL"
      
        template {
          containers {
            image = "us-docker.pkg.dev/cloudrun/container/hello"
            env {
              name = "MY_SECRET"
              value_source {
                secret_key_ref {
                  secret  = google_secret_manager_secret.default.secret_id
                  version = "latest"
                }
              }
            }
          }
          service_account = google_service_account.default.email
        }
        depends_on = [google_secret_manager_secret_version.default]
      }

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 o Cloud Run:

   Acesse 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 do serviço conforme preferir e clique em Contêineres, volumes, rede, segurança para expandir a página de configurações do serviço.

4. Clique na guia Contêiner.

   

   • Em Secrets:
     • Clique em Referência a um secret.
     • Selecione Não vê seu secret? Insira o código do recurso secret na lista suspensa Secret para exibir o seguinte formulário:

       

     • 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 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. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato REGION-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

É possível fazer o download e conferir as configurações de serviço 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:
       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: 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. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
   • 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:
       metadata:
         annotations:
           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. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato REGION-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.
   • 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 serviço do Cloud Run, faça o seguinte:

Console

1. No console do Google Cloud, acesse o Cloud Run:

   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 dos Secrets está listada na guia Contêiner.

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.

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.