pulumi-best-practices
Skill19 starsChanged 8 months agoMITView on GitHub
Best practices for writing reliable Pulumi programs. Covers Output handling, resource dependencies, component structure, secrets management, safe refactoring with aliases, and deployment workflows.
- Reads credentials
In this repository53 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/skills/agent-rules/AGENTS.mdAGENTS.md
- .github/workflows/AGENTS.mdAGENTS.md
- pkg/AGENTS.mdAGENTS.md
- agent-ready-goSkill
- agent-rulesSkill
- architecture-designerSkill
- cli-developerSkill
- cloudformation-to-pulumiSkill
- code-reviewerSkill
- commitlintSkill
- commitSkill
- csharp-developerSkill
- decideSkill
- dep-upgradeSkill
- design-principlesSkill
- devops-engineerSkill
- flux-cliSkill
- flux-operator-cliSkill
- golang-proSkill
- go-nolint-auditSkill
- javascript-proSkill
- kubernetes-specialistSkill
- lint-fixSkill
- markdownlintSkill
- prSkill
- pull-request-msg-with-ghSkill
- pulumi-arm-to-pulumiSkill
- pulumi-automation-apiSkill
- pulumi-cdk-to-pulumiSkill
- pulumi-cliSkill
- pulumi-componentSkill
- pulumi-escSkill
- pulumi-goSkill
- pulumi-neoSkill
- pulumi-pythonSkill
- pulumi-terraform-to-pulumiSkill
- pulumi-typescriptSkill
- python-proSkill
- reviewSkill
- roadmapSkill
- rust-async-patternsSkill
- rust-best-practicesSkill
- rust-engineerSkill
- scoutSkill
- security-auditSkill
- spring-boot-engineerSkill
- sre-engineerSkill
- sync-websiteSkill
- tailscale-installSkill
- tech-debtSkill
- the-foolSkill
- typescript-proSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 175
Use a consistent type URN pattern: organization:module:ComponentName
- Very specific: line 176
Call registerOutputs() at the end of the constructor
- Distinctive: line 380
Add alias during refactor
- Very specific: line 381
Run pulumi up on all stacks
- Distinctive: line 382
Remove alias after all stacks updated (optional, but keeps code clean)
- Distinctive: line 395
No preview step anywhere in the CI/CD workflow for a given change
- Distinctive: line 460
Run preview on every PR
- Distinctive: line 486
When reviewing Pulumi code, verify:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Pulumi Best Practices
When to Use This Skill
Invoke this skill when:
- Writing new Pulumi programs or components
- Reviewing Pulumi code for correctness
- Refactoring existing Pulumi infrastructure
- Debugging resource dependency issues
- Setting up configuration and secrets
Practices
1. Never Create Resources Inside apply()
Why: Resources created inside apply() don't appear in pulumi preview, making changes unpredictable. Pulumi cannot properly track dependencies, leading to race conditions and deployment failures.
Detection signals:
new aws.or other resource constructors inside.apply()callbacks- Resource creation inside
pulumi.all([...]).apply() - Dynamic resource counts determined at runtime inside apply
Wrong:
const bucket = new aws.s3.Bucket("bucket");
bucket.id.apply(bucketId => {
// WRONG: This resource won't appear in preview
new aws.s3.BucketObject("object", {
bucket: bucketId,
content: "hello",
});
});Right:
const bucket = new aws.s3.Bucket("bucket");
// Pass the output directly - Pulumi handles the dependency
const object = new aws.s3.BucketObject("object", {
bucket: bucket.id, // Output<string> works here
content: "hello",
});When apply is appropriate:
- Transforming output values for use in tags, names, or computed strings
- Logging or debugging (not resource creation)
- Conditional logic that affects resource properties, not resource existence
Reference: https://www.pulumi.com/docs/concepts/inputs-outputs/
2. Pass Outputs Directly as Inputs
Why: Pulumi builds a directed acyclic graph (DAG) based on input/output relationships. Passing outputs directly ensures correct creation order. Unwrapping values manually breaks the dependency chain, causing resources to deploy in wrong order or reference values that don't exist yet.
Detection signals:
- Variables extracted from
.apply()used later as resource inputs awaiton output values outside of apply- String concatenation with outputs instead of
pulumi.interpolate
Wrong:
const vpc = new aws.ec2.Vpc("vpc", { cidrBlock: "10.0.0.0/16" });
// WRONG: Extracting the value breaks the dependency chain
let vpcId: string;
vpc.id.apply(id => { vpcId = id; });
const subnet = new aws.ec2.Subnet("subnet", {
vpcId: vpcId, // May be undefined, no tracked dependency
cidrBlock: "10.0.1.0/24",
});Right:
const vpc = new aws.ec2.Vpc("vpc", { cidrBlock: "10.0.0.0/16" });
const subnet = new aws.ec2.Subnet("subnet", {
vpcId: vpc.id, // Pass the Output directly
cidrBlock: "10.0.1.0/24",
});For string interpolation:
// WRONG
const name = bucket.id.apply(id => `prefix-${id}-suffix`);
// RIGHT - use pulumi.interpolate for template literals
const name = pulumi.interpolate`prefix-${bucket.id}-suffix`;
// RIGHT - use pulumi.concat for simple concatenation
const name = pulumi.concat("prefix-", bucket.id, "-suffix");Reference: https://www.pulumi.com/docs/concepts/inputs-outputs/
3. Use Components for Related Resources
Why: ComponentResource classes group related resources into reusable, logical units. Without components, your resource graph is flat, making it hard to understand which resources belong together, reuse patterns across stacks, or reason about your infrastructure at a higher level.
Detection signals:
- Multiple related resources created at top level without grouping
- Repeated resource patterns across stacks that should be abstracted
- Hard to understand resource relationships from the Pulumi console
Wrong:
// Flat structure - no logical grouping, hard to reuse
const bucket = new aws.s3.Bucket("app-bucket");
const bucketPolicy = new aws.s3.BucketPolicy("app-bucket-policy", {
bucket: bucket.id,
policy: policyDoc,
});
const originAccessIdentity = new aws.cloudfront.OriginAccessIdentity("app-oai");
const distribution = new aws.cloudfront.Distribution("app-cdn", { /* ... */ });Right:
interface StaticSiteArgs {
domain: string;
content: pulumi.asset.AssetArchive;
}
class StaticSite extends pulumi.ComponentResource {
public readonly url: pulumi.Output<string>;
constructor(name: string, args: StaticSiteArgs, opts?: pulumi.ComponentResourceOptions) {
super("myorg:components:StaticSite", name, args, opts);
// Resources created here - see practice 4 for parent setup
const bucket = new aws.s3.Bucket(`${name}-bucket`, {}, { parent: this });
// ...
this.url = distribution.domainName;
this.registerOutputs({ url: this.url });
}
}
// Reusable across stacks
const site = new StaticSite("marketing", {
domain: "marketing.example.com",
content: new pulumi.asset.FileArchive("./dist"),
});Component best practices:
- Use a consistent type URN pattern:
organization:module:ComponentName - Call
registerOutputs()at the end of the constructor - Expose outputs as class properties for consumers
- Accept
ComponentResourceOptionsto allow callers to set providers, aliases, etc.
For in-depth component authoring guidance (args design, multi-language support, testing, distribution), use skill pulumi-component.
Reference: https://www.pulumi.com/docs/concepts/resources/components/
4. Always Set parent: this in Components
Why: When you create resources inside a ComponentResource without setting parent: this, those resources appear at the root level of your stack's state. This breaks the logical hierarchy, makes the Pulumi console hard to navigate, and can cause issues with aliases and refactoring. The parent relationship is what makes the component actually group its children.
Detection signals:
- ComponentResource classes that don't pass
{ parent: this }to child resources - Resources inside a component appearing at root level in the console
- Unexpected behavior when adding aliases to components
Wrong:
class MyComponent extends pulumi.ComponentResource {
constructor(name: string, opts?: pulumi.ComponentResourceOptions) {
super("myorg:components:MyComponent", name, {}, opts);
// WRONG: No parent set - this bucket appears at root level
const bucket = new aws.s3.Bucket(`${name}-bucket`);
}
}Right:
class MyComponent extends pulumi.ComponentResource {
constructor(name: string, opts?: pulumi.ComponentResourceOptions) {
super("myorg:components:MyComponent", name, {}, opts);
// RIGHT: Parent establishes hierarchy
const bucket = new aws.s3.Bucket(`${name}-bucket`, {}, {
parent: this
});
const policy = new aws.s3.BucketPolicy(`${name}-policy`, {
bucket: bucket.id,
policy: policyDoc,
}, {
parent: this
});
}
}What parent: this provides:
- Resources appear nested under the component in Pulumi console
- Deleting the component deletes all children
- Aliases on the component automatically apply to children
- Clear ownership in state files
Reference: https://www.pulumi.com/docs/concepts/resources/components/
5. Encrypt Secrets from Day One
Why: Secrets marked with --secret are encrypted in state files, masked in CLI output, and tracked through transformations. Starting with plaintext config and converting later requires credential rotation, reference updates, and audit of leaked values in logs and state history.
Detection signals:
- Passwords, API keys, tokens stored as plain config
- Connection strings with embedded credentials
- Private keys or certificates in plaintext
Wrong:
# Plaintext - will be visible in state and logs
pulumi config set databasePassword hunter2
pulumi config set apiKey sk-1234567890Right:
# Encrypted from the start
pulumi config set --secret databasePassword hunter2
pulumi config set --secret apiKey sk-1234567890In code:
const config = new pulumi.Config();
// This retrieves a secret - the value stays encrypted
const dbPassword = config.requireSecret("databasePassword");
// Creating outputs from secrets preserves secrecy
const connectionString = pulumi.interpolate`postgres://user:${dbPassword}@host/db`;
// connectionString is also a secret Output
// Explicitly mark values as secret
const computed = pulumi.secret(someValue);Use Pulumi ESC for centralized secrets:
# Pulumi.yaml
environment:
- production-secrets # Pull from ESC environment# ESC manages secrets centrally across stacks
esc env set production-secrets db.password --secret "hunter2"What qualifies as a secret:
- Passwords and passphrases
- API keys and tokens
- Private keys and certificates
- Connection strings with credentials
- OAuth client secrets
- Encryption keys
References:
6. Use Aliases When Refactoring
Why: Renaming resources, moving them into components, or changing parents causes Pulumi to see them as new resources. Without aliases, refactoring destroys and recreates resources, potentially causing downtime or data loss. Aliases preserve resource identity through refactors.
Detection signals:
- Resource rename without alias
- Moving resource into or out of a ComponentResource
- Changing the parent of a resource
- Preview shows delete+create when update was intended
Wrong:
// Before: resource named "my-bucket"
const bucket = new aws.s3.Bucket("my-bucket");
// After: renamed without alias - DESTROYS THE BUCKET
const bucket = new aws.s3.Bucket("application-bucket");Right:
// After: renamed with alias - preserves the existing bucket
const bucket = new aws.s3.Bucket("application-bucket", {}, {
aliases: [{ name: "my-bucket" }],
});Moving into a component:
// Before: top-level resource
const bucket = new aws.s3.Bucket("my-bucket");
// After: inside a component - needs alias with old parent
class MyComponent extends pulumi.ComponentResource {
constructor(name: string, opts?: pulumi.ComponentResourceOptions) {
super("myorg:components:MyComponent", name, {}, opts);
const bucket = new aws.s3.Bucket("bucket", {}, {
parent: this,
aliases: [{
name: "my-bucket",
parent: pulumi.rootStackResource, // Was at root
}],
});
}
}Alias types:
// Simple name change
aliases: [{ name: "old-name" }]
// Parent change
aliases: [{ name: "resource-name", parent: oldParent }]
// Full URN (when you know the exact previous URN)
aliases: ["urn:pulumi:stack::project::aws:s3/bucket:Bucket::old-name"]Lifecycle:
- Add alias during refactor
- Run
pulumi upon all stacks - Remove alias after all stacks updated (optional, but keeps code clean)
Reference: https://www.pulumi.com/docs/iac/concepts/resources/options/aliases/
7. Preview Before Every Deployment
Why: pulumi preview shows exactly what will be created, updated, or destroyed. Surprises in production come from skipping preview. A resource showing "replace" when you expected "update" means imminent destruction and recreation.
Detection signals:
- Running
pulumi up --yesinteractively without reviewing changes - No preview step anywhere in the CI/CD workflow for a given change
- Preview output not reviewed before merge or deployment approval
Wrong:
# Deploying blind
pulumi up --yesRight:
# Always preview first
pulumi preview
# Review the output, then deploy
pulumi upWhat to look for in preview:
+ create- New resource will be created~ update- Existing resource will be modified in place- delete- Resource will be destroyed+-replace- Resource will be destroyed and recreated (potential downtime)~+-replace- Resource will be updated, then replaced
Warning signs:
- Unexpected
replaceoperations (check for immutable property changes) - Resources being deleted that shouldn't be
- More changes than expected from your code diff
CI/CD integration:
# GitHub Actions example
jobs:
preview:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Pulumi Preview
uses: pulumi/actions@v5
with:
command: preview
stack-name: production
env:
PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
deploy:
needs: preview
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
steps:
- name: Pulumi Up
uses: pulumi/actions@v5
with:
command: up
stack-name: productionPR workflow:
- Run preview on every PR
- Post preview output as PR comment
- Require preview review before merge
- Deploy only on merge to main
References:
- https://www.pulumi.com/docs/cli/commands/pulumi_preview/
- https://www.pulumi.com/docs/iac/packages-and-automation/continuous-delivery/github-actions/
Quick Reference
| Practice | Key Signal | Fix |
| No resources in apply | new Resource() inside .apply() | Move resource outside, pass Output directly |
| Pass outputs directly | Extracted values used as inputs | Use Output objects, pulumi.interpolate |
| Use components | Flat structure, repeated patterns | Create ComponentResource classes |
| Set parent: this | Component children at root level | Pass { parent: this } to all child resources |
| Secrets from day one | Plaintext passwords/keys in config | Use --secret flag, ESC |
| Aliases when refactoring | Delete+create in preview | Add alias with old name/parent |
| Preview before deploy | pulumi up --yes | Always run pulumi preview first |
Validation Checklist
When reviewing Pulumi code, verify:
- No resource constructors inside
apply()callbacks - Outputs passed directly to dependent resources
- Related resources grouped in ComponentResource classes
- Child resources have
{ parent: this } - Sensitive values use
config.requireSecret()or--secret - Refactored resources have aliases preserving identity
- Deployment process includes preview step
Related Skills
- pulumi-component: Deep guide to authoring ComponentResource classes, designing args interfaces, multi-language support, testing, and distribution. Use skill
pulumi-component. - pulumi-automation-api: Programmatic orchestration of multiple stacks. Use skill
pulumi-automation-api. - pulumi-esc: Centralized secrets and configuration management. Use skill
pulumi-esc.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

