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.
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 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:
Acesse a página Secret Manager no Console do Google Cloud:
Selecione o secret e, na guia de permissões do lado direito, clique em Adicionar principal.
Na caixa de texto Novos principais, insira o e-mail da conta de serviço para seu serviço do Cloud Run.
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
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.
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, redes, segurança para expandir a página de configuração do serviço.
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:
- Em Caminho de ativação, especifique o caminho de ativação que você está usando para secrets.
- 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.
- Clique em Concluído.
- Se você está expondo o secret como uma variável de ambiente:
- 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.
- Clique em Concluído.
- Em Secrets:
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
. Ao usar o Artifact Registry, o URL tem o seguinte formato:REGION-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
. Ao usar o Artifact Registry, o URL tem o seguinte 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 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
É 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.
Para ver e fazer o download da configuração:
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
. Ao usar o Artifact Registry, o URL tem o seguinte 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
- Começa com
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
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.
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, redes, segurança para expandir a página de configuração do serviço.
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:
- Em Caminho de ativação, especifique o caminho de ativação que você está usando para secrets.
- 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.
- Clique em Concluído.
- Se você está expondo o secret como uma variável de ambiente:
- 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.
- Clique em Concluído.
- Em Secrets:
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
. Ao usar o Artifact Registry, o URL tem o seguinte formato:REGION-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
É 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.
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.
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
. Ao usar o Artifact Registry, o URL tem o seguinte 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 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
. Ao usar o Artifact Registry, o URL tem o seguinte formato:REGION-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
.
Para jobs do Cloud Run
É possível tornar um secret acessível ao job usando o console do Google Cloud, a Google Cloud CLI ou o YAML:
Console
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.
Clique em Contêiner, variáveis e secrets, conexões e segurança para expandir a página de propriedades do job.
Clique na guia Variáveis e secrets.
- 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,
- Em Caminho de ativação, especifique o caminho de ativação que você está usando para secrets.
- 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.
- Clique em Concluído.
- Se você está expondo o secret como uma variável de ambiente:
- 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.
- Clique em Concluído.
- Na guia "Variáveis e secrets":
Clique em Criar ou Atualizar.
Linha de comando
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
; 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 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.
Faça o download e veja a configuração do job que já existe usando o comando gcloud run jobs describe --format export
, que gera resultados limpos no formato YAML. Em seguida, modifique os campos descritos abaixo e faça upload do YAML modificado usando o comando gcloud run jobs replace
.
Modifique os campos somente conforme documentado.
Para ver e fazer o download da configuração:
gcloud run jobs describe JOB_NAME --format export > job.yaml
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
. Ao usar o Artifact Registry, o URL tem o seguinte formato:REGION-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 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: 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
. Ao usar o Artifact Registry, o URL tem o seguinte formato:REGION-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
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 de secrets é listada na guia Variables & Secrets.
Linha de comando
Use o comando a seguir:
gcloud run services describe SERVICE
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
Clique no job em que você tem interesse para abrir a página Detalhes do job.
Clique na guia Configuração.
Localize a definição dos secrets nos detalhes da configuração.
Linha de comando
Use o comando a seguir:
gcloud run jobs describe JOB_NAME
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.