Variables et mappage de variables avec l'environnement d'exécution SaaS

Ce document explique le fonctionnement des variables, du mappage de variables et des dépendances dans l'environnement d'exécution SaaS.

L'environnement d'exécution SaaS vous permet de déployer et de gérer des applications SaaS complexes en les organisant en unités modulaires. Ces unités, définies par des configurations Terraform dans des blueprints, peuvent être interconnectées par le biais de dépendances, ce qui permet une orchestration sophistiquée et un provisionnement automatisé. La gestion de ces unités et de leurs interactions passe principalement par les variables et le mappage des variables.

Vous pouvez créer des déploiements complexes, modulaires et évolutifs avec un provisionnement automatisé, une communication entre les unités et des options de configuration flexibles. Examinez attentivement la hiérarchie de vos variables, les relations de dépendance et les mappages de variables pour optimiser votre architecture SaaS et vos workflows de gestion dans l'environnement d'exécution SaaS.

Unités et variables

Les unités sont au cœur de l'environnement d'exécution SaaS. Les unités utilisent des variables pour personnaliser leur déploiement et leur comportement. Ces variables sont essentiellement des variables Terraform que vous pouvez définir dans le fichier variables.tf de votre blueprint. Elles vous permettent de paramétrer vos configurations Terraform, ce qui les rend réutilisables et adaptables à différents environnements et déploiements.

Variables obligatoires pour le provisionnement d'unités

Bien que vous puissiez définir des variables personnalisées pour vos unités, l'environnement d'exécution SaaS s'appuie également sur un ensemble de variables obligatoires. Ces variables sont automatiquement reconnues et gérées par SaaS Runtime, même si elles ne sont pas explicitement définies dans votre configuration Terraform.

Les variables obligatoires sont les suivantes :

  • project_id et project_number (ou tenant_project_id et tenant_project_id) : cette variable spécifie l'ID du projet Google Cloud dans lequel les ressources de votre unité seront déployées. Vous pouvez utiliser project_id et project_number, ou tenant_id et tenant_project_id. Ce champ est nécessaire pour la création et la gestion des ressources dans le bon projet Google Cloud .

    Vous pouvez trouver l'ID de votre projet dans la console Google Cloud sur la page du tableau de bord. Recherchez le champ ID du projet dans la fiche Informations sur le projet de la section Présentation de Cloud.

  • project_number ou tenant_project_number : semblable à project_id, cette variable représente le numéro du projet Google Cloud . Vous pouvez utiliser project_number ou tenant_project_number de manière interchangeable.

    Vous trouverez le numéro de votre projet à côté de son ID dans la fiche Informations sur le projet de la section Présentation de Cloud de la page Tableau de bord de la console Google Cloud .

  • actuation_sa : cette variable représente l'adresse e-mail du compte de service d'actionnement. Ce compte de service est un compte de service géré par l'utilisateur que SaaS Runtime utilise (via Infrastructure Manager) pour exécuter vos configurations Terraform lors du provisionnement, de la mise à jour ou du déprovisionnement des unités.

    Nous vous recommandons d'utiliser un compte de service d'actionnement dédié par locataire (ou unité) pour appliquer le principe du moindre privilège. Cela limite l'impact potentiel des failles de sécurité et permet une meilleure isolation entre vos déploiements.

    Pour en savoir plus sur la configuration et l'octroi d'autorisations aux comptes de service d'actionnement, consultez la présentation du produit.

Hiérarchie des variables d'unité

Les variables d'unité peuvent être définies et provenir de plusieurs emplacements. Lorsque vous utilisez SaaS Runtime, il est important de comprendre la hiérarchie des valeurs de variables utilisées lors des opérations unitaires.

Voici l'ordre de priorité (de la plus basse à la plus haute) :

