Como usar variáveis de ambiente

É possível definir pares de chave-valor arbitrários para o Cloud Functions no momento da implantação. Esses pares são exibidos como variáveis de ambiente literais, acessíveis pelo seu código no ambiente de execução ou como informações de configuração do sistema buildpack. Eles são armazenados no back-end do Cloud Functions, estão vinculados a uma única função e existem dentro do mesmo ciclo de vida da função a que estão vinculados.

Como usar variáveis de ambiente de execução

As variáveis de ambiente de execução são pares de chave-valor implantados com uma função. Essas variáveis são definidas para o escopo da função, e não são visíveis para outras funções no projeto. É possível adicionar ou remover variáveis de ambiente de execução usando a ferramenta de linha de comando gcloud ou a IU do Console do Cloud.

Como definir variáveis de ambiente de execução

Use esses métodos para estabelecer novas variáveis ou substituir completamente as variáveis existentes. Para fazer alterações aditivas, use o processo de atualização (a sinalização --update-env-vars em gcloud) descrito na próxima seção.

gcloud

Para definir uma variável de ambiente de execução usando a ferramenta de linha de comando gcloud, use a sinalização --set-env-vars no momento da implantação:

gcloud functions deploy FUNCTION_NAME --set-env-vars FOO=bar FLAGS ...

Também é possível definir várias variáveis de ambiente de execução usando uma lista separada por vírgulas:

gcloud functions deploy FUNCTION_NAME --set-env-vars FOO=bar,BAZ=boo FLAGS...

Para armazenar sua configuração em um arquivo (por exemplo, no controle de origem), use um arquivo YAML com a sinalização --env-vars-file:

gcloud functions deploy FUNCTION_NAME --env-vars-file .env.yaml FLAGS...

em que o conteúdo do arquivo .env.yaml é:

 FOO: bar
 BAZ: boo

Nos exemplos acima, FLAGS... se refere a outras opções passadas durante a implantação da função. Para uma referência completa para o comando deploy, consulte gcloud functions deploy.

IU do Console do Cloud

É possível definir variáveis de ambiente de execução durante a criação da função no Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em Criar função.

  3. Preencha os campos obrigatórios da função.

  4. Abra a seção Variáveis, rede e configurações avançadas.

  5. Selecione a guia Variáveis de ambiente.

  6. Na seção Variáveis de ambiente de execução, clique em Adicionar variável e adicione o nome e o valor.

Como atualizar variáveis de ambiente de execução

Também é possível atualizar as variáveis de ambiente de execução para as funções atuais. É uma abordagem não destrutiva que altera ou adiciona variáveis de ambiente de execução, mas não as exclui.

gcloud

Para atualizar uma variável usando a ferramenta de linha de comando gcloud, use a sinalização --update-env-vars no momento da implantação:

gcloud functions deploy FUNCTION_NAME --update-env-vars FOO=bar

Também é possível atualizar várias variáveis de ambiente de execução usando uma lista separada por vírgulas:

gcloud functions deploy FUNCTION_NAME --update-env-vars FOO=bar,BAZ=boo

IU do Console do Cloud

Para atualizar variáveis de ambiente de execução usando o Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em uma função existente para acessar a página de detalhes.

  3. Clique em Edit.

  4. Abra a seção Variáveis, rede e configurações avançadas.

  5. Selecione a guia Variáveis de ambiente.

  6. Faça suas edições na seção Variáveis de ambiente de execução.

Como excluir variáveis de ambiente de execução

gcloud

Se você quiser remover seletivamente as variáveis de ambiente de execução, use a sinalização --remove-env-vars no momento da implantação:

gcloud functions deploy FUNCTION_NAME --remove-env-vars FOO,BAZ

Também é possível apagar todas as variáveis de ambiente de execução já definidas com a sinalização --clear-env-vars:

gcloud functions deploy FUNCTION_NAME --clear-env-vars

IU do Console do Cloud

