O serviço 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 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 de secret, 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 de secret pertence à identidade usada para o contêiner. Em todos os outros casos, o volume pertence à raiz. Isso inclui:
- Ambiente de execução de primeira geração em que você está implantando vários contêineres
- O ambiente de segunda geração
Antes de começar
-
Enable the Secret Manager API.
- 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
) no serviço Cloud Run -
Usuário da conta de serviço (
roles/iam.serviceAccountUser
) na conta de 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 o serviço do Cloud Run interage com as APIs do Google 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
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 serviço usando o console do Google Cloud, a CLI do Google Cloud ou um arquivo YAML ao implantar um novo serviço ou atualizar um atual e implantar uma revisão: Clique na guia escolhida:
Console
No console do Google Cloud, acesse o Cloud Run:
Clique em Implantar contêiner e selecione Serviço para configurar um novo serviço. Preencha a página inicial de configurações do serviço e clique em Contêineres, volumes, redes e segurança para expandir a página de configurações de serviço.
Ao configurar um serviço atual, clique nele e em Editar e implantar nova revisão.
Siga as etapas para expor o secret como uma variável de ambiente ou ativá-lo como um volume.
Para ativar o secret como um volume:
- Clique na guia Volumes e selecione Adicionar volume.
- Na lista Tipo de volume, selecione Secret.
- No campo Nome do volume, digite um nome ou aceite o nome padrão.
- Na lista Secret, selecione o secret que você quer usar.
- No campo Caminho 1, digite o nome do arquivo a ser ativado.
- Na lista Versão 1, selecione a versão do secret a ser referenciada. Por padrão, a versão mais recente é selecionada. É possível selecionar uma versão específica.
- Clique em Concluído.
- Acesse a guia Contêiner para ativar o secret no contêiner.
- Na guia Ativações de volume, clique em Ativar volume.
- Na lista Nome 1, selecione o nome do volume.
- No campo Caminho de ativação 1, insira o caminho de ativação do secret. Esse é o diretório em que todas as versões do secret são colocadas.
- Clique em Concluído.
- Clique em Criar ou Implantar.
Para expor o secret como uma variável de ambiente:
- Clique na guia Contêiner.
- Na guia Variáveis e secrets, clique em Referenciar um secret.
- No campo Nome 1, insira o nome da variável de ambiente.
- Na lista Secret, selecione o secret que você quer usar.
- Na lista Versão 1, selecione a versão do secret a ser referenciada.
- Clique em Concluído.
- Clique em Criar ou Implantar.
gcloud
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 formatoLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
PATH
pelo 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 epassword
é o nome do arquivo do secret.SECRET_NAME
pelo nome do secret no mesmo projeto, por exemplo,mysecret
.VERSION
pela versão do secret Uselatest
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 formatoLOCATION-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 Uselatest
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
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 services describe SERVICE --format export > service.yaml
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
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 formatoLOCATION-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
- Começa com
Substitua o serviço pela nova configuração usando o seguinte comando:
gcloud run services replace service.yaml
Terraform
Crie um secret e uma versão dele.
Crie uma conta de serviço e conceda a ela acesso ao secret:
Os secrets do Secret Manager podem ser acessados no Cloud Run como caminhos de arquivo montados ou como variáveis de ambiente.
Para secrets montados como caminhos de arquivo, crie uma referência ao recurso do Secret Manager no parâmetro
volumes
. Oname
corresponde a uma entrada no parâmetrovolume_mounts
:Para secrets expostos como variáveis de ambiente, crie uma referência ao recurso do Secret Manager no parâmetro
env
:
Fazer referência a secrets de outros projetos
Para fazer referência a um secret de outro projeto, verifique se a conta de serviço do projeto tem acesso ao secret.
Console
No console do Google Cloud, acesse o Cloud Run:
Clique em Implantar contêiner e selecione Serviço para configurar um novo serviço. Preencha a página inicial de configurações do serviço e clique em Contêineres, volumes, redes e segurança para expandir a página de configurações de serviço.
Ao configurar um serviço atual, clique nele e em Editar e implantar nova revisão.
Siga as etapas para expor o secret como uma variável de ambiente ou ativá-lo como um volume.
Para ativar o secret como um volume:
- Clique na guia Volumes e selecione Adicionar volume.
- Na lista Tipo de volume, selecione Secret.
- No campo Nome do volume, digite um nome ou aceite o nome padrão.
- Na lista Secret, clique em Inserir secret manualmente.
Insira o ID do recurso do secret no seguinte formato:
projects/PROJECT_NUMBER/secrets/SECRET_NAME
Substitua:
PROJECT_NUMBER pelo número do projeto do Google Cloud. Para instruções detalhadas sobre como encontrar o número do projeto, consulte Criar e gerenciar projetos.
SECRET_NAME: o nome do secret no Secret Manager.
No campo Caminho 1, digite o nome do arquivo a ser ativado.
Na lista Versão 1, selecione a versão do secret a ser referenciada. Por padrão, a versão mais recente é selecionada. É possível selecionar uma versão específica.
Clique em Concluído.
Acesse a guia Contêiner para ativar o secret no contêiner.
Na guia Ativações de volume, clique em Ativar volume.
Na lista Nome 1, selecione o nome do volume.
No campo Caminho de ativação 1, insira o caminho de ativação do secret. Esse é o diretório em que todas as versões do secret são colocadas.
Clique em Concluído.
Clique em Criar ou Implantar.
Para expor o secret como uma variável de ambiente:
- Clique na guia Contêiner.
- Na guia Variáveis e secrets, clique em Referenciar um secret.
- No campo Nome 1, insira o nome da variável de ambiente.
- Na lista Secret, clique em Inserir secret manualmente.
Insira o ID do recurso do secret no seguinte formato:
projects/PROJECT_NUMBER/secrets/SECRET_NAME
Substitua:
PROJECT_NUMBER pelo número do projeto do Google Cloud. Para instruções detalhadas sobre como encontrar o número do projeto, consulte Criar e gerenciar projetos.
SECRET_NAME: o nome do secret no Secret Manager.
Na lista Versão 1, selecione a versão do secret a ser referenciada.
Clique em Concluído.
Clique em Criar ou Implantar.
gcloud
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 formatoLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
PATH
pelo 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 epassword
é 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 Uselatest
para a versão mais recente ou um número, por exemplo,2
.
YAML
Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, baixe a configuração YAML correspondente:
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.
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 formatoLOCATION-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 Uselatest
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 aSECRET_NAME
.
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 formatoLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
PATH
pelo 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 epassword
é 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 Uselatest
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 aSECRET_NAME
.VOLUME_NAME
com qualquer nome (por exemplo,my-volume
) pode ser igual aSECRET_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
No console do Google Cloud, acesse o Cloud Run:
Clique no serviço de seu interesse para abrir a página Detalhes do serviço.
Clique na guia Revisões.
No painel de detalhes à direita, a configuração dos Secrets está listada na guia Contêiner.
gcloud
Use o comando a seguir:
gcloud run services describe SERVICE
Localize a configuração de secret na configuração retornada.
Remover segredos de um serviço
É possível remover segredos de um serviço usando o console do Google Cloud ou a CLI gcloud:
Console
No console do Google Cloud, acesse o Cloud Run:
Selecione seu serviço na lista e clique em Editar e implantar uma nova revisão.
Clique na guia Contêiner.
Para excluir segredos montados como um volume, selecione a guia Volume mounts, mantenha o cursor sobre o segredo que você quer remover e clique em
Delete.Para excluir segredos expostos como uma variável de ambiente, selecione a guia Variáveis e secrets, coloque o cursor sobre o segredo que você quer remover e clique em
Excluir.Clique em Implantar.
gcloud
É possível remover todos os secrets de um serviço ou especificar um ou mais secrets a serem excluídos:
Para remover todos os segredos, execute o seguinte comando:
gcloud run deploy SERVICE --image IMAGE_URL \ --clear-secrets
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 formatoLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
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 run deploy SERVICE --image IMAGE_URL \ --remove-secrets=ENV_VAR_NAME,SECRET_FILE_PATH
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 formatoLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
- 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 elatest
é 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 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.
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
.