L'environnement d'exécution SaaS résout les valeurs des variables dans l'ordre suivant :

  1. Variables d'entrée existantes sur l'unité : si une variable est déjà définie sur la ressource d'unité elle-même (à partir d'une opération ou d'une configuration précédente, par exemple), cette valeur a la priorité la plus basse. Si une valeur de variable est définie directement sur l'unité, elle sera remplacée si une valeur est trouvée à partir de sources plus haut dans la hiérarchie.

  2. Valeurs par défaut de la version : les valeurs par défaut de la version sont appliquées si une variable n'est pas déjà définie sur l'unité, mais elles remplacent les variables d'unité existantes.

  3. Opérations unitaires : lorsque vous effectuez une opération unitaire telle que provision ou upgrade, vous pouvez fournir explicitement des variables d'entrée dans la requête d'opération. Les variables fournies dans une opération d'unité remplacent les valeurs par défaut de la version et les variables d'unité existantes.

  4. Mappages de variables d'entrée des dépendances : lorsqu'une unité dépend d'autres unités, les mappages de variables définis dans le type d'unité peuvent obtenir les valeurs des variables à partir des variables de sortie des unités de dépendance. Il s'agit de la source de priorité la plus élevée. Les variables obtenues par le biais de mappages de dépendances remplacent les valeurs des opérations d'unité, les valeurs par défaut de la version et les variables d'unité existantes.

Cette approche hiérarchique offre flexibilité et contrôle sur la gestion de vos variables. Vous pouvez établir des configurations persistantes directement sur l'unité (priorité la plus basse), définir des valeurs par défaut de base à l'aide des versions, personnaliser pour des opérations spécifiques et obtenir dynamiquement les valeurs les plus importantes et prioritaires à partir des dépendances des unités (priorité la plus élevée).

Dépendances d'unité

L'environnement d'exécution SaaS vous permet de définir des dépendances entre les unités. C'est important pour créer des applications SaaS complexes où différents composants dépendent les uns des autres. Les dépendances garantissent que les unités associées sont provisionnées et gérées de manière coordonnée.

Vous définissez les dépendances dans un genre d'unité. Lorsque vous créez une unité d'un type d'unité particulier, l'environnement d'exécution SaaS gère automatiquement ses dépendances.

Définition de la dépendance dans le genre d'unité

Dans la définition UnitKind, vous spécifiez une liste de dépendances, chacune faisant référence à un autre UnitKind et lui attribuant un alias. Cet alias est utilisé pour référencer la dépendance dans les mappages de variables :

  message UnitKind {
    // ... other fields ...

    // List of other unit kinds that this release will depend on.
    repeated Dependency dependencies = 4
        [(.google.api.field_behavior) = OPTIONAL];
    // ...
  }

  message Dependency {
    // The unit kind of the dependency.
    string unit_kind = 1 [
      (.google.api.field_behavior) = REQUIRED,
      (.google.api.field_behavior) = IMMUTABLE,
      (.google.api.resource_reference) = {
        type: "saasservicemgmt.googleapis.com/UnitKind"
      }
    ];

    // An alias for the dependency. Used for input variable mapping.
    string alias = 2 [(.google.api.field_behavior) = REQUIRED];
  }

Provisionnement automatique des dépendances

Lorsque vous demandez à provisionner une unité dont les dépendances sont définies dans son UnitKind, l'environnement d'exécution SaaS vérifie automatiquement l'existence de ces unités de dépendance.

Si une unité de dépendance n'est pas trouvée, l'environnement d'exécution SaaS la provisionnera automatiquement avant de provisionner l'unité dépendante.

L'environnement d'exécution SaaS s'assure que les unités de dépendance sont provisionnées avant leurs unités dépendantes, ce qui permet de maintenir l'ordre correct des opérations.

Mappage des variables

Le mappage des variables est le mécanisme permettant de transmettre des données (valeurs de variables) entre les unités dépendantes et leurs dépendances. C'est essentiel pour configurer les unités dépendantes en fonction des sorties de leurs dépendances.

Le mappage des variables est défini dans le type d'unité dépendante et utilise FromMapping et ToMapping :

  • FromMapping : FromMapping permet de récupérer les variables de sortie d'une unité de dépendance et de les mapper aux variables d'entrée de l'unité dépendante. C'est ainsi qu'une unité dépendante peut obtenir des informations de ses dépendances, telles que des points de terminaison de connexion ou des ID de ressources.

    message VariableMapping {
  // ...
  oneof mapping_type {
    // Output variables which will get their values from dependencies
    FromMapping from = 2 [(.google.api.field_behavior) = OPTIONAL];
    // ...
  }
}

