Como usar variáveis de ambiente

Variáveis de ambiente no Cloud Functions são um recurso que permite especificar pares de chave-valor arbitrários no momento da implantação, que surgirão como variáveis de ambiente literais acessíveis pelo código no ambiente de execução. As variáveis de ambiente são armazenadas no back-end do Cloud Functions, estão vinculadas a uma única função e adotam o mesmo ciclo de vida da função a que estão vinculadas.

Como usar variáveis de ambiente

As variáveis de ambiente 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 usando a ferramenta de linha de comando gcloud e a interface do usuário do Console do Cloud.

Como definir variáveis de ambiente

Para definir uma variável 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...

Você também pode definir várias variáveis de ambiente 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 ver uma referência completa para o comando deploy, consulte gcloud functions deploy.

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

  1. Abra a página de 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. Expanda as configurações avançadas clicando em Mais.

  5. Na seção Variáveis de ambiente, defina variáveis clicando em Adicionar variável.

Como atualizar variáveis de ambiente

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

Para definir 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 usando uma lista separada por vírgulas:

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

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

  1. Abra a página de 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 Editar.

  4. Expanda as configurações avançadas clicando em Mais.

  5. Na seção Variáveis de ambiente, edite variáveis existentes ou clique em Adicionar variável para definir novas variáveis.

Como excluir variáveis de ambiente

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

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

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

gcloud functions deploy FUNCTION_NAME --clear-env-vars

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

  1. Abra a página de 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 Editar.

  4. Expanda as configurações avançadas clicando em Mais.

  5. Na seção Variáveis de ambiente, exclua uma variável clicando no X ao lado dela.

Como acessar variáveis de ambiente no ambiente de execução

Defina a variável de ambiente durante a implantação:

Node.js

gcloud functions deploy envVar --runtime nodejs8 --set-env-vars FOO=bar --trigger-http
Use estes valores da sinalização --runtime para usar versões diferentes do Node.js:
  • nodejs6 (obsoleto)
  • nodejs8
  • nodejs10 (beta)

Python

gcloud functions deploy env_vars --runtime python37 --set-env-vars FOO=bar --trigger-http

Go

gcloud functions deploy EnvVar --runtime go111 --set-env-vars FOO=bar --trigger-http

Acesse a variável de ambiente:

Node.js

No ambiente de execução, as variáveis de ambiente são acessíveis por meio da propriedade process.env no Node.js:
exports.envVar = (req, res) => {
  // Sends 'bar' as response
  res.send(process.env.FOO);
};

Python

No ambiente de execução, as variáveis de ambiente são acessíveis via os.environ no Python:
import os

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

Go

No ambiente de execução, as variáveis de ambiente são acessíveis por meio da propriedade os.Getenv() no Go:

// 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"))
}

Ciclo de vida variável

As variáveis de ambiente estão vinculadas a uma implementação de uma das Cloud Functions 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.

Variáveis de ambiente definidas automaticamente

Esta seção lista as variáveis de ambiente que são definidas automaticamente.

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

As seguintes variáveis de ambiente são definidas automaticamente para os ambientes de execução Node.js 6, Node.js 8, Python 3.7 e Go 1.11. Os ambientes de execução subsequentes do Cloud Functions usam um conjunto mais limitado de variáveis de ambiente, como descrito 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 do GCP.
GCLOUD_PROJECT Reservado: o ID do projeto atual do GCP (obsoleto).
GOOGLE_CLOUD_PROJECT Reservado: não definido, mas reservado para uso interno.
FUNCTION_TRIGGER_TYPE Reservado: o tipo de acionador 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 anteriores aceitos pelo Cloud Functions. Todos os ambientes de execução futuros no Cloud Functions 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.

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 as seguintes 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.

Como gerenciar segredos

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> ('_'), como definido no Conjunto de caracteres portáteis, e que elas não iniciem com um dígito.