Pulumi Automation API 教程 - 基础设施即代码自动化编排与部署

pulumi-automation-api by pulumi/agent-skills

353 周安装量

30 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/pulumi/agent-skills --skill pulumi-automation-api

自动化云服务开发运维

🇨🇳中文介绍

Pulumi Automation API

何时使用此技能

在以下场景中调用此技能：

跨多个 Pulumi 堆栈编排部署
在自定义应用程序中嵌入 Pulumi 操作
构建自助式基础设施平台
替换脆弱的 Bash/Makefile 编排脚本
创建用于基础设施管理的自定义 CLI
构建可配置基础设施的 Web 应用程序

什么是 Automation API

Automation API 提供了对 Pulumi 操作的程序化访问。无需从 CLI 运行 pulumi up，而是在代码中调用执行相同操作的函数。

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

// 创建或选择堆栈
const stack = await automation.LocalWorkspace.createOrSelectStack({
    stackName: "dev",
    projectName: "my-project",
    program: async () => {
        // 你的 Pulumi 程序写在这里
    },
});

// 以编程方式运行 pulumi up
const upResult = await stack.up({ onOutput: console.log });
console.log(`更新摘要：${JSON.stringify(upResult.summary)}`);

何时使用 Automation API

适用场景

多堆栈编排：

当将基础设施拆分为多个专注的项目时，Automation API 通过跨堆栈编排操作来帮助抵消增加的复杂性：

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

本地源 vs 内联源

本地源 - Pulumi 程序位于单独的文件中：

const stack = await automation.LocalWorkspace.createOrSelectStack({
    stackName: "dev",
    workDir: "./infrastructure",  // 指向现有的 Pulumi 项目
});

不同团队分别维护编排器和 Pulumi 程序
Pulumi 程序已存在
希望独立的版本控制和发布周期
平台团队编排应用团队的基础设施

内联源 - Pulumi 程序嵌入在编排器中：

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 };
    },
});

单一团队负责所有内容
希望编排和基础设施之间紧密耦合
分发为编译后的二进制文件（无需源文件）
更简单的部署工件

Automation API 程序可以使用与其编排的 Pulumi 程序不同的语言：

编排器 (Go) → 管理 → Pulumi 程序 (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(`正在部署 ${stackInfo.name}...`);

        const stack = await automation.LocalWorkspace.createOrSelectStack({
            stackName: "prod",
            workDir: stackInfo.dir,
        });

        await stack.up({ onOutput: console.log });
        console.log(`${stackInfo.name} 部署成功`);
    }
}

async function destroy() {
    // 按相反顺序销毁
    const stacks = [
        { name: "application", dir: "./app" },
        { name: "platform", dir: "./platform" },
        { name: "infrastructure", dir: "./infra" },
    ];

    for (const stackInfo of stacks) {
        console.log(`正在销毁 ${stackInfo.name}...`);

        const stack = await automation.LocalWorkspace.selectStack({
            stackName: "prod",
            workDir: stackInfo.dir,
        });

        await stack.destroy({ onOutput: console.log });
    }
}

以编程方式设置堆栈配置：

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

// 设置配置值
await stack.setConfig("aws:region", { value: "us-west-2" });
await stack.setConfig("dbPassword", { value: "secret", secret: true });

// 然后部署
await stack.up();

部署后访问堆栈输出：

const upResult = await stack.up();

// 获取所有输出
const outputs = await stack.outputs();
console.log(`VPC ID：${outputs["vpcId"].value}`);

// 或从 up 结果中获取
console.log(`输出：${JSON.stringify(upResult.outputs)}`);

优雅地处理部署失败：

try {
    const result = await stack.up({ onOutput: console.log });

    if (result.summary.result === "failed") {
        console.error("部署失败");
        process.exit(1);
    }
} catch (error) {
    console.error(`部署错误：${error}`);
    throw error;
}

当堆栈独立时，并行部署：

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}`) });
}));

将配置与代码分离

将配置外部化到文件或环境变量中：

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();
}

这样可以在不暴露源代码的情况下分发编译后的二进制文件。

为长时间操作流式传输输出

使用 onOutput 回调进行实时反馈：

await stack.up({
    onOutput: (message) => {
        process.stdout.write(message);
        // 或发送到日志系统、websocket 等
    },
});

场景	方法
现有 Pulumi 项目	使用 workDir 的本地源
新的嵌入式基础设施	使用 program 函数的内联源
不同团队	本地源以实现独立性
编译后的二进制文件分发	内联源或捆绑的本地源
多堆栈依赖	按顺序依次部署
独立堆栈	使用 Promise.all 并行部署

pulumi-best-practices : Pulumi 程序的代码级模式

🇺🇸English

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.

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

// Create or select a stack
const stack = await automation.LocalWorkspace.createOrSelectStack({
    stackName: "dev",
    projectName: "my-project",
    program: async () => {
        // Your Pulumi program here
    },
});

// Run pulumi up programmatically
const 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:

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:

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:

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:

Orchestrator (Go) → manages → Pulumi Program (TypeScript)

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:

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:

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

// Set configuration values
await stack.setConfig("aws:region", { value: "us-west-2" });
await stack.setConfig("dbPassword", { value: "secret", secret: true });

// Then deploy
await stack.up();

Reading Outputs

Access stack outputs after deployment:

const upResult = await stack.up();

// Get all outputs
const outputs = await stack.outputs();
console.log(`VPC ID: ${outputs["vpcId"].value}`);

// Or from the up result
console.log(`Outputs: ${JSON.stringify(upResult.outputs)}`);

Error Handling

Handle deployment failures gracefully:

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:

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:

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:

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

Weekly Installs

353

Repository

pulumi/agent-skills

GitHub Stars

First Seen

Jan 28, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode308

codex304

github-copilot303

gemini-cli294

amp288

kimi-cli286

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

100,500 周安装

Pulumi Automation API 教程 - 基础设施即代码自动化编排与部署

🇨🇳中文介绍

Pulumi Automation API

何时使用此技能

什么是 Automation API

何时使用 Automation API

适用场景

相关 Skills

不适用场景

架构选择

本地源 vs 内联源

语言独立性

常见模式

多堆栈编排

传递配置

读取输出

错误处理

并行堆栈操作

最佳实践

将配置与代码分离

为长时间操作流式传输输出

快速参考

相关技能

参考

🇺🇸English

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

最新 Skills