Utiliser des variables d'environnement

Vous pouvez définir des paires clé/valeur arbitraires pour Cloud Functions au moment du déploiement. Ces paires s'affichent sous forme de variables d'environnement littérales, accessibles par votre code lors de l'exécution ou en tant qu'informations de configuration pour le système buildpack. Elles sont stockées dans le backend de Cloud Functions, sont liées à une seule fonction et existent dans le même cycle de vie que la fonction à laquelle elles sont associées.

Utiliser des variables d'environnement d'exécution

Les variables d'environnement sont des paires clé/valeur déployées conjointement à une fonction. Ces variables ont pour champ d'application la fonction concernée et ne sont pas visibles par les autres fonctions de votre projet. Vous pouvez ajouter ou supprimer des variables d'environnement d'exécution à l'aide de l'outil de ligne de commande gcloud ou de l'interface utilisateur de Cloud Console.

Définir des variables d'environnement d'exécution

Utilisez ces méthodes pour établir de nouvelles variables ou remplacer complètement des variables existantes. Pour effectuer des modifications, utilisez le processus de mise à jour (l'option --update-env-vars dans gcloud) décrit dans la section suivante.

gcloud

Pour définir une variable d'environnement d'exécution à l'aide de l'outil de ligne de commande gcloud, utilisez l'option --set-env-vars au moment du déploiement :

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

Vous pouvez également définir plusieurs variables d'environnement d'exécution en utilisant une liste séparée par des virgules :

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

Si vous souhaitez stocker votre configuration dans un fichier (avec gestion des versions, par exemple), utilisez un fichier YAML avec l'option --env-vars-file :

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

le contenu du fichier .env.yaml étant le suivant :

 FOO: bar
 BAZ: boo

Dans l'exemple ci-dessus, FLAGS... fait référence aux autres options que vous transmettez lors du déploiement de votre fonction. Pour en savoir plus sur la commande deploy, reportez-vous à la documentation de référence sur gcloud functions deploy.

Interface utilisateur de Cloud Console

Vous pouvez définir des variables d'environnement d'exécution lors de la création d'une fonction dans Cloud Console :

  1. Ouvrez la page de présentation de Cloud Functions dans Cloud Console :

    Accéder à la page de présentation de Cloud Functions

  2. Cliquez sur Créer une fonction.

  3. Renseignez les champs obligatoires de votre fonction.

  4. Ouvrez la section Variables, mise en réseau et paramètres avancés.

  5. Sélectionnez l'onglet Variables d'environnement.

  6. Dans la section Variables d'environnement de compilation, cliquez sur Ajouter une variable, puis ajoutez le nom et la valeur.

Mettre à jour des variables d'environnement d'exécution

Vous pouvez également mettre à jour les variables d'environnement d'exécution pour les fonctions existantes. Il s'agit d'une approche non destructrice, qui permet de modifier ou d'ajouter des variables d'environnement sans les supprimer.

gcloud

Pour mettre à jour une variable à l'aide de l'outil de ligne de commande gcloud, utilisez l'option --update-env-vars au moment du déploiement :

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

Vous pouvez également définir plusieurs variables d'environnement d'exécution en utilisant une liste séparée par des virgules :

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

Interface utilisateur de Cloud Console

Pour mettre à jour des variables d'environnement d'exécution à l'aide de Cloud Console, procédez comme suit :

  1. Ouvrez la page de présentation de Cloud Functions dans Cloud Console :

    Accéder à la page de présentation de Cloud Functions

  2. Cliquez sur une fonction existante pour accéder à ses détails.

  3. Cliquez sur Modifier.

  4. Ouvrez la section Variables, mise en réseau et paramètres avancés.

  5. Sélectionnez l'onglet Variables d'environnement.

  6. Effectuez des modifications dans la section Variables d'environnement d'exécution.

Supprimer des variables d'environnement d'exécution

gcloud

Si vous souhaitez supprimer des variables d'environnement d'exécution de manière sélective, vous pouvez utiliser l'option --remove-env-vars au moment du déploiement :

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

Vous pouvez également effacer l'ensemble des variables d'environnement d'exécution définies précédemment à l'aide de l'option --clear-env-vars :

gcloud functions deploy FUNCTION_NAME --clear-env-vars

Interface utilisateur de Cloud Console

Pour supprimer des variables d'environnement d'exécution à l'aide de Cloud Console, procédez comme suit :

  1. Ouvrez la page de présentation de Cloud Functions dans Cloud Console :

    Accéder à la page de présentation de Cloud Functions

  2. Cliquez sur une fonction existante pour accéder à ses détails.

  3. Cliquez sur Modifier.

  4. Ouvrez la section Variables, mise en réseau et paramètres avancés.

  5. Sélectionnez l'onglet Variables d'environnement.

  6. Dans la section Variables d'environnement d'exécution, cliquez sur l'icône de corbeille à côté de la paire clé/valeur pour la supprimer.

Variables d'environnement d'exécution définies automatiquement

Cette section répertorie les variables d'environnement définies automatiquement.

Node.js 8, Python 3.7 et Go 1.11

Les variables d'environnement d'exécution suivantes sont définies automatiquement pour les environnements d'exécution Node.js 8, Python 3.7 et Go 1.11. Tous les autres environnements d'exécution Cloud Functions utilisent un ensemble plus limité de variables d'environnement, comme décrit dans la section Environnements d'exécution plus récents.

Clé Description
ENTRY_POINT Réservée : fonction à exécuter.
GCP_PROJECT Réservée : ID du projet GCP actuel.
GCLOUD_PROJECT Réservée : ID du projet GCP actuel (obsolète).
GOOGLE_CLOUD_PROJECT Réservée : non définie, mais réservée à un usage interne.
FUNCTION_TRIGGER_TYPE Réservée : type de déclencheur de la fonction.
FUNCTION_NAME Réservée : nom de la ressource de la fonction.
FUNCTION_MEMORY_MB Réservée : mémoire maximale de la fonction.
FUNCTION_TIMEOUT_SEC Réservée : délai d'exécution en secondes.
FUNCTION_IDENTITY Réservée : identité actuelle (compte de service) de la fonction.
FUNCTION_REGION Réservée : région associée à la fonction (exemple : us-central1).

Environnements d'exécution plus récents

Les environnements d'exécution plus récents définissent automatiquement moins de variables d'environnement que les anciens. Tous les langages et environnements d'exécution non mentionnés dans la section précédente utilisent cet ensemble plus limité de variables d'environnement prédéfinies.

Clé Description
FUNCTION_TARGET Réservée : fonction à exécuter.
FUNCTION_SIGNATURE_TYPE Réservée : type de la fonction : http pour les fonctions HTTP et event pour les fonctions d'arrière-plan.
K_SERVICE Réservée : nom de la ressource de la fonction.
K_REVISION Réservée : identifiant de version de la fonction.
PORT Réservée : port sur lequel la fonction est appelée.
gcloud functions deploy envVarMemory \
--runtime nodejs10 \
--set-env-vars FUNCTION_MEMORY_MB=2Gi \
--memory 2Gi \
--trigger-http

Définir et récupérer des variables d'environnement d'exécution : exemple

Définissez la variable d'environnement d'exécution :

Node.js

gcloud functions deploy envVar \
--runtime nodejs10 \
--set-env-vars FOO=bar \
--trigger-http
Vous pouvez attribuer les valeurs suivantes à l'option --runtime, afin de spécifier votre version préférée de Node.js :
  • nodejs10
  • nodejs12
  • nodejs14 (aperçu public)

Python

gcloud functions deploy env_vars \
--runtime python38 \
--set-env-vars FOO=bar \
--trigger-http
Vous pouvez attribuer les valeurs suivantes à l'option --runtime, afin de spécifier votre version préférée de Python :
  • python37
  • python38
  • python39 (aperçu public)

Go

gcloud functions deploy EnvVar \
--runtime go113 \
--set-env-vars FOO=bar \
--trigger-http
Vous pouvez attribuer les valeurs suivantes à l'option --runtime, afin de spécifier votre version préférée de Go :
  • go111 (obsolète)
  • go113

Java

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

C#

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

Ruby

gcloud functions deploy env_vars --runtime ruby26 \
--set-env-vars FOO=bar \
--trigger-http
Vous pouvez attribuer les valeurs suivantes à l'option --runtime, afin de spécifier votre version préférée de Ruby :
  • ruby26
  • ruby27

Lors de l'exécution, accédez aux variables de manière automatisée :

Node.js

Dans Node.js, utilisez la propriété process.env pour accéder aux variables d'environnement d'exécution :

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

Python

En Python, utilisez os.environ pour accéder aux variables d'environnement d'exécution :

import os

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

Go

En Go, utilisez os.Getenv() pour accéder aux variables d'environnement d'exécution :


// 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

En Java, utilisez System.getenv pour accéder aux variables d'environnement d'exécution :


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#

Au moment de l'exécution, les variables d'environnement sont accessibles via la propriété Environment.GetEnvironmentVariable en Go :

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

Ruby

Au moment de l'exécution, les variables d'environnement sont accessibles via ENV en Ruby :

require "functions_framework"

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

Utiliser des variables d'environnement de compilation

Vous pouvez également définir des variables d'environnement de compilation pour les environnements d'exécution compatibles avec les packs de création.

Les variables d'environnement de compilation sont des paires clé/valeur déployées conjointement à une fonction. Elles vous permettent de transmettre des informations de configuration aux packs de création. Par exemple, vous pouvez personnaliser les options du compilateur. Vous pouvez ajouter ou supprimer ces variables d'environnement de compilation à l'aide de l'outil de ligne de commande gcloud ou de l'interface utilisateur de Cloud Console.

Définir des variables d'environnement de compilation

Utilisez ces méthodes pour établir de nouvelles variables ou remplacer complètement des variables existantes. Pour effectuer des modifications, utilisez le processus de mise à jour (l'option --update-build-env-vars dans gcloud) décrit dans la section suivante.

gcloud

Pour définir une variable à l'aide de l'outil de ligne de commande gcloud, utilisez l'option --set-build-env-vars lors du déploiement :

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

Vous pouvez également définir plusieurs variables d'environnement de compilation en utilisant une liste séparée par des virgules :

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

Si vous souhaitez stocker votre configuration dans un fichier (avec gestion des versions, par exemple), utilisez un fichier YAML avec l'option --build-env-vars-file :

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

le contenu du fichier *.yaml étant le suivant :

 FOO: bar
 BAZ: boo

Dans l'exemple ci-dessus, FLAGS... fait référence aux autres options que vous transmettez lors du déploiement de votre fonction. Pour en savoir plus sur la commande deploy, reportez-vous à la documentation de référence sur gcloud beta functions deploy.

Interface utilisateur de Cloud Console

Vous pouvez également définir des variables d'environnement de compilation lors de la création de la fonction dans Cloud Console :

  1. Ouvrez la page de présentation de Cloud Functions dans Cloud Console :

    Accéder à la page de présentation de Cloud Functions

  2. Cliquez sur Créer une fonction.

  3. Renseignez les champs obligatoires de votre fonction.

  4. Ouvrez la section Variables, mise en réseau et paramètres avancés.

  5. Sélectionnez l'onglet Variables d'environnement.

  6. Dans la section Variables d'environnement de compilation, cliquez sur Ajouter une variable, puis ajoutez le nom et la valeur.

Mettre à jour des variables d'environnement de compilation

Vous pouvez également mettre à jour les variables d'environnement de compilation pour les fonctions existantes. Il s'agit d'une approche non destructrice, qui permet de modifier ou d'ajouter des variables d'environnement sans suppression.

gcloud

Pour définir une variable à l'aide de l'outil de ligne de commande gcloud, utilisez l'option --update-build-env-vars lors du déploiement :

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

Vous pouvez également mettre à jour plusieurs variables d'environnement de compilation en utilisant une liste séparée par des virgules :

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

Interface utilisateur de Cloud Console

Pour mettre à jour des variables d'environnement de compilation à l'aide de Cloud Console, procédez comme suit :

  1. Ouvrez la page de présentation de Cloud Functions dans Cloud Console :

    Accéder à la page de présentation de Cloud Functions

  2. Cliquez sur une fonction existante pour accéder à ses détails.

  3. Cliquez sur Modifier.

  4. Ouvrez la section Variables, mise en réseau et paramètres avancés.

  5. Sélectionnez l'onglet Variables d'environnement.

  6. Effectuez les modifications dans la section Variables d'environnement de compilation.

Supprimer des variables d'environnement de compilation

gcloud

Si vous souhaitez supprimer des variables d'environnement de compilation de manière sélective, vous pouvez utiliser l'option --remove-build-env-vars au moment du déploiement :

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

Vous pouvez également effacer l'ensemble des variables d'environnement de compilation définies précédemment à l'aide de l'option --clear-build-env-vars :

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

Interface utilisateur de Cloud Console

Pour supprimer des variables d'environnement de compilation à l'aide de Cloud Console, procédez comme suit :

  1. Ouvrez la page de présentation de Cloud Functions dans Cloud Console :

    Accéder à la page de présentation de Cloud Functions

  2. Cliquez sur une fonction existante pour accéder à ses détails.

  3. Cliquez sur Modifier.

  4. Ouvrez la section Variables, mise en réseau et paramètres avancés.

  5. Sélectionnez l'onglet Variables d'environnement.

  6. Dans la section Variables d'environnement de compilation, cliquez sur l'icône de corbeille à côté de la paire clé/valeur pour la supprimer.

Cycle de vie d'une variable

Les variables d'environnement sont liées au déploiement d'une fonction Cloud Functions et ne peuvent être définies ou modifiées que lors d'un déploiement. Si un déploiement échoue pour une raison quelconque, les modifications apportées aux variables d'environnement ne seront pas appliquées. Pour que les variables d'environnement soient modifiées, le déploiement doit être réussi.

Bonnes pratiques et variables d'environnement réservées

D'autres variables d'environnement sont définies automatiquement suivant l'environnement d'exécution utilisé par votre fonction. Celles-ci dépendent du système d'exploitation de l'environnement d'exécution (par exemple, DEBIAN_FRONTEND, SHLVL ou PATH) ainsi que de l'environnement d'exécution du langage (par exemple NODE_ENV, VIRTUAL_ENV ou GOPATH).

Les variables d'environnement fournies par l'environnement (autres que celles répertoriées dans la section Variables d'environnement définies automatiquement) pourront faire l'objet de modifications dans des versions d'exécution ultérieures. Il est déconseillé de modifier ou de dépendre de variables d'environnement que vous n'avez pas définies explicitement.

Modifier les variables d'environnement fournies par l'environnement peut avoir des conséquences imprévisibles. Les tentatives de modification de ces variables d'environnement peuvent être bloquées ou, pire, avoir des conséquences inattendues comme empêcher le lancement de certaines fonctions. Nous vous recommandons de préfixer les variables d'environnement à l'aide d'une clé unique afin d'éviter tout conflit.

Enfin, vous ne pouvez pas utiliser les variables d'environnement suivantes :

Clé Description
Vide ('') Une clé ne peut pas être une chaîne vide.
= Une clé ne peut pas contenir le caractère "=".
X_GOOGLE_ Une clé ne peut pas contenir le préfixe X_GOOGLE_.

Limites de taille

Le nombre total d'octets utilisés par les noms et les valeurs des variables d'environnement d'exécution pour une fonction individuelle est limité à 32 Kio. Cependant, il n'y a pas de limite spécifique pour les clés ou les valeurs individuelles dans cette capacité globale.

Pour les variables d'environnement de compilation, vous pouvez définir jusqu'à 100 variables, avec la chaîne de définition foo=bar limitée à 64 Kio.

Gérer les secrets

Les variables d'environnement peuvent être utilisées pour la configuration des fonctions, mais elles ne sont pas recommandées pour stocker des codes secrets, tels que les identifiants de bases de données ou les clés API. Ces valeurs plus sensibles doivent être stockées en dehors de votre code source et des variables d'environnement. Certains environnements d'exécution ou frameworks peuvent entraîner l'envoi du contenu de variables d'environnement vers les journaux, et il est déconseillé de stocker des identifiants sensibles dans les fichiers YAML, les scripts de déploiement ou les fichiers soumis à la gestion des versions.

Pour stocker des codes secrets, nous vous recommandons de consulter les bonnes pratiques de gestion des codes secrets. Notez qu'il n'existe pas d'intégration spécifique de Cloud KMS avec Cloud Functions.

Portabilité

Il est possible que les variables d'environnement qui fonctionnent actuellement avec votre fonction Cloud ne fonctionnent pas avec un environnement d'exécution différent, par exemple dans un autre langage, ou avec certains outils et bibliothèques. Il se peut également qu'elles ne soient pas acceptées par une plate-forme différente.

Pour éviter ce type de problèmes, suivez la norme POSIX pour les variables d'environnement. Si vous utilisez Cloud Console pour modifier des variables, vous êtes averti chaque fois que vous définissez une variable susceptible de présenter des problèmes de portabilité. Toutefois, la console n'empêche pas le déploiement. En règle générale, nous recommandons que les clés des variables d'environnement se composent uniquement de lettres majuscules, de chiffres et du caractère <underscore> (_), comme défini dans le jeu de caractères compatibles, et qu'elles ne commencent pas par un chiffre.