Para excluir variáveis de ambiente de execução usando o Console do Cloud, siga estas etapas:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em uma função existente para acessar a página de detalhes.

  3. Clique em Edit.

  4. Abra a seção Variáveis, rede e configurações avançadas.

  5. Selecione a guia Variáveis de ambiente.

  6. Na seção Variáveis de ambiente de execução, clique no ícone de lixeira ao lado do par de chave-valor para excluí-lo.

Variáveis de ambiente de execução definidas automaticamente

Nesta seção, listamos as variáveis de ambiente de execução que são definidas automaticamente.

Node.js 6, Node.js 8, Python 3.7 e Go 1.11

As seguintes variáveis do ambiente de execução são definidas automaticamente para os ambientes de execução Node.js 6, Node.js 8, Python 3.7 e Go 1.11. Todos os outros tempos de execução do Cloud Functions usam um conjunto mais limitado de variáveis de ambiente, como explicado em Ambientes de execução do Node.js 10 e posteriores.

Chave Descrição
ENTRY_POINT Reservado: a função a ser executada.
GCP_PROJECT Reservado: o ID do projeto atual no GCP.
GCLOUD_PROJECT Reservado: o ID do projeto atual no GCP (obsoleto).
GOOGLE_CLOUD_PROJECT Reservado: não definido, mas reservado para uso interno.
FUNCTION_TRIGGER_TYPE Reservado: o tipo de gatilho da função.
FUNCTION_NAME Reservado: o nome do recurso da função.
FUNCTION_MEMORY_MB Reservado: a memória máxima da função.
FUNCTION_TIMEOUT_SEC Reservado: o tempo limite de execução em segundos.
FUNCTION_IDENTITY Reservado: a identidade atual (conta de serviço) da função.
FUNCTION_REGION Reservado: a região da função (exemplo: us-central1).

Ambientes de execução do Node.js 10 e posteriores

O ambiente de execução do Node.js 10 define automaticamente menos variáveis de ambiente que os ambientes de execução anteriores aceitos pelo Cloud Functions. Todas as linguagens e os ambientes de execução, além daqueles mencionados na seção anterior, usarão esse conjunto mais limitado de variáveis de ambiente predefinidas.

Chave Descrição
FUNCTION_TARGET Reservado: a função a ser executada.
FUNCTION_SIGNATURE_TYPE Reservado: o tipo da função: http para funções HTTP e event para funções em segundo plano.
K_SERVICE Reservado: o nome do recurso da função.
K_REVISION Reservado: o identificador da versão da função.
PORT Reservado: a porta pela qual a função é invocada.

Como configurar e recuperar variáveis de ambiente de execução: um exemplo

Defina a variável de ambiente de execução:

Node.js

gcloud functions deploy envVar \
--runtime nodejs10 \
--set-env-vars FOO=bar \
--trigger-http
É possível usar os seguintes valores na sinalização --runtime para especificar a versão preferencial do Node.js:
  • nodejs10
  • nodejs12

Python

gcloud functions deploy env_vars \
--runtime python37 \
--set-env-vars FOO=bar \
--trigger-http
É possível usar os seguintes valores da sinalização --runtime para especificar a versão preferencial do Python:
  • python37
  • python38

Go

gcloud functions deploy EnvVar \
--runtime go111 \
--set-env-vars FOO=bar \
--trigger-http
É possível usar os seguintes valores para a sinalização --runtime para especificar sua versão Go preferencial:
  • go111
  • go113

Java

gcloud functions deploy java-envVar-function \
--entry-point functions.EnvVars \
--runtime java11 \
--memory 512MB \
--set-env-vars FOO=bar \
--trigger-http

Acesse as variáveis de maneira programática no momento da execução:

Node.js

Em Node.js, use a propriedade process.env para acessar variáveis de ambiente de execução:

exports.envVar = (req, res) => {
  // Sends 'bar' as response
  res.send(process.env.FOO);
};

Python

No Python, use os.environ para acessar as variáveis de ambiente de execução:

import os

def env_vars(request):
    return os.environ.get('FOO', 'Specified environment variable is not set.')

Go

Em Go, use os.Getenv() para acessar as variáveis de ambiente de execução:


// Package tips contains tips for writing Cloud Functions in Go.
package tips

