Pulumi Automation Api

pulumi/agent-skills/pulumi/skills/pulumi-automation-api

作者 pulumi900eacf4444f無授權條款70 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫昨天更新

Load this skill when a user asks how to run Pulumi programmatically, embed Pulumi in an application, orchestrate multiple stacks in code, build a self-service infrastructure portal, replace pulumi CLI shell scripts with code, or use the Pulumi Automation API (LocalWorkspace, createOrSelectStack, inline programs). Also load for questions about multi-stack sequencing, parallel deployments, or passing outputs between stacks via code.

僅含說明DevOps & Cloud Software Development

AI 產生的概覽

說明如何以程式碼方式透過 Pulumi Automation API 編排部署，涵蓋多堆疊順序、內嵌程式與輸出傳遞。

功能: 此技能說明如何用 Pulumi Automation API 在程式碼中執行 Pulumi 操作，而不透過命令列。內容涵蓋 LocalWorkspace、createOrSelectStack、內嵌與本機原始碼程式、組態設定、讀取輸出、錯誤處理，以及多堆疊的循序與平行部署。產出的是指引與程式碼範例，而非可執行指令碼。
適用情境: 適合將 Pulumi 嵌入應用程式、以程式碼編排多個堆疊、建置自助式基礎設施入口網站或自訂 CLI，或以程式碼取代 Shell 與 Makefile 編排的情況。也適合回答多堆疊順序、平行部署及堆疊間輸出傳遞的問題。
執行需求: 未包含指令碼，僅為說明性內容。依範例操作需具備 Pulumi 專案、對應語言的 Pulumi Automation API 套件，以及目標雲端平台的存取權限。

Pulumi Automation API

When to Use This Skill

Invoke this skill when:

Orchestrating deployments across multiple Pulumi stacks
Embedding Pulumi operations in custom applications
Building self-service infrastructure platforms
Replacing fragile Bash/Makefile orchestration scripts
Creating custom CLIs for infrastructure management
Building web applications that provision infrastructure

What is Automation API

Automation API provides programmatic access to Pulumi operations. Instead of running pulumi up from the CLI, you call functions in your code that perform the same operations.

typescript

import * as automation from "@pulumi/pulumi/automation";
// Create or select a stackconst stack = await automation.LocalWorkspace.createOrSelectStack({    stackName: "dev",    projectName: "my-project",    program: async () => {        // Your Pulumi program here    },});
// Run pulumi up programmaticallyconst upResult = await stack.up({ onOutput: console.log });console.log(`Update summary: ${JSON.stringify(upResult.summary)}`);

import * as automation from "@pulumi/pulumi/automation";
// Create or select a stackconst stack = await automation.LocalWorkspace.createOrSelectStack({    stackName: "dev",    projectName: "my-project",    program: async () => {        // Your Pulumi program here    },});
// Run pulumi up programmaticallyconst upResult = await stack.up({ onOutput: console.log });console.log(`Update summary: ${JSON.stringify(upResult.summary)}`);

When to Use Automation API

Good Use Cases

Multi-stack orchestration:

When you split infrastructure into multiple focused projects, Automation API helps offset the added complexity by orchestrating operations across stacks:

text

infrastructure → platform → application     ↓              ↓            ↓   (VPC)      (Kubernetes)   (Services)

infrastructure → platform → application     ↓              ↓            ↓   (VPC)      (Kubernetes)   (Services)

Automation API ensures correct sequencing without manual intervention.

Self-service platforms:

Build internal tools where developers request infrastructure without learning Pulumi:

Web portals for environment provisioning
Slack bots that create/destroy resources
Custom CLIs tailored to your organization

Embedded infrastructure:

Applications that provision their own infrastructure:

SaaS platforms creating per-tenant resources
Testing frameworks spinning up test environments
CI/CD systems with dynamic infrastructure needs

Replacing fragile scripts:

If you have Bash scripts or Makefiles stitching together multiple pulumi commands, Automation API provides:

Proper error handling
Type safety
Programmatic access to outputs

When NOT to Use

Single project with standard deployment needs
When you don't need programmatic control over operations

Architecture Choices

Local Source vs Inline Source

Local Source - Pulumi program in separate files:

typescript

