Managing Pulumi

Pulumi Management Skill

Manage and inspect Pulumi stacks, configurations, secrets, and deployments.

MANDATORY: Discovery-First Pattern

Always list stacks and check current stack before modifying infrastructure.

Phase 1: Discovery

#!/bin/bash

echo "=== Pulumi Version ==="
pulumi version 2>/dev/null

echo ""
echo "=== Available Stacks ==="
pulumi stack ls --json 2>/dev/null | jq -r '.[] | "\(.name)\t\(.current // false)\t\(.resourceCount // 0) resources\t\(.lastUpdate // "never")"' | column -t

echo ""
echo "=== Current Stack ==="
pulumi stack --json 2>/dev/null | jq '{name: .current, url: .url}'

echo ""
echo "=== Stack Outputs ==="
pulumi stack output --json 2>/dev/null | jq 'to_entries[] | {key: .key, value: .value}' | head -30

Core Helper Functions

#!/bin/bash

# Pulumi wrapper with stack selection
pu_cmd() {
    pulumi "$@" --non-interactive 2>/dev/null
}

# Safe stack selection
pu_select_stack() {
    local stack="$1"
    pulumi stack select "$stack" --non-interactive 2>/dev/null
}

# Pulumi API call (for Pulumi Cloud)
pu_api() {
    local endpoint="$1"
    curl -s -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
        "https://api.pulumi.com/api/$endpoint"
}

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Use --json output with jq filtering
• Never dump full stack exports -- extract key fields
• Use --non-interactive to prevent prompts

Common Operations

Stack Resource Inspection

#!/bin/bash
STACK="${1:-$(pulumi stack --show-name 2>/dev/null)}"
echo "=== Stack Resources: $STACK ==="
pulumi stack export --stack "$STACK" 2>/dev/null | jq '
    .deployment.resources[] |
    select(.type != "pulumi:pulumi:Stack") |
    {type: .type, urn: .urn | split("::") | last, provider: .provider | split("::")[2]}
' | head -50

echo ""
echo "=== Resource Type Summary ==="
pulumi stack export --stack "$STACK" 2>/dev/null | jq -r '
    [.deployment.resources[] | .type] | group_by(.) | map({type: .[0], count: length}) | sort_by(-.count)[] | "\(.count)\t\(.type)"
' | head -20

Preview Changes

#!/bin/bash
echo "=== Preview Changes ==="
pulumi preview --json --non-interactive 2>/dev/null | jq '{
    steps: [.steps[]? | {
        op: .op,
        urn: .urn | split("::") | last,
        type: .type
    }],
    summary: {
        create: [.steps[]? | select(.op == "create")] | length,
        update: [.steps[]? | select(.op == "update")] | length,
        delete: [.steps[]? | select(.op == "delete")] | length,
        same: [.steps[]? | select(.op == "same")] | length
    }
}'

Configuration and Secrets Management

#!/bin/bash
echo "=== Stack Configuration ==="
pulumi config --json 2>/dev/null | jq 'to_entries[] | {
    key: .key,
    secret: .value.secret,
    value: (if .value.secret then "***" else .value.value end)
}'

echo ""
echo "=== Environment Variables ==="
pulumi config env --json 2>/dev/null | jq '.' 2>/dev/null || echo "No environment configuration found"

Stack History and Rollback

#!/bin/bash
echo "=== Update History ==="
pulumi stack history --json 2>/dev/null | jq '.[0:10][] | {
    version: .version,
    kind: .kind,
    result: .result,
    timestamp: .startTime,
    resourceChanges: .resourceChanges
}'

echo ""
echo "=== Last Failed Update ==="
pulumi stack history --json 2>/dev/null | jq '
    [.[] | select(.result == "failed")] | first // "No failures found"
'

Cross-Stack References

#!/bin/bash
echo "=== Stack References ==="
pulumi stack export 2>/dev/null | jq -r '
    .deployment.resources[] |
    select(.type == "pulumi:pulumi:StackReference") |
    {name: (.urn | split("::") | last), target: .inputs.name}
'

echo ""
echo "=== All Stack Outputs ==="
for stack in $(pulumi stack ls --json 2>/dev/null | jq -r '.[].name'); do
    echo "--- $stack ---"
    pulumi stack output --stack "$stack" --json 2>/dev/null | jq 'keys' 2>/dev/null
done

Safety Rules

• NEVER run pulumi up without explicit user confirmation -- always preview first
• NEVER run pulumi destroy unless explicitly requested with confirmation
• Always use --non-interactive to prevent prompts that hang automation
• Secrets are encrypted in state -- never use pulumi config set without --secret for sensitive values
• Stack exports contain secrets in plaintext -- handle with care

Output Format

Present results as a structured report:

Managing Pulumi Report
══════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Pending operations: If a previous update was interrupted, stack may have pending operations -- use pulumi cancel or pulumi stack export/import to fix
• Secret provider mismatch: Changing secrets provider requires re-encrypting all secrets -- backup first
• Stack references: Deleting a stack that other stacks reference will break those references
• Language runtime: Pulumi requires the correct language runtime (Node.js, Python, Go, etc.) installed
• State corruption: Never manually edit exported state -- use pulumi state delete or pulumi state unprotect
• Provider version drift: Different stacks may use different provider versions -- pin in package files
• Refresh vs preview: pulumi refresh updates state from cloud; pulumi preview shows config-vs-state diff
• Protected resources: Resources with protect: true cannot be deleted -- unprotect first with pulumi state unprotect