message FromMapping {
  // Alias of the dependency that the outputVariable will pass its value to
  string dependency = 1 [(.google.api.field_behavior) = REQUIRED];

  // Name of the outputVariable on the dependency
  string output_variable = 2 [(.google.api.field_behavior) = REQUIRED];
}

    Dans l'exemple d'atelier de programmation fourni, App UnitKind possède un FromMapping pour récupérer la variable de sortie cluster_endpoint à partir de la dépendance Cluster UnitKind. Cela permet à l'application de se connecter au cluster Kubernetes nouvellement provisionné.

  • ToMapping : ToMapping permet de transmettre les variables d'entrée de l'unité dépendante aux variables d'entrée d'une unité de dépendance. Cela vous permet de configurer des unités de dépendance en fonction des paramètres fournis pour l'unité dépendante.

    message VariableMapping {
  // ...
  oneof mapping_type {
    // ...
    // Input variables whose values will be passed on to dependencies.
    ToMapping to = 3 [(.google.api.field_behavior) = OPTIONAL];
  }
}

message ToMapping {
  // Alias of the dependency that the inputVariable will pass its value to
  string dependency = 1 [(.google.api.field_behavior) = REQUIRED];

  // Name of the inputVariable on the dependency
  string input_variable = 2 [(.google.api.field_behavior) = REQUIRED];

  // Tells EasySaaS if this mapping should be used during lookup or not
  bool ignore_for_lookup = 3 [(.google.api.field_behavior) = OPTIONAL];
}

    Dans l'atelier de programmation, App UnitKind utilise ToMapping pour transmettre les variables d'entrée tenant_project_id et tenant_project_number à la dépendance Cluster UnitKind. Cela garantit que le cluster Kubernetes est créé dans le bon projet.

  • ignore_for_lookup dans ToMapping : le champ ignore_for_lookup dans ToMapping contrôle le comportement de recherche des dépendances. Il s'agit d'une valeur booléenne :

    • false (ou non spécifié) : lorsqu'il est défini sur false, l'environnement d'exécution SaaS utilise les variables d'entrée spécifiées dans ToMapping comme clés de recherche pour trouver une unité de dépendance existante. Si une unité avec des variables d'entrée correspondantes est trouvée, elle sera réutilisée comme dépendance. Si aucune unité correspondante n'est trouvée, une nouvelle unité de dépendance sera provisionnée. Cela permet de réutiliser des ressources partagées telles que des clusters.
    • true : lorsque la valeur est définie sur true, la variable d'entrée dans ToMapping n'est pas utilisée pour la recherche de dépendances. Cela signifie qu'une nouvelle unité de dépendance sera toujours provisionnée, même si des unités avec les mêmes variables d'entrée existent déjà. Cela est utile lorsque vous avez besoin de dépendances dédiées et non partagées pour chaque unité dépendante.

Exemple : Cluster Kubernetes partagé

Si vous souhaitez réutiliser un cluster Kubernetes pour plusieurs unités d'application au sein du même projet, vous devez utiliser ToMapping avec ignore_for_lookup défini sur false et mapper des variables telles que tenant_project_id et region au type d'unité de cluster. Les unités d'un même projet et d'une même région réutiliseraient alors le même cluster.

Exemple : cluster Kubernetes dédié par application

Si vous avez besoin d'un cluster Kubernetes dédié pour chaque unité d'application, vous devez utiliser ToMapping avec ignore_for_lookup défini sur true ou éviter complètement les variables de recherche ToMapping. Chaque unité d'application déclenchera alors le provisionnement d'un nouveau cluster Kubernetes isolé.

Gérer les secrets

Les variables d'exécution SaaS ne sont pas destinées au stockage d'informations sensibles telles que des mots de passe, des clés API ou des certificats. Stocker des secrets directement dans des variables présente des risques pour la sécurité. Les valeurs des variables peuvent être consignées et potentiellement exposées via les sorties système, ce qui augmente le risque d'accès non autorisé.

Pour gérer les secrets de manière sécurisée dans vos applications SaaS Runtime, nous vous recommandons vivement d'utiliser Secret Manager.

Étapes suivantes