Pulumi ESC (Environments, Secrets, and Configuration)

Pulumi ESC est un service centralisé pour gérer les environnements, les secrets et la configuration across cloud infrastructure et applications.

Qu'est-ce qu'ESC ?

ESC permet aux équipes de :

Centraliser les secrets et la configuration dans un seul emplacement sécurisé
Composer des environnements en important et en superposant la configuration
Générer des credentials dynamiques via OIDC pour AWS, Azure, GCP
Intégrer des magasins de secrets externes (AWS Secrets Manager, Azure Key Vault, Vault, 1Password)
Versionner et auditer tous les changements de configuration
Contrôler l'accès avec RBAC granulaire

Commandes CLI essentielles

# Create a new environment
pulumi env init <org>/<project-name>/<environment-name>

# Edit environment (opens in editor)
pulumi env edit <org>/<project-name>/<environment-name>

# Set values
pulumi env set <org>/<project-name>/<environment-name> <key> <value>
pulumi env set <org>/<project-name>/<environment-name> <key> <value> --secret

# View definition (secrets hidden)
pulumi env get <org>/<project-name>/<environment-name>

# Open and resolve (reveals secrets)
pulumi env open <org>/<project-name>/<environment-name>

# Run command with environment
pulumi env run <org>/<project-name>/<environment-name> -- <command>

# Link to Pulumi stack
pulumi config env add <project-name>/<environment-name>

Concepts clés

Distinctions entre les commandes

pulumi env get : Affiche la définition statique, les secrets apparaissent comme [secret]
pulumi env open : Résout et révèle toutes les valeurs, y compris les secrets et les credentials dynamiques
pulumi env run : Exécute des commandes avec les variables d'environnement chargées
pulumi config env add : Prend uniquement la portion <project-name>/<environment-name>

Structure de l'environnement

Les environnements sont des documents YAML avec des clés réservées au niveau supérieur :

imports : Importer et composer d'autres environnements
values : Définir la configuration et les secrets

Sous-clés réservées sous values :

environmentVariables : Mapper les valeurs aux variables d'environnement shell
pulumiConfig : Configurer les paramètres de stack Pulumi
files : Générer des fichiers avec les données d'environnement

Exemple basique

imports:
  - common/base-config

values:
  environment: production
  region: us-west-2

  dbPassword:
    fn::secret: super-secure-password

  environmentVariables:
    AWS_REGION: ${region}
    DB_PASSWORD: ${dbPassword}

  pulumiConfig:
    aws:region: ${region}
    app:dbPassword: ${dbPassword}

Travailler avec l'utilisateur

Pour les questions simples

Si l'utilisateur pose des questions basiques comme « Comment créer un environnement ? » ou « Quelle est la différence entre get et open ? », répondez directement en utilisant les informations ci-dessus.

Pour la documentation détaillée

Quand les utilisateurs ont besoin de plus d'informations, utilisez l'outil de web-fetch pour obtenir le contenu depuis la documentation officielle Pulumi ESC :

Syntaxe YAML complète et fonctions → https://www.pulumi.com/docs/esc/environments/syntax/
Intégrations de fournisseurs (AWS, Azure, GCP, Vault, 1Password) :
- AWS: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/
- Azure: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/azure-login/
- GCP: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/gcp-login/
- Fournisseurs de credentials à court terme (OIDC) : https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/
- Fournisseurs de secrets dynamiques : https://www.pulumi.com/docs/esc/integrations/dynamic-secrets/
Guide de démarrage → https://www.pulumi.com/docs/esc/get-started/
Référence CLI → https://www.pulumi.com/docs/esc/cli/commands/
- Préférez utiliser les sous-commandes pulumi env plutôt que la CLI esc.

Utilisez l'outil de web-fetch avec des prompts spécifiques pour extraire les informations pertinentes de ces docs.

Pour les tâches complexes

Quand vous aidez les utilisateurs :

Comprendre l'objectif : Configurent-ils de nouveaux environnements, migrent-ils depuis stack config, ou déboguent-ils ?
Vérifier la configuration existante : Utiliser les commandes pulumi env pour lister les environnements ou lire les définitions
Récupérer la documentation pertinente : Utiliser web-fetch pour obtenir des exemples spécifiques ou la syntaxe depuis les docs officiels
Fournir des conseils étape par étape : Parcourir le processus avec des commandes spécifiques
Valider : Les aider à tester avec pulumi env get ou pulumi preview a. N'utiliser pulumi env open que quand les valeurs résolues complètes sont nécessaires, mais avec prudence car cela révèle les secrets.

Exemple : Aider à la configuration d'AWS OIDC

Utilisateur : « Comment configurer les credentials AWS OIDC dans ESC ? »

1. Utiliser l'outil de web-fetch pour obtenir la documentation AWS OIDC depuis « https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/ »
2. Fournir à l'utilisateur la configuration
3. Demander à l'utilisateur s'il a un rôle prédéfini ou s'il a besoin qu'on en crée un
4. Configurer autant que possible de l'environnement, puis les guider à travers les étapes que vous ne pouvez pas faire pour eux
5. Les aider à tester avec `pulumi env get` ou `pulumi env open` si nécessaire

Flux de travail courants

Créer un environnement

pulumi env init my-org/my-project/dev-config
# Edit environment (accepts new definition from a file, better for agents, more difficult for users)
pulumi env edit --file /tmp/example.yml my-org/my-project/dev-config

Lier à un stack

pulumi config env add my-project/dev-config
pulumi config  # Verify environment values are accessible

Accès API (rare)

Préférez toujours les commandes CLI. N'utilisez l'API que si absolument nécessaire (ex : opérations en masse, automatisation).

Les endpoints API disponibles incluent :

GET /api/esc/environments/{orgName} - Lister les environnements
GET /api/esc/environments/{orgName}/{projectName}/{envName} - Lire la définition de l'environnement
GET /api/esc/providers?orgName={orgName} - Lister les fournisseurs disponibles

Utilisez l'outil call_pulumi_cloud_api() pour faire des requêtes si nécessaire.

Bonnes pratiques

Toujours utiliser fn::secret pour les valeurs sensibles
Préférer OIDC aux clés statiques
Utiliser des noms descriptifs comme <org>/my-app/production-aws et non <org>/app/prod
Superposer les environnements : base → cloud-provider → stack-spécifique
Vérifier que pulumi config affiche les valeurs attendues après avoir lié un environnement à un stack
Préférer utiliser pulumi env run pour les commandes ayant besoin de variables d'environnement
N'utiliser pulumi env open que si absolument nécessaire, car cela révèle les secrets

Dépannage rapide

« Environment not found » : Vérifier les permissions avec pulumi env ls -o <org>
« Secret decryption failed » : Utiliser pulumi env open et non pulumi env get
« Stack can't read values » : Vérifier pulumi config env ls pour s'assurer que le stack est listé.
- S'assurer que l'environnement est référencé uniquement par le format project-name/environment-name.
- Obtenir la définition spécifique de l'environnement avec pulumi env get <org>/<project-name>/<environment-name>.
- Vérifier que la clé pulumiConfig existe et est imbriquée sous la clé values.

pulumi-esc