Variables et mappage de variables avec App Lifecycle Manager

Ce document explique le fonctionnement des variables, du mappage de variables et des dépendances dans App Lifecycle Manager.

App Lifecycle Manager 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 plans, peuvent être interconnectées via des dépendances, ce qui permet une orchestration sophistiquée et un provisionnement automatisé. La gestion de ces unités et de leurs interactions passe par des variables et le mappage de variables.

Vous pouvez créer des déploiements complexes, modulaires et évolutifs avec un provisionnement automatisé, une communication inter-unités et des options de configuration flexibles. Examinez attentivement votre hiérarchie de variables, vos relations de dépendance et vos mappages de variables pour optimiser votre architecture SaaS et vos workflows de gestion dans App Lifecycle Manager.

Unités et variables

Les unités sont au cœur d'App Lifecycle Manager. Elles 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 plan. Elles vous permettent de paramétrer vos configurations Terraform, ce qui les rend réutilisables et adaptables dans différents environnements et déploiements.

Variables obligatoires pour le provisionnement des unités

Bien que vous puissiez définir des variables personnalisées pour vos unités, App Lifecycle Manager s'appuie également sur un ensemble de variables obligatoires. Ces variables sont automatiquement reconnues et gérées par App Lifecycle Manager, 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_number) : cette variable spécifie l' Google Cloud ID du projet dans lequel les ressources de votre unité seront déployées. Vous pouvez utiliser soit project_id et project_number, soit tenant_id et tenant_project_number. Ce champ est nécessaire pour la création et la gestion des ressources dans le projet approprié Google Cloud .

    Vous trouverez l'ID de votre projet dans la Google Cloud console, sur la page "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 Google Cloud numéro du projet. Vous pouvez utiliser project_number ou tenant_project_number de manière interchangeable.

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

  • actuation_sa : cette variable représente l'adresse e-mail du compte de service d'activation. Ce compte de service est un compte de service géré par l'utilisateur qu'App Lifecycle Manager 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'activation 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 offre une meilleure isolation entre vos déploiements.

    Pour en savoir plus sur la configuration et l'octroi d'autorisations aux comptes de service d'activation, consultez 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 App Lifecycle Manager, il est important de comprendre la hiérarchie des valeurs de variables utilisées lors des opérations sur les unités.

L'ordre est le suivant (de la priorité la plus basse à la priorité la plus élevée) :

App Lifecycle Manager résout les valeurs de variables dans cet ordre :

  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 est 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 sur les unités : lorsque vous effectuez une opération sur une unité telle que provision ou upgrade, vous pouvez fournir explicitement des variables d'entrée dans le cadre de la requête d'opération. Les variables fournies dans une opération sur une 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 genre d'unité peuvent obtenir des valeurs de 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 via les mappages de dépendances remplacent les valeurs des opérations sur les unités, 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 référence à l'aide de versions, personnaliser des opérations spécifiques et obtenir dynamiquement les valeurs les plus importantes et prioritaires à partir des dépendances d'unité (priorité la plus élevée).

Dépendances d'unité

App Lifecycle Manager vous permet de définir des dépendances entre les unités. Cela 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 des dépendances dans un genre d'unité. Lorsque vous créez une unité d'un genre d'unité particulier, App Lifecycle Manager gère automatiquement ses dépendances.

Définition des dépendances 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, App Lifecycle Manager vérifie automatiquement l'existence de ces unités de dépendance.

Si une unité de dépendance n'est pas trouvée, App Lifecycle Manager la provisionne automatiquement avant de provisionner l'unité dépendante.

App Lifecycle Manager s'assure que les unités de dépendance sont provisionnées avant leurs unités dépendantes, en respectant l'ordre correct des opérations.

Mappage de variables

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

Le mappage de variables est défini dans le genre 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 de l'atelier de programmation fourni, App UnitKind comporte un FromMapping pour récupérer la variable de sortie cluster_endpoint de la dépendance Cluster UnitKind. Cela permet à l'application de se connecter au cluster Kubernetes nouvellement provisionné.

  • ToMapping: ToMapping permet de transmettre des 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é) : lorsque la valeur est false, App Lifecycle Manager utilise les variables d'entrée spécifiées dans le 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 est réutilisée comme dépendance. Si aucune unité correspondante n'est trouvée, une nouvelle unité de dépendance est provisionnée. Cela est utile pour réutiliser des ressources partagées telles que des clusters.
    • true: lorsque la valeur est true, la variable d'entrée dans le ToMapping n'est pas utilisée pour la recherche de dépendances. Cela signifie qu'une nouvelle unité de dépendance est 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 dans le 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 genre d'unité de cluster. Les unités du même projet et de la même région réutilisent 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éclenche alors le provisionnement d'un nouveau cluster Kubernetes isolé.

Gérer les secrets

Les variables App Lifecycle Manager ne sont pas destinées à stocker des informations sensibles telles que des mots de passe, des clés API ou des certificats. Le stockage direct de secrets dans des variables présente des risques pour la sécurité. Les valeurs de variables peuvent être enregistrées et potentiellement exposées via des sorties système, ce qui augmente le risque d'accès non autorisé.

Pour une gestion sécurisée des secrets dans vos applications App Lifecycle Manager, nous vous recommandons vivement d'utiliser Secret Manager.

Étape suivante