import (
	"fmt"
	"net/http"
	"os"
)

// EnvVar is an example of getting an environment variable in a Go function.
func EnvVar(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "FOO: %q", os.Getenv("FOO"))
}

Java

Em Java, use System.getenv para acessar variáveis de ambiente de execução:


import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;

public class EnvVars implements HttpFunction {

  // Returns the environment variable "foo" set during function deployment.
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    BufferedWriter writer = response.getWriter();
    String foo = System.getenv("FOO");
    if (foo == null) {
      foo = "Specified environment variable is not set.";
    }
    writer.write(foo);
  }
}

Como usar variáveis de ambiente de build

Também é possível definir variáveis de ambiente de criação para ambientes de execução compatíveis com pacotes de criação.

Variáveis de ambiente de compilação são pares de chave-valor implantados com uma função que permite passar informações de configuração para pacotes de criação. Por exemplo, convém personalizar as opções do compilador. É possível adicionar ou remover essas variáveis de ambiente de build usando a ferramenta de linha de comando gcloud ou a IU do Console do Cloud.

Como usar o gcloud

Como o recurso de variáveis do ambiente de build está na visualização, para usar gcloud, é necessário ter o componente Beta gcloud instalado.

Se você precisar instalar o componente Beta ou quiser verificar se ele está instalado, na linha de comando, execute o seguinte comando:

gcloud components install beta

Como definir variáveis de ambiente de build

Use esses métodos para estabelecer novas variáveis ou substituir completamente as variáveis existentes. Para fazer alterações aditivas, use o processo de atualização (a sinalização --update-build-env-vars em gcloud) descrito na próxima seção.

gcloud

Para definir uma variável usando a ferramenta de linha de comando gcloud, use a sinalização --set-build-env-vars no momento da implantação:

gcloud beta functions deploy FUNCTION_NAME --set-build-env-vars FOO=bar FLAGS...

Também é possível definir várias variáveis de ambiente de build usando uma lista separada por vírgulas:

gcloud functions deploy FUNCTION_NAME --set-build-env-vars FOO=bar,BAZ=boo FLAGS...

Para armazenar sua configuração em um arquivo (por exemplo, no controle de origem), use um arquivo YAML com a sinalização --build-env-vars-file:

gcloud functions deploy FUNCTION_NAME --build-env-vars-file FILE_NAME.yaml FLAGS...

em que o conteúdo do arquivo *.yaml é:

 FOO: bar
 BAZ: boo

Nos exemplos acima, FLAGS... se refere a outras opções passadas durante a implantação da função. Para uma referência completa para o comando deploy, consulte gcloud beta functions deploy.

IU do Console do Cloud

Também é possível definir variáveis de ambiente de build durante a criação da função no Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em Criar função.

  3. Preencha os campos obrigatórios da função.

  4. Abra a seção Variáveis, rede e configurações avançadas.

  5. Selecione a guia Variáveis de ambiente.

  6. Na seção Variáveis de ambiente de compilação, clique em Adicionar variável e adicione o nome e o valor.

Como atualizar variáveis de ambiente de build

Também é possível atualizar variáveis de ambiente de compilação para funções atuais. É uma abordagem não destrutiva que altera ou adiciona variáveis de ambiente de compilação, mas não as exclui.

gcloud

Para definir uma variável usando a ferramenta de linha de comando gcloud, use a sinalização --update-build-env-vars no momento da implantação:

gcloud functions deploy FUNCTION_NAME --update-build-env-vars FOO=bar

Também é possível atualizar várias variáveis de ambiente de compilação usando uma lista separada por vírgulas:

gcloud functions deploy FUNCTION_NAME --update-env-vars FOO=bar,BAZ=boo

IU do Console do Cloud

Para atualizar variáveis de ambiente de build usando o Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em uma função existente para acessar a página de detalhes.

  3. Clique em Edit.

  4. Abra a seção Variáveis, rede e configurações avançadas.

  5. Selecione a guia Variáveis de ambiente.

  6. Faça suas edições na seção Variáveis de ambiente de build.

Como excluir variáveis de ambiente de build

