Communitygithub.com

Infrastructure as Code avec Pulumi (TypeScript)

Définissez votre infrastructure cloud en TypeScript avec une sécurité de type totale, grâce à Pulumi.

Qu'est-ce que Infrastructure as Code avec Pulumi (TypeScript) ?

Cette compétence fournit un guide complet pour utiliser Pulumi avec TypeScript afin de gérer l'infrastructure cloud en tant que code. Elle couvre la création de ressources typées, l'encapsulation avec `ComponentResource`, la gestion des sorties (`Output<T>`), la configuration et les secrets, les références entre piles (`StackReference`) et l'API Automation. Les motifs clés incluent l'utilisation obligatoire de `pulumi.interpolate` pour la construction de chaînes avec des `Outputs` (évitant la concaténation), le passage systématique de `{ parent: this }` aux ressources enfants dans un `ComponentResource`, et l'appel obligatoire à `this.registerOutputs()` à la fin des constructeurs. La compétence détaille les options de cycle de vie comme `protect`, `aliases` et `transforms`, et met en garde contre les pièges fréquents tels que la création de ressources dans `.apply()` ou l'utilisation de `Config.require()` pour des valeurs sensibles. Elle est destinée aux développeurs TypeScript construisant des plateformes cloud reproductibles, multi-piles et conformes.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/infra-iac-pulumi

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Infrastructure as Code avec Pulumi

Guide rapide : Définissez votre infrastructure cloud en TypeScript avec une sécurité de type totale. Utilisez ComponentResource pour encapsuler des motifs d'infrastructure réutilisables. Passez { parent: this } à toutes les ressources enfants dans les composants. Utilisez pulumi.interpolate pour les chaînes contenant des Outputs (pas la concaténation de chaînes). Ne créez jamais de ressources dans .apply(). Utilisez Config.requireSecret() pour les valeurs sensibles. Préférez transforms aux transformations obsolètes. Appelez toujours this.registerOutputs() à la fin des constructeurs de composants.


<critical_requirements>

CRITIQUE : Avant d'utiliser cette compétence

Tout le code doit suivre les conventions du projet dans CLAUDE.md (kebab-case, exports nommés, ordre des imports, import type, constantes nommées)

(Vous DEVEZ passer { parent: this } à TOUTES les ressources enfants d'un ComponentResource – l'omettre brise l'arbre des ressources et le suivi d'état)

(Vous DEVEZ utiliser pulumi.interpolate pour les chaînes avec des Outputs – la concaténation produit silencieusement [object Object])

(Vous NE DEVEZ JAMAIS créer de ressources dans .apply() – elles n'apparaîtront pas dans pulumi preview et causeront des problèmes d'ordonnancement)

