Configure as variáveis de ambiente

É possível implantar pares arbitrários de chave-valor com uma função do Cloud Run. Esses pares são disponibilizados para a função como variáveis de ambiente literais, acessíveis pelo código no ambiente de execução ou como informações de configuração dos buildpacks do Google Cloud.

As variáveis de ambiente estão vinculadas a uma única função e não são visíveis a outras no projeto do Google Cloud. Cada variável é armazenada no back-end do Cloud Run functions e existe no mesmo ciclo de vida da função à qual está vinculada.

É possível adicionar ou remover variáveis de ambiente de execução usando a Google Cloud CLI ou o console do Google 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 complementares, use o processo de atualização descrito na próxima seção.

gcloud

Para definir uma variável de ambiente de execução usando a Google Cloud CLI, 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 Google Cloud

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

  1. Abra a página de visão geral do Functions no console do Google Cloud:

    Acesse a página de visão geral das funções do Cloud Run.

  2. Clique em Criar função.

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

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Ambiente de execução.

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

    Para instruções sobre como adicionar variáveis de ambiente a uma função existente, consulte Como atualizar variáveis de ambiente de execução.

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. Essa é 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 CLI do Google Cloud, 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 Google Cloud

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

  1. Abra a página de visão geral do Functions no console do Google Cloud:

    Acesse a página de visão geral das funções do Cloud Run.

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

  3. Clique em Editar.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Ambiente de execução.

  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 Google Cloud

Para excluir variáveis de ambiente de execução usando o Console do Google Cloud, faça o seguinte:

  1. Abra a página de visão geral do Functions no console do Google Cloud:

    Acesse a página de visão geral das funções do Cloud Run.

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

  3. Clique em Editar.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Ambiente de execução.

  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

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

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 orientadas a eventos.
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. 
gcloud functions deploy envVarMemory \
--runtime nodejs10 \
--set-env-vars FUNCTION_MEMORY_MB=2Gi \
--memory 2Gi \
--trigger-http

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 nodejs22 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão do Node.js compatível a fim de executar a função.

Python 

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

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão compatível do Python a fim de executar a função.

Go

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

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão do Go compatível a fim de executar a função.

Java 

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

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão compatível do Java a fim de executar a função.

C# 

gcloud functions deploy csharp-envVar-function \
--entry-point EnvironmentVariables.Function \
--runtime dotnet8 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão do .NET compatível a fim de executar a função.

Ruby 

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

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.

PHP 

 gcloud functions deploy envVar --runtime php83 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID do ambiente de execução de uma versão do PHP compatível a fim de executar a função.

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);
  }
}

C#

No ambiente de execução, as variáveis de ambiente são acessíveis por meio da propriedade Environment.GetEnvironmentVariable em C#:

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System;
using System.Threading.Tasks;

namespace EnvironmentVariables;

public class Function : IHttpFunction
{
    public async Task HandleAsync(HttpContext context)
    {
        string foo = Environment.GetEnvironmentVariable("FOO")
            ?? "Specified environment variable is not set.";
        await context.Response.WriteAsync(foo, context.RequestAborted);
    }
}

Ruby

No ambiente de execução, as variáveis de ambiente são acessíveis usando ENV em Ruby:

require "functions_framework"

FunctionsFramework.http "env_vars" do |_request|
  ENV["FOO"] || "Specified environment variable is not set."
end

PHP

No ambiente de execução, as variáveis de ambiente são acessíveis usando a função getenv do PHP:


use Psr\Http\Message\ServerRequestInterface;

function envVar(ServerRequestInterface $request): string
{
    return getenv('FOO') . PHP_EOL;
}

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 build 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, digamos que você quer personalizar as opções do compilador. É possível adicionar ou remover essas variáveis de ambiente de build usando a Google Cloud CLI ou a interface do console do Google Cloud.

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 complementares, 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 CLI do Google Cloud, 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 Google Cloud

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

  1. Abra a página de visão geral do Functions no console do Google Cloud:

    Acesse a página de visão geral das funções do Cloud Run.

  2. Clique em Criar função.

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

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Criar.

  6. Na seção Variáveis de ambiente de build, 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 build para funções atuais. Essa é uma abordagem não destrutiva que altera ou adiciona variáveis de ambiente de build, mas não as exclui.

gcloud

Para definir uma variável usando a CLI do Google Cloud, 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 build usando uma lista separada por vírgulas:

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

IU do Console do Google Cloud

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

  1. Abra a página de visão geral do Functions no console do Google Cloud:

    Acesse a página de visão geral das funções do Cloud Run.

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

  3. Clique em Editar.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Criar.

  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 build, 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 build definidas anteriormente com a sinalização --clear-build-env-vars:

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

IU do Console do Google Cloud

Para excluir variáveis de ambiente de build usando o Console do Google Cloud, faça o seguinte:

  1. Abra a página de visão geral do Functions no console do Google Cloud:

    Acesse a página de visão geral das funções do Cloud Run.

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

  3. Clique em Editar.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Criar.

  6. Na seção Variáveis de ambiente de build, 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 implementação de uma das Cloud Run 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.

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 secrets, recomendamos o uso do Secret Manager. Para configurar o Cloud Run functions para acessar secrets armazenados no Secret Manager, consulte Configurar secrets. Não há integração específica do Cloud Run functions ao Cloud KMS.

Portabilidade

É possível que as variáveis de ambiente que atualmente funcionam com o Cloud Run 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 Google Cloud para editar variáveis, ele avisará sempre que você definir uma variável que possa ter problemas de portabilidade, mas isso 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.