gcloud

Se você quiser remover seletivamente variáveis de ambiente de compilação, use a sinalização --remove-build-env-vars no momento da implantação:

gcloud functions deploy FUNCTION_NAME --remove-build-env-vars FOO,BAZ

Também é possível apagar todas as variáveis de ambiente de compilação definidas anteriormente com a sinalização --clear-build-env-vars:

gcloud functions deploy FUNCTION_NAME --clear-build-env-vars

IU do Console do Cloud

Para excluir variáveis de ambiente de build usando o Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em uma função existente para acessar a página de detalhes.

  3. Clique em Edit.

  4. Abra a seção Variáveis, rede e configurações avançadas.

  5. Selecione a guia Variáveis de ambiente.

  6. Na seção Variáveis de ambiente de criação, clique no ícone de lixeira ao lado do par de chave-valor para excluí-lo.

Ciclo de vida variável

Todas as variáveis de ambiente estão vinculadas a uma implantação de uma das Funções do Cloud e só podem ser definidas ou alteradas com uma implantação. Se uma implantação falhar por algum motivo, todas as alterações feitas nas variáveis de ambiente não serão aplicadas. As mudanças na variável de ambiente precisam de uma implantação bem-sucedida.

Práticas recomendadas e variáveis de ambiente reservadas

Algumas outras variáveis de ambiente são definidas automaticamente, dependendo do ambiente de execução usado pela função. Eles são baseados no sistema operacional do ambiente de execução (por exemplo, DEBIAN_FRONTEND, SHLVL ou PATH) e no ambiente de execução da linguagem (por exemplo, NODE_ENV, VIRTUAL_ENV ou GOPATH).

Variáveis de ambiente fornecidas pelo ambiente (além das listadas em Variáveis de ambiente definidas automaticamente) podem ser alteradas em futuras versões do ambiente de execução. Como prática recomendada, recomendamos não depender de ou modificar variáveis de ambiente que você não tenha definido explicitamente.

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

Por fim, não é possível usar estas variáveis de ambiente:

Chave Descrição
Vazia ('') As chaves não podem ser uma string vazia.
= As chaves não podem conter o caractere "=".
X_GOOGLE_ As chaves não podem conter o prefixo X_GOOGLE_.

Limites de tamanho

O número total de bytes usados pelos nomes e valores das variáveis de ambiente para uma função individual é limitado a 32 KiB. Porém, não há limites específicos sobre chaves ou valores individuais nessa capacidade geral.

Para variáveis de ambiente de criação, até 100 variáveis podem ser definidas, com a string de definição foo=bar limitada a 64 KiB.

Como gerenciar secrets

As variáveis de ambiente podem ser usadas na configuração da função, mas não são recomendadas como uma maneira de armazenar segredos, como credenciais de banco de dados ou chaves de API. Esses valores mais confidenciais precisam ser armazenados fora do código-fonte e das variáveis de ambiente externas. Alguns ambientes de execução ou o uso de alguns frameworks podem fazer com que o conteúdo de variáveis de ambiente seja enviado para registros, e armazenar credenciais confidenciais em arquivos YAML, scripts de implantação ou controle de origem não é recomendado.

Para armazenar segredos, recomendamos consultar as práticas recomendadas para gerenciamento de segredos. Não há integração específica do Cloud Functions com o Cloud KMS.

Portabilidade

É possível que as variáveis de ambiente que atualmente funcionam com o Cloud Function não funcionem com um ambiente de execução diferente, como em uma linguagem diferente ou com determinadas ferramentas ou bibliotecas. Também é possível que elas não sejam aceitos por uma plataforma diferente.

Evite esses problemas seguindo o padrão POSIX para variáveis de ambiente. Se você usar o Console do Cloud para editar variáveis, o Console do Cloud avisará sempre que você definir uma variável que possa ter problemas de portabilidade, mas não impedirá a implantação. Como regra geral, recomendamos que as chaves de variáveis de ambiente consistam somente em letras maiúsculas, dígitos e <underscore> (_), conforme definido no Conjunto de caracteres portáteis e que elas não comecem com um dígito.