Utiliser des configurations et des secrets avec les fonctions Edge

Découvrez comment transmettre des configurations et des secrets non sensibles à une fonction AEM Edge via edgeFunctions.yaml et les lire dans votre code.

Configurations ou secrets

configs et secrets sont des paires clé/valeur que vous exposez à votre fonction AEM Edge.

La différence réside dans l’endroit où réside la valeur et dans la mesure dans laquelle elle est sensible.

Où vous déclarez des configurations et des secrets

Déclarez les deux sous data dans edgeFunctions.yaml, en tant que frères de functions. Elles ne sont pas imbriquées sous une fonction individuelle.

# config/edgeFunctions.yaml
kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  configs:
    - key: TRIPS_API_BASE_URL
      value: "https://api.example.com/trips"
    - key: ADVENTURE_CACHE_TTL_SECONDS
      value: "300"
  secrets:
    - key: TRIPS_API_TOKEN
      value: ${{WKND_TRIPS_API_TOKEN}}

Les noms clés respectent la casse. Le key que vous déclarez ici est le même nom que votre code lit au moment de l’exécution.

Pour toutes les propriétés prises en charge, voir Déclarer les fonctions.

Utilisation des configurations

Les configurations contiennent des valeurs non sensibles qui varient selon l’environnement. Les valeurs de configuration sont toujours des chaînes, donc convertissez-les lorsque vous avez besoin d’un nombre ou d’une valeur booléenne.

Lire les configurations dans le code

Ouvrez le magasin de config_default, puis appelez-get() avec la clé que vous avez déclarée. L’appel est synchrone.

// src/index.js or handler file
import { ConfigStore } from "fastly:config-store";

const config = new ConfigStore("config_default");

// read a config value (always a string)
const apiBaseUrl = config.get("TRIPS_API_BASE_URL");

// cast to a number, with a fallback if the key is missing
const ttlSeconds = Number(config.get("ADVENTURE_CACHE_TTL_SECONDS") || "300");

Utiliser des secrets

Les secrets contiennent des valeurs sensibles, telles qu’un jeton API. La valeur reste dans un secret Cloud Manager. Votre edgeFunctions.yaml y fait référence avec la syntaxe ${{SECRET_NAME}}, de sorte que la valeur n’apparaît jamais dans Git.

Deux noms sont impliqués, et ils sont différents à dessein.

Cet exemple utilise une clé et un secret, le motif pour AEM as a Cloud Service. Sur Edge Delivery Services, vous répétez le modèle une fois par site, car un pipeline de configuration sert les trois sites.

Ajouter le secret sur AEM as a Cloud Service

Définissez le secret Cloud Manager et exécutez le pipeline de configuration avant de l’utiliser dans votre fonction AEM Edge. Chaque environnement (RDE, développement, évaluation, production) possède son propre onglet de configuration. Par conséquent, un secret que vous ajoutez à l’environnement de développement n’existe pas dans l’environnement d’évaluation ou de production tant que vous ne l’y avez pas ajouté également.

Ajouter le secret sur Edge Delivery Services

Edge Delivery Services dispose d’un pipeline de configuration par programme, et non d’un par site. Il déploie un seul edgeFunctions.yaml pour l’ensemble du programme, partagé par chaque site, plutôt qu’un fichier distinct par site.

Les sites de développement, d’évaluation et de production partagent tous ce pipeline. Vous ne pouvez donc pas ajouter le même nom de variable trois fois avec trois valeurs différentes et vous ne pouvez pas vous fier à un edgeFunctions.yaml spécifique à la branche pour choisir le bon.

Ajoutez le préfixe à chaque nom de variable avec son site afin que les trois sites ne soient jamais en conflit, par exemple DEV_TRIPS_API_TOKEN, STAGE_TRIPS_API_TOKEN et MAIN_TRIPS_API_TOKEN. Déclarez les trois dans le même edgeFunctions.yaml, puis laissez votre code choisir le bon au moment de l’exécution.

# config/edgeFunctions.yaml
secrets:
  - key: TRIPS_API_TOKEN_DEV
    value: ${{DEV_TRIPS_API_TOKEN}}
  - key: TRIPS_API_TOKEN_STAGE
    value: ${{STAGE_TRIPS_API_TOKEN}}
  - key: TRIPS_API_TOKEN_MAIN
    value: ${{MAIN_TRIPS_API_TOKEN}}

La fonction AEM Edge doit décider quelle clé lire au moment de l’exécution, en fonction du site qu’elle diffuse actuellement. La section suivante affiche la recherche.

Lecture de secrets dans le code

Lisez le secret au moment de l’exécution via l’assistant SecretStoreManager fourni par le standard dans src/lib/config.js. Il lit dans le magasin secret_default. L’appel est asynchrone sur les deux plateformes, mais la clé que vous recherchez est différente.

Sur AEM as a Cloud Service, la clé est fixe, car chaque environnement possède son propre secret derrière le même nom de clé :

// src/index.js or handler file
import { SecretStoreManager } from "./lib/config";

const token = await SecretStoreManager.getSecret("TRIPS_API_TOKEN");
if (!token) {
  throw new Error("TRIPS_API_TOKEN is not configured");
}

Sur Edge Delivery Services, commencez par créer la clé à partir du site actuel, car un edgeFunctions.yaml partagé déclare une clé distincte par site :

// src/index.js or handler file
import { SecretStoreManager } from "./lib/config";

const site = getCurrentSite(); // for example, "DEV", "STAGE", or "MAIN" based on the origin header
const token = await SecretStoreManager.getSecret(`TRIPS_API_TOKEN_${site}`);
if (!token) {
  throw new Error(`TRIPS_API_TOKEN_${site} is not configured`);
}

Une fois que vous disposez du jeton, utilisez-le dans votre requête sortante de la même manière sur les deux plateformes :

// use the token in an outbound request, never in a response to the client
const request = new Request("https://api.example.com/trips", {
  headers: { Authorization: `Bearer ${token}` },
});

Conservez le secret dans la fonction AEM Edge. Ne le renvoyez pas au client ou ne le consignez pas.

Directives

Ressources supplémentaires