(Vous DEVEZ utiliser Config.requireSecret() pour les valeurs sensibles – Config.require() stocke les valeurs en clair dans l'état)

(Vous DEVEZ appeler this.registerOutputs() à la fin de chaque constructeur ComponentResource – l'omettre empêche le suivi des sorties)

</critical_requirements>


Ressources détaillées :

  • examples/core.md - Définitions de ressources, ressources composants, nommage, Outputs, configuration/secrets
  • examples/advanced.md - Références de pile, transforms, fournisseurs dynamiques, API Automation, Policy Packs
  • reference.md - Cadres de décision, table des options de ressources, référence API, commandes CLI

Auto-détection : Pulumi, @pulumi/pulumi, @pulumi/aws, @pulumi/gcp, @pulumi/azure, @pulumi/kubernetes, pulumi.ComponentResource, pulumi.CustomResource, pulumi.Output, pulumi.Config, pulumi.interpolate, pulumi.all, registerOutputs, StackReference, ComponentResourceOptions, CustomResourceOptions, dynamic.Resource, dynamic.ResourceProvider, LocalWorkspace, InlineProgramArgs, Automation API, CrossGuard, PolicyPack

Quand l'utiliser :

  • Définir une infrastructure cloud en TypeScript avec des API de ressources typées
  • Créer des composants d'infrastructure réutilisables avec ComponentResource
  • Gérer des architectures multi-piles avec des références de pile
  • Gérer les secrets et la configuration spécifique à l'environnement
  • Construire des plateformes d'infrastructure en libre-service avec l'API Automation
  • Écrire des politiques de conformité avec CrossGuard Policy Packs

Quand ne PAS l'utiliser :

  • Scripts shell ponctuels qui créent une seule ressource (utilisez directement la CLI du cloud)
  • Projets où l'équipe n'a aucune expérience TypeScript (envisagez d'autres langages IaC)

Motifs clés couverts :

  • Définitions de ressources avec entrées typées et nommage automatique
  • Encapsulation ComponentResource (parent, nommage, registerOutputs)
  • Outputs : apply, all, interpolate, et levage
  • Gestion de la configuration et des secrets (Config.require, Config.requireSecret, pulumi.secret)
  • Références de pile pour le partage de données entre piles
  • Options de ressources (dependsOn, protect, aliases, ignoreChanges, transforms)
  • Fournisseurs dynamiques pour des ressources CRUD personnalisées
  • API Automation pour la gestion programmatique des piles
  • CrossGuard Policy Packs pour l'application de la conformité

Philosophie

Pulumi traite l'infrastructure comme du code réel, pas comme des fichiers de configuration. TypeScript vous apporte la sécurité de type, l'autocomplétion IDE, les outils de refactoring et tout l'écosystème Node.js. Les ressources sont des objets, les dépendances sont automatiques, et la réutilisation se fait via des fonctions et des classes – pas un langage de modules personnalisé.

Principes fondamentaux :

  • Les ressources sont des objets : Chaque ressource cloud est une instance de classe TypeScript avec des entrées et sorties typées
  • Les dépendances sont automatiques : Lorsque vous passez la sortie d'une ressource comme entrée d'une autre, Pulumi déduit le graphe de dépendances
  • Réutilisation via les composants : ComponentResource encapsule plusieurs ressources en une seule unité logique avec ses propres entrées et sorties
  • Les Outputs sont des promesses : Output<T> représente une valeur qui peut ne pas être connue avant le déploiement – utilisez apply, all ou interpolate pour les manipuler, ne les dépaquetez jamais manuellement
  • L'état est géré : Pulumi suit chaque ressource dans l'état – changer un nom logique ou déplacer une ressource entre fichiers déclenche une suppression et recréation sauf si vous utilisez aliases

Motifs principaux

Motif 1 : Définitions de ressources

Chaque ressource prend un nom logique (utilisé pour le suivi d'état), un sac d'arguments (entrées typées) et des options de ressource facultatives.

const bucket = new aws.s3.Bucket(
  "data-bucket",
  {
    versioning: { enabled: true },
    lifecycleRules: [
      { enabled: true, expiration: { days: BUCKET_EXPIRY_DAYS } },
    ],
  },
  { protect: true },
); // Empêche la suppression accidentelle

Points clés : Les noms logiques doivent être uniques par type dans une pile. Pulumi ajoute automatiquement un suffixe aléatoire au nom physique pour éviter les collisions. Utilisez protect: true sur les ressources critiques. Exportez les sorties pour une consommation entre piles.

Voir examples/core.md pour le nommage des ressources, la configuration du nommage automatique et les options de fournisseur.


Motif 2 : Encapsulation ComponentResource

Enveloppez les ressources liées dans un ComponentResource pour créer des unités d'infrastructure réutilisables.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

interface StaticSiteArgs {
  indexDocument?: string;
  errorDocument?: string;
}

class StaticSite extends pulumi.ComponentResource {
  public readonly bucketName: pulumi.Output<string>;
  public readonly websiteUrl: pulumi.Output<string>;

  constructor(
    name: string,
    args: StaticSiteArgs,
    opts?: pulumi.ComponentResourceOptions,
  ) {
    super("myinfra:web:StaticSite", name, args, opts);

    const bucket = new aws.s3.BucketV2(`${name}-bucket`, {}, { parent: this });

    const website = new aws.s3.BucketWebsiteConfigurationV2(
      `${name}-website`,
      {
        bucket: bucket.id,
        indexDocument: { suffix: args.indexDocument ?? "index.html" },
        errorDocument: { key: args.errorDocument ?? "error.html" },
      },
      { parent: this },
    );

    this.bucketName = bucket.id;
    this.websiteUrl = website.websiteEndpoint;
    this.registerOutputs({
      bucketName: this.bucketName,
      websiteUrl: this.websiteUrl,
    });
  }
}

Pourquoi c'est bon : les ressources enfants utilisent { parent: this }, le nom est préfixé à partir du parent, registerOutputs est appelé, le jeton de type suit le format pkg:module:Type

Voir examples/core.md pour les motifs de composants complets avec héritage de fournisseur et ressources multi-composants.


Motif 3 : Travailler avec les Outputs

Les Outputs représentent des valeurs résolues après le déploiement. N'utilisez jamais la concaténation de chaînes – utilisez interpolate, apply, ou all.

// interpolate – template tag pour la construction de chaînes (recommandé)
const url = pulumi.interpolate`https://${bucket.bucketRegionalDomainName}/index.html`;

// apply – transformer une sortie unique
const upper = bucket.id.apply((id) => id.toUpperCase());

// all – combiner plusieurs sorties
const endpoint = pulumi
  .all([lb.dnsName, listener.port])
  .apply(([dns, port]) => `http://${dns}:${port}`);

// Levage – accéder directement aux propriétés sur les sorties de ressources
const subnetId = vpc.subnets[0].id; // Pas besoin d'apply pour les propriétés connues

Pourquoi c'est bon : interpolate gère les valeurs Output de manière transparente, all attend plusieurs valeurs, le levage évite les appels apply inutiles

Piège : Les ressources créées dans .apply() n'apparaîtront pas dans pulumi preview et peuvent causer des problèmes d'ordonnancement. Passez toujours les Outputs directement comme entrées d'autres ressources.

Voir examples/core.md pour les motifs Output, l'encapsulation pulumi.output(), et l'anti-motif apply.


Motif 4 : Configuration et secrets

Utilisez pulumi.Config pour les valeurs spécifiques à une pile. Utilisez requireSecret pour les données sensibles – cela chiffre la valeur dans l'état.

const config = new pulumi.Config();

// Valeurs de configuration simples
const region = config.require("region"); // Échoue si manquant
const nodeCount = config.getNumber("nodeCount"); // Retourne undefined si manquant

// Valeurs secrètes – chiffrées dans l'état
const dbPassword = config.requireSecret("dbPassword");
const apiKey = config.getSecret("apiKey");

// Marquer des valeurs programmatiques comme secrètes
const connectionString = pulumi.interpolate`postgres://admin:${dbPassword}@${db.endpoint}/mydb`;
// connectionString est automatiquement secret car dbPassword est secret

// Marquer explicitement une valeur comme secrète
const token = pulumi.secret(generateToken());

Point clé : Tout Output dérivé d'un secret est automatiquement marqué secret. Vous n'avez pas besoin de re-marquer les valeurs dérivées.

Voir examples/core.md pour la configuration par espace de noms, les sorties secrètes et les commandes CLI de configuration.


Motif 5 : Options de ressources

Les options de ressources contrôlent le comportement du cycle de vie. Les plus importantes :

const db = new aws.rds.Instance(
  "primary-db",
  {
    /* ... */
  },
  {
    protect: true, // Empêche la suppression accidentelle
    dependsOn: [vpc, securityGroup], // Ordonnancement explicite
    ignoreChanges: ["tags"], // Ignorer la dérive sur des propriétés spécifiques
    aliases: [{ name: "old-db-name" }], // Renommer sans recréer
    retainOnDelete: true, // Conserver la ressource cloud lors d'un pulumi destroy
    deleteBeforeReplace: true, // Pour les ressources qui doivent être uniques
    replaceOnChanges: ["engine"], // Forcer le remplacement lors de modifications spécifiques
    provider: usEastProvider, // Fournisseur explicite (région, compte)
  },
);

Piège : Changer le nom logique ou le parent d'une ressource amène Pulumi à la supprimer et la recréer. Utilisez aliases pour renommer en toute sécurité.

Voir reference.md pour la table complète des options de ressources.


Motif 6 : Références de pile

Partagez les sorties entre piles en utilisant StackReference.

// Dans la pile réseau : exporter les sorties
export const vpcId = vpc.id;
export const subnetIds = subnets.map((s) => s.id);

// Dans la pile applicative : consommer les sorties
const networkStack = new pulumi.StackReference("myorg/networking/prod");
const vpcId = networkStack.getOutput("vpcId");
const subnetIds = networkStack.getOutput("subnetIds");

// requireOutput échoue si la sortie n'existe pas (plus sûr que getOutput)
const vpcIdRequired = networkStack.requireOutput("vpcId");

Voir examples/advanced.md pour les motifs de référence de pile et getOutputDetails.


Motif 7 : Transforms

Appliquez des transformations aux ressources et à leurs enfants. Utilisez transforms (pas les transformations obsolètes). Les transforms reçoivent un objet args avec type, props, et opts, et retournent un résultat modifié ou undefined pour ignorer.

// Au niveau ressource : appliquer des tags à tous les enfants taggables d'un composant
const vpc = new MyVpcComponent(
  "vpc",
  {},
  {
    transforms: [
      (args) => {
        if (isTaggable(args.type)) {
          return {
            props: {
              ...args.props,
              tags: { ...args.props["tags"], ManagedBy: "pulumi" },
            },
            opts: args.opts,
          };
        }
        return undefined;
      },
    ],
  },
);

Différence clé avec les transformations obsolètes : transforms prend en charge la modification des enfants de composants packagés (awsx, eks), prennent en charge les callbacks asynchrones et ne passent pas d'objet Resource.

Voir examples/advanced.md pour les transforms au niveau de la pile, la modification des options et la migration depuis transformations.


Motif 8 : API Automation

Exécutez Pulumi par programmation sans CLI – pour les plateformes en libre-service, les tests d'intégration ou les outils de déploiement personnalisés.

const stack = await LocalWorkspace.createOrSelectStack({
  stackName: "dev",
  projectName: "my-platform",
  program: async () => {
    const bucket = new aws.s3.Bucket("auto-bucket");
    return { bucketName: bucket.id };
  },
});
const upResult = await stack.up({ onOutput: console.log });

Point clé : L'API Automation nécessite que la CLI Pulumi soit installée et dans le PATH – elle utilise le moteur de la CLI en arrière-plan.

Voir examples/advanced.md pour preview, destroy, mode programme local, configuration et récupération des sorties de pile.


<red_flags>

DRAPEAUX ROUGES

Haute priorité :

  • Créer des ressources dans .apply() – Elles n'apparaîtront pas dans pulumi preview, causent des problèmes d'ordonnancement et brisent le graphe de dépendances. Passez les Outputs directement comme entrées de ressources.
  • Oublier { parent: this } dans les enfants d'un ComponentResource – Les ressources apparaissent à la racine de l'arbre d'état, brisant le regroupement logique et la cascade de suppression des composants.
  • Concaténation de chaînes avec des Outputs – "https://" + bucket.id produit [object Object]. Utilisez pulumi.interpolate à la place.
  • Utiliser Config.require() pour les mots de passe/clés – Stocke la valeur en clair dans l'état. Utilisez Config.requireSecret() pour chiffrer.
  • Oublier this.registerOutputs() – Les sorties des composants ne seront pas correctement suivies dans l'état ni disponibles via les références de pile.
  • Changer les noms logiques sans alias – Pulumi supprime et recrée la ressource. Utilisez aliases: [{ name: "old-name" }] pour renommer en toute sécurité.

Priorité moyenne :

  • Compter sur les fournisseurs par défaut dans les configurations multi-régions – Utilisez des fournisseurs explicites par région. Définissez pulumi:disable-default-providers dans la configuration pour forcer.
  • Commencer par des fonctions au lieu de ComponentResource – Migrer plus tard nécessite des alias ou une recréation de ressources. Utilisez des composants dès le début.
  • Ne pas utiliser dependsOn pour les dépendances non évidentes – Pulumi déduit les dépendances du câblage Input/Output, mais les effets secondaires (propagation IAM

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Skills associés