Esta página foi traduzida pela API Cloud Translation.

Configure variáveis de ambiente para serviços

Esta página descreve como configurar variáveis de ambiente para o seu serviço do Cloud Run.

Pode usar variáveis de ambiente para a configuração do serviço, mas não as recomendamos como forma de armazenar segredos, como credenciais de bases de dados ou chaves de API. Os valores confidenciais devem ser armazenados fora do código fonte e das variáveis de ambiente. Para armazenar segredos, recomendamos que use o Secret Manager. Para configurar serviços para aceder a segredos armazenados no Secret Manager, consulte o artigo Configurar segredos.

Qualquer alteração de configuração leva à criação de uma nova revisão. As revisões subsequentes também vão receber automaticamente esta definição de configuração, a menos que faça atualizações explícitas para a alterar.

Funções necessárias

Para receber as autorizações de que precisa para configurar e implementar serviços do Cloud Run, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

Programador do Cloud Run (roles/run.developer) no serviço Cloud Run
Utilizador da conta de serviço (roles/iam.serviceAccountUser) na identidade do serviço

Se estiver a implementar um serviço ou uma função a partir do código fonte, também tem de ter funções adicionais concedidas no seu projeto e na conta de serviço do Cloud Build.

Para ver uma lista de funções e autorizações de IAM associadas ao Cloud Run, consulte os artigos Funções de IAM do Cloud Run e Autorizações de IAM do Cloud Run. Se o seu serviço do Cloud Run interage com Google Cloud APIs, como as bibliotecas cliente da Google Cloud, consulte o guia de configuração da identidade do serviço. Para mais informações sobre a atribuição de funções, consulte as autorizações de implementação e faça a gestão do acesso.

Número máximo de variáveis de ambiente e limites

Pode definir um máximo de 1000 variáveis de ambiente para um serviço do Cloud Run.

O comprimento máximo da variável é de 32 KB.

Defina variáveis de ambiente

Pode definir variáveis de ambiente para serviços novos e existentes. Tenha em atenção que a flag --set-env-vars é uma ação destrutiva que elimina as variáveis de ambiente definidas anteriormente que não estão incluídas na nova lista de variáveis de ambiente.

As variáveis de ambiente estão associadas a uma revisão de serviço específica e não são visíveis para outros serviços no seu projeto Google Cloud .

Pode definir variáveis de ambiente através da Google Cloud consola, da CLI gcloud ou de um ficheiro YAML quando cria um novo serviço ou implementa uma nova revisão:

Consola

Na Google Cloud consola, aceda ao Cloud Run:

Aceda ao Cloud Run
Selecione Serviços no menu e clique em Implementar contentor para configurar um novo serviço. Se estiver a configurar um serviço existente, clique no serviço e, de seguida, em Editar e implementar nova revisão.
Se estiver a configurar um novo serviço, preencha a página de definições iniciais do serviço e, de seguida, clique em Contentores, volumes, rede, segurança para expandir a página de configuração do serviço.
Clique no separador Contentor.
- No separador Variáveis e segredos, clique em Adicionar variável para adicionar uma nova variável e especifique o nome que quer para a variável e o respetivo valor nos campos Nome e Valor. Para mais informações sobre como definir várias variáveis de ambiente ou ignorar carateres especiais, consulte o artigo Defina várias variáveis de ambiente.
Clique em Criar ou Implementar.

gcloud

Nota: se estiver a usar a CLI gcloud para implementar uma função, tem de especificar as flags necessárias quando executar gcloud run deploy e ter as funções necessárias concedidas.

Para especificar variáveis de ambiente quando implementa o seu serviço, use a flag --set-env-vars:

gcloud run deploy SERVICE --image IMAGE_URL --set-env-vars KEY1=VALUE1,KEY2=VALUE2

Substitua o seguinte:

