pulumi-esc_skill

Overview

This skill provides practical guidance for using Pulumi ESC (Environments, Secrets, and Configuration) to manage centralized environments, secrets, and configuration for Pulumi stacks. It focuses on common commands, environment structure, provider integrations (OIDC, AWS, Azure, GCP), and secure secret handling. Use it to create, compose, link, and run environments with Pulumi tooling while following best practices for secrets and short-term credentials.

How this skill works

The skill explains how ESC stores YAML environment documents with imports and values, including reserved sections like environmentVariables, pulumiConfig, and files. It describes CLI-focused workflows using pulumi env commands to init, edit, set values (including fn::secret), view (get vs open), run commands in an environment, and link environments into Pulumi stacks. It also covers integrating dynamic credentials and external secret stores such as AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, and 1Password.

When to use it

• When you need a central place to compose and version environment configuration and secrets.
• When you want to generate short-term cloud credentials via OIDC for AWS, Azure, or GCP.
• When migrating stack config into reusable, layered environments.
• When you must integrate external secret stores with Pulumi-managed config.
• When running CI jobs or local commands that require environment-specific secrets.

Best practices

• Always mark sensitive values with fn::secret in environment YAML.
• Prefer OIDC short-term credentials over static cloud keys for security.
• Layer environments (base → provider → stack) and reuse imports for consistency.
• Use pulumi env run for commands that need environment variables; avoid env open unless you need revealed secrets.
• Name environments descriptively (e.g., org/my-app/production-aws) and verify with pulumi config after linking.

Example use cases

• Create a production environment that composes common base settings, provider region, and secrets, then link it to a stack with pulumi config env add.
• Configure AWS OIDC dynamic credentials in ESC and test them by running pulumi env run <env> -- aws sts get-caller-identity.
• Migrate existing per-stack config into shared environments using imports and pulumi env edit --file to apply YAML definitions.
• Integrate HashiCorp Vault or Azure Key Vault so secrets are referenced dynamically in environment values.
• Run CI pipelines with pulumi env run to inject environmentVariables without exposing secrets in logs.