const stack = await automation.LocalWorkspace.createOrSelectStack({    stackName: "dev",    workDir: "./infrastructure",  // Points to existing Pulumi project});

const stack = await automation.LocalWorkspace.createOrSelectStack({    stackName: "dev",    workDir: "./infrastructure",  // Points to existing Pulumi project});

When to use:

Different teams maintain orchestrator vs Pulumi programs
Pulumi programs already exist
Want independent version control and release cycles
Platform team orchestrating application team's infrastructure

Inline Source - Pulumi program embedded in orchestrator:

typescript

import * as aws from "@pulumi/aws";
const stack = await automation.LocalWorkspace.createOrSelectStack({    stackName: "dev",    projectName: "my-project",    program: async () => {        const bucket = new aws.s3.Bucket("my-bucket");        return { bucketName: bucket.id };    },});

import * as aws from "@pulumi/aws";
const stack = await automation.LocalWorkspace.createOrSelectStack({    stackName: "dev",    projectName: "my-project",    program: async () => {        const bucket = new aws.s3.Bucket("my-bucket");        return { bucketName: bucket.id };    },});

When to use:

Single team owns everything
Tight coupling between orchestration and infrastructure is desired
Distributing as compiled binary (no source files needed)
Simpler deployment artifact

Language Independence

The Automation API program can use a different language than the Pulumi programs it orchestrates:

This enables platform teams to use their preferred language while application teams use theirs.

Common Patterns

Multi-Stack Orchestration

Deploy multiple stacks in dependency order:

typescript

import * as automation from "@pulumi/pulumi/automation";
async function deploy() {    const stacks = [        { name: "infrastructure", dir: "./infra" },        { name: "platform", dir: "./platform" },        { name: "application", dir: "./app" },    ];
    for (const stackInfo of stacks) {        console.log(`Deploying ${stackInfo.name}...`);
        const stack = await automation.LocalWorkspace.createOrSelectStack({            stackName: "prod",            workDir: stackInfo.dir,        });
        await stack.up({ onOutput: console.log });        console.log(`${stackInfo.name} deployed successfully`);    }}
async function destroy() {    // Destroy in reverse order    const stacks = [        { name: "application", dir: "./app" },        { name: "platform", dir: "./platform" },        { name: "infrastructure", dir: "./infra" },    ];
    for (const stackInfo of stacks) {        console.log(`Destroying ${stackInfo.name}...`);
        const stack = await automation.LocalWorkspace.selectStack({            stackName: "prod",            workDir: stackInfo.dir,        });
        await stack.destroy({ onOutput: console.log });    }}

import * as automation from "@pulumi/pulumi/automation";
async function deploy() {    const stacks = [        { name: "infrastructure", dir: "./infra" },        { name: "platform", dir: "./platform" },        { name: "application", dir: "./app" },    ];
    for (const stackInfo of stacks) {        console.log(`Deploying ${stackInfo.name}...`);
        const stack = await automation.LocalWorkspace.createOrSelectStack({            stackName: "prod",            workDir: stackInfo.dir,        });
        await stack.up({ onOutput: console.log });        console.log(`${stackInfo.name} deployed successfully`);    }}
async function destroy() {    // Destroy in reverse order    const stacks = [        { name: "application", dir: "./app" },        { name: "platform", dir: "./platform" },        { name: "infrastructure", dir: "./infra" },    ];
    for (const stackInfo of stacks) {        console.log(`Destroying ${stackInfo.name}...`);
        const stack = await automation.LocalWorkspace.selectStack({            stackName: "prod",            workDir: stackInfo.dir,        });
        await stack.destroy({ onOutput: console.log });    }}

Passing Configuration

Set stack configuration programmatically:

typescript

const stack = await automation.LocalWorkspace.createOrSelectStack({    stackName: "dev",    workDir: "./infrastructure",});
// Set configuration valuesawait stack.setConfig("aws:region", { value: "us-west-2" });await stack.setConfig("dbPassword", { value: "secret", secret: true });
// Then deployawait stack.up();

const stack = await automation.LocalWorkspace.createOrSelectStack({    stackName: "dev",    workDir: "./infrastructure",});
// Set configuration valuesawait stack.setConfig("aws:region", { value: "us-west-2" });await stack.setConfig("dbPassword", { value: "secret", secret: true });
// Then deployawait stack.up();

Reading Outputs

Access stack outputs after deployment:

typescript

const upResult = await stack.up();
// Get all outputsconst outputs = await stack.outputs();console.log(`VPC ID: ${outputs["vpcId"].value}`);
// Or from the up resultconsole.log(`Outputs: ${JSON.stringify(upResult.outputs)}`);

const upResult = await stack.up();
// Get all outputsconst outputs = await stack.outputs();console.log(`VPC ID: ${outputs["vpcId"].value}`);
// Or from the up resultconsole.log(`Outputs: ${JSON.stringify(upResult.outputs)}`);

Error Handling

Handle deployment failures gracefully:

typescript

try {    const result = await stack.up({ onOutput: console.log });
    if (result.summary.result === "failed") {        console.error("Deployment failed");        process.exit(1);    }} catch (error) {    console.error(`Deployment error: ${error}`);    throw error;}

try {    const result = await stack.up({ onOutput: console.log });
    if (result.summary.result === "failed") {        console.error("Deployment failed");        process.exit(1);    }} catch (error) {    console.error(`Deployment error: ${error}`);    throw error;}

Parallel Stack Operations

When stacks are independent, deploy in parallel:

typescript

const independentStacks = [    { name: "service-a", dir: "./service-a" },    { name: "service-b", dir: "./service-b" },    { name: "service-c", dir: "./service-c" },];
await Promise.all(independentStacks.map(async (stackInfo) => {    const stack = await automation.LocalWorkspace.createOrSelectStack({        stackName: "prod",        workDir: stackInfo.dir,    });    return stack.up({ onOutput: (msg) => console.log(`[${stackInfo.name}] ${msg}`) });}));

const independentStacks = [    { name: "service-a", dir: "./service-a" },    { name: "service-b", dir: "./service-b" },    { name: "service-c", dir: "./service-c" },];
await Promise.all(independentStacks.map(async (stackInfo) => {    const stack = await automation.LocalWorkspace.createOrSelectStack({        stackName: "prod",        workDir: stackInfo.dir,    });    return stack.up({ onOutput: (msg) => console.log(`[${stackInfo.name}] ${msg}`) });}));

Best Practices

Separate Configuration from Code

Externalize configuration into files or environment variables:

typescript

import * as fs from "fs";
interface DeployConfig {    stacks: Array<{ name: string; dir: string; }>;    environment: string;}
const config: DeployConfig = JSON.parse(    fs.readFileSync("./deploy-config.json", "utf-8"));
for (const stackInfo of config.stacks) {    const stack = await automation.LocalWorkspace.createOrSelectStack({        stackName: config.environment,        workDir: stackInfo.dir,    });    await stack.up();}

import * as fs from "fs";
interface DeployConfig {    stacks: Array<{ name: string; dir: string; }>;    environment: string;}
const config: DeployConfig = JSON.parse(    fs.readFileSync("./deploy-config.json", "utf-8"));
for (const stackInfo of config.stacks) {    const stack = await automation.LocalWorkspace.createOrSelectStack({        stackName: config.environment,        workDir: stackInfo.dir,    });    await stack.up();}

This enables distributing compiled binaries without exposing source code.

Stream Output for Long Operations

Use onOutput callback for real-time feedback:

typescript

await stack.up({    onOutput: (message) => {        process.stdout.write(message);        // Or send to logging system, websocket, etc.    },});

await stack.up({    onOutput: (message) => {        process.stdout.write(message);        // Or send to logging system, websocket, etc.    },});

Quick Reference

Scenario	Approach
Existing Pulumi projects	Local source with workDir
New embedded infrastructure	Inline source with program function
Different teams	Local source for independence
Compiled binary distribution	Inline source or bundled local
Multi-stack dependencies	Sequential deployment in order
Independent stacks	Parallel deployment with Promise.all

Related Skills

pulumi-best-practices: Code-level patterns for Pulumi programs

References

來源與署名

來源：pulumi/agent-skills位於pulumi/skills/pulumi-automation-api提交900eacf

授權條款：無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

Pulumi Automation Api

Pulumi Automation API

When to Use This Skill

What is Automation API

When to Use Automation API

Good Use Cases

When NOT to Use

Architecture Choices

Local Source vs Inline Source

Language Independence

Common Patterns

Multi-Stack Orchestration

Passing Configuration

Reading Outputs

Error Handling

Parallel Stack Operations

Best Practices

Separate Configuration from Code

Stream Output for Long Operations

Quick Reference

Related Skills

References

來源與署名

更多來自 pulumi/agent-skills 的技能

Pulumi Component

Pulumi Overview

Pulumi Esc

Pulumi Best Practices

Upstream Patches

Provider Upgrade

更多DevOps & Cloud技能

Playwright Devops

M5 Onboard

Yeet

Runbook

Incident Response

Deploy Checklist