SERVICE: o nome do seu serviço.
KEY1=VALUE1,KEY2=VALUE2: a lista separada por vírgulas de nomes e valores de variáveis.
IMAGE_URL: uma referência à imagem do contentor, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se usar o Artifact Registry, o repositório REPO_NAMEtem de já estar criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

Para mais informações sobre como definir várias variáveis de ambiente ou carateres especiais de escape, consulte o artigo Defina várias variáveis de ambiente.

YAML

Se estiver a criar um novo serviço, ignore este passo. Se estiver a atualizar um serviço existente, transfira a respetiva configuração YAML:
```
gcloud run services describe SERVICE --format export > service.yaml
```
Atualize os atributos name e value no atributo env em containers::
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      name: REVISION
    spec:
      containers:
      - image: IMAGE
        env:
        - name: KEY-1
          value: VALUE-1
        - name: KEY-N
          value: VALUE-N
```
Substitua o seguinte:
- SERVICE: o nome do seu serviço do Cloud Run.
- IMAGE_URL: uma referência à imagem do contentor, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se usar o Artifact Registry, o repositório REPO_NAMEtem de já estar criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
- KEY-1, VALUE-1: a variável de ambiente e o valor. Opcionalmente, adicione mais variáveis e valores conforme necessário.
- REVISION com um novo nome de revisão ou elimine-o (se existir). Se fornecer um novo nome de revisão, este tem de cumprir os seguintes critérios:
  - Começa com SERVICE-
  - Contém apenas letras minúsculas, números e -
  - Não termina com um -
  - Não exceder 63 carateres
Crie ou atualize o serviço com o seguinte comando:
```
gcloud run services replace service.yaml
```

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

Adicione o seguinte a um recurso google_cloud_run_v2_service na sua configuração do Terraform:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-env-var"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      # Environment variables
      env {
        name  = "foo"
        value = "bar"
      }
      env {
        name  = "baz"
        value = "quux"
      }
    }
  }
}

O recurso google_cloud_run_v2_service anterior especifica que define a variável de ambiente foo como bar e a variável de ambiente baz como quux. Atualize as variáveis de ambiente conforme necessário.

Defina variáveis de ambiente predefinidas no contentor

Pode usar a declaração ENV num Dockerfile para definir valores predefinidos para variáveis de ambiente:

ENV KEY1=VALUE1,KEY2=VALUE2

Ordem de precedência: variáveis do contentor versus variáveis de serviço

Se definir uma variável de ambiente predefinida no contentor e também definir uma variável de ambiente com o mesmo nome no serviço do Cloud Run, o valor definido no serviço tem precedência.

Defina várias variáveis de ambiente

Pode definir várias variáveis de ambiente através do ficheiro .env ou da flag --set-env-vars.

Defina várias variáveis de ambiente através do ficheiro `.env`

Consola

Na Google Cloud consola, aceda ao Cloud Run:

Aceda ao Cloud Run
Selecione Serviços no menu e clique em Implementar contentor para configurar um novo serviço. Se estiver a configurar um serviço existente, clique no serviço e, de seguida, em Editar e implementar nova revisão.
Se estiver a configurar um novo serviço, preencha a página de definições iniciais do serviço e, de seguida, clique em Contentores, volumes, rede, segurança para expandir a página de configuração do serviço.
Clique no separador Contentor.
- No separador Variáveis e segredos, clique em Adicionar variável e cole o conteúdo do ficheiro .env no campo Nome. O Cloud Run preenche automaticamente o campo Valor e cria novas variáveis para cada par de chave-valor que definir no ficheiro .env.
Clique em Criar ou Implementar.

gcloud

Para especificar várias variáveis de ambiente a partir do ficheiro .env, execute o seguinte comando:

gcloud beta run deploy SERVICE --image=IMAGE_URL --env-vars-file=ENV_FILE_PATH

Substitua o seguinte:

SERVICE: o nome do seu serviço do Cloud Run.
IMAGE_URL: uma referência à imagem do contentor, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se usar o Artifact Registry, o repositório REPO_NAMEtem de já estar criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
ENV_FILE_PATH: caminho para o ficheiro .env.

Defina várias variáveis de ambiente com a flag `--set-env-vars`

Se tiver várias variáveis de ambiente que não podem ser listadas no formato KEY1=VALUE1,KEY2=VALUE2, pode repetir a flag --set-env-vars várias vezes:

   [...]
   --set-env-vars "KEY1=VALUE1" \
   --set-env-vars "KEY2=VALUE2" \
   --set-env-vars "KEY3=VALUE3"

Escape de carateres de vírgula

Uma vez que o caráter de vírgula , é usado para dividir as variáveis de ambiente, se a sua variável de ambiente contiver carateres de vírgula como valores, tem de escapar a esses delimitadores especificando um caráter delimitador diferente, por exemplo, @:

--set-env-vars "^@^KEY1=value1,value2,value3@KEY2=..."

Atualize as variáveis de ambiente

Pode atualizar as variáveis de ambiente para serviços existentes. Esta é uma abordagem não destrutiva que altera ou adiciona variáveis de ambiente, mas não elimina as variáveis de ambiente definidas anteriormente.

Consola

Para atualizar as variáveis de ambiente através da consola Google Cloud :

Na Google Cloud consola, aceda ao Cloud Run:

Aceda ao Cloud Run
Selecione o seu serviço na lista e clique em Editar e implementar nova revisão.
Clique no separador Contentor.
No separador Variáveis e segredos, edite os campos Nome ou Valor e clique em Concluído.
Clique em Implementar.

gcloud

Nota: se estiver a usar a CLI gcloud para implementar uma função, tem de especificar as flags necessárias quando executar gcloud run deploy e ter as funções necessárias concedidas.

Para atualizar as variáveis de ambiente de um serviço existente, use a flag --update-env-vars:

gcloud run services update SERVICE --update-env-vars KEY1=VALUE1,KEY2=VALUE2

Substitua o seguinte:

SERVICE: o nome do seu serviço.
KEY1=VALUE1,KEY2=VALUE2: a lista separada por vírgulas de nomes e valores de variáveis.

Para atualizar as variáveis de ambiente de um serviço multirregional existente, use o comando gcloud beta run multi-region-services update.

Veja as definições das variáveis de ambiente

Para ver as definições atuais das variáveis de ambiente do seu serviço do Cloud Run:

Consola

Na Google Cloud consola, aceda ao Cloud Run:

Aceda ao Cloud Run
Clique no serviço que lhe interessa para abrir a página Detalhes do serviço.
Clique no separador Revisões.
No painel de detalhes à direita, a definição de variáveis de ambiente é apresentada no separador Contentor.

gcloud

Use o seguinte comando:
```
gcloud run services describe SERVICE
```
Localize a definição de variáveis de ambiente na configuração devolvida.

Elimine variáveis de ambiente

Pode eliminar variáveis de ambiente para serviços existentes.

Consola

Para eliminar variáveis de ambiente através da Google Cloud consola:

Na Google Cloud consola, aceda ao Cloud Run:

Aceda ao Cloud Run
Selecione o seu serviço na lista e clique em Editar e implementar nova revisão.
Clique no separador Contentor.
No separador Variáveis e segredos, mova o cursor para a esquerda do campo Valor da variável de ambiente que está a remover para apresentar o ícone Eliminar e clique nele.
Clique em Concluído.
Clique em Implementar.

gcloud

Nota: se estiver a usar a CLI gcloud para implementar uma função, tem de especificar as flags necessárias quando executar gcloud run deploy e ter as funções necessárias concedidas.

Para remover seletivamente variáveis de ambiente de um serviço existente,use a flag --remove-env-vars:

gcloud run services update SERVICE --remove-env-vars KEY1,KEY2

Substitua o seguinte:

SERVICE: o nome do seu serviço.
KEY1,KEY2: a lista separada por vírgulas de nomes de variáveis.

Em alternativa, limpe todas as variáveis de ambiente definidas anteriormente com a flag --clear-env-vars:

gcloud run services update SERVICE --clear-env-vars

Substitua SERVICE pelo nome do seu serviço.

Práticas recomendadas

A secção seguinte realça algumas das práticas recomendadas para configurar variáveis de ambiente.

Variáveis de ambiente reservadas para serviços

As variáveis de ambiente definidas no contrato de tempo de execução do contentor estão reservadas e não podem ser definidas. Em particular, a variável de ambiente PORT é injetada no contentor pelo Cloud Run. Não deve defini-lo manualmente.

Variáveis de ambiente reservadas adicionais ao implementar funções

O Cloud Run define automaticamente as seguintes variáveis de ambiente de tempo de execução quando implementa funções:

FUNCTION_TARGET: a função a executar.
FUNCTION_SIGNATURE_TYPE: o tipo da função: http para funções HTTP e event para funções orientadas por eventos.

Algumas variáveis de ambiente adicionais são definidas automaticamente consoante o tempo de execução usado pela sua função. Estes baseiam-se no sistema operativo do tempo de execução, por exemplo, DEBIAN_FRONTEND, SHLVL ou PATH, e no tempo de execução da linguagem, por exemplo, NODE_ENV, VIRTUAL_ENV ou GOPATH.

As variáveis de ambiente fornecidas pelo ambiente, exceto as que são definidas automaticamente, podem mudar em versões de tempo de execução futuras. Como prática recomendada, recomendamos que não dependa nem modifique variáveis de ambiente que não tenha definido explicitamente.

A modificação de variáveis de ambiente fornecidas pelo ambiente pode levar a resultados imprevisíveis. As tentativas de modificar essas variáveis de ambiente podem ser bloqueadas ou, pior, levar a consequências não intencionais, como funções que não podem ser iniciadas. Como prática recomendada, considere prefixar quaisquer variáveis de ambiente com uma chave única para evitar conflitos.

Variáveis de ambiente inválidas

Não pode usar as seguintes variáveis de ambiente:

Chave	Descrição
Vazio ('')	As chaves não podem ser uma string vazia.
`=`	As chaves não podem conter o caráter "=".
`X_GOOGLE_`	As chaves não podem conter o prefixo `X_GOOGLE_`.

Exemplo de código

Para ver um exemplo de código que mostra como aceder às variáveis de ambiente no seu código, consulte o artigo Processar configurações confidenciais com o Secret Manager no tutorial de autenticação do utilizador final.

O que se segue?

Pode usar variáveis de ambiente para definir a configuração dos buildpacks. Para ver detalhes específicos do idioma, consulte a documentação dos buildpacks para:

Se estiver a implementar a partir da origem e precisar de personalizar variáveis no momento da compilação, consulte o artigo Defina variáveis de ambiente de compilação.

Configure variáveis de ambiente para serviços Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Funções necessárias

Número máximo de variáveis de ambiente e limites

Defina variáveis de ambiente

Consola

gcloud

YAML

Terraform

Defina variáveis de ambiente predefinidas no contentor

Ordem de precedência: variáveis do contentor versus variáveis de serviço

Defina várias variáveis de ambiente

Defina várias variáveis de ambiente através do ficheiro .env

Consola

gcloud

Defina várias variáveis de ambiente com a flag --set-env-vars

Escape de carateres de vírgula

Atualize as variáveis de ambiente

Consola

gcloud

Veja as definições das variáveis de ambiente

Consola

gcloud

Elimine variáveis de ambiente

Consola

gcloud

Práticas recomendadas

Variáveis de ambiente reservadas para serviços

Variáveis de ambiente reservadas adicionais ao implementar funções

Variáveis de ambiente inválidas

Exemplo de código

O que se segue?

Configure variáveis de ambiente para serviços

Defina várias variáveis de ambiente através do ficheiro `.env`

Defina várias variáveis de ambiente com a flag `--set-env-vars`