pulumi-overview

Pulumi

Pulumi 是用于创建和管理云基础设施的工具：虚拟机、存储、Kubernetes 集群、数据库，以及任何云服务提供商提供的其他资源。你可以编写代码或运行 CLI 命令；Pulumi 会预览将要发生的更改，然后应用这些更改。本技能介绍了使用 Pulumi 的三个层级，从单个 CLI 命令到包含策略和定期漂移检测的项目。请从适合当前任务的最低层级开始。

三个层级

第 1 级是 pulumi do，这是一个可直接对任何云服务提供商执行 CRUD 操作的 CLI，无需项目文件或编程语言。当工作涉及多个相关资源、循环或条件、可重用抽象，或因环境而异的变体时，可使用第 2 级：以 Python、TypeScript、Go、C# 或 Java 编写的 Pulumi 项目。第 3 级是在项目基础上添加 Pulumi Cloud，用于 ESC 凭据和配置、策略、托管执行、漂移检测、计划任务和审计。

级别	使用方式	适用场景
1	pulumi do	单个资源或多云服务商引导配置
2	Pulumi 项目（Python、TS、Go、C#、Java）	多个资源、抽象、环境
3	ESC、策略、部署、漂移、计划任务	治理、机密、定期运行和托管运行

如果目录中没有现成的 Pulumi 项目，用户要求创建单个存储桶时，这属于第 1 级任务；不要为此搭建新项目。若用户要求配置包含子网和 Kubernetes 集群的 VPC，则应从一开始就使用第 2 级。若用户要求对现有堆栈进行夜间漂移检测，则属于第 3 级。

将其他工具（Terraform、CloudFormation、CDK、ARM 或 Bicep）的现有基础设施代码转换过来属于单独的路径：应直接转到文末表格中列出的迁移技能，不受层级模型限制。

要选对层级，必须了解目录中已有的内容。如果可以检查文件系统，请这样做。如果无法检查（例如受限的 Agent 上下文），请在运行任何 Pulumi 命令之前询问用户目录中是否已有 Pulumi 项目。不要通过运行 Pulumi 命令来确认：原本需要登录的命令会静默创建新的 Agent 账户，而用户可能已经拥有自己的账户。

---

第 1 级：使用 pulumi do 直接操作资源

使用 pulumi do 对任何云服务提供商执行一次性资源操作。例如：创建 Cloudflare DNS 记录、创建用于备份的 S3 存储桶、创建用于上传图片的 GCP 存储桶、启动 Azure 虚拟机、配置 Datadog 监控器，或在 Cloudflare DNS 中为 Vercel 部署注册域名。整个过程不涉及项目文件、目录结构或编程语言。

pulumi do 是无状态的。每条命令运行一次，直接操作云服务提供商：create 会配置资源并输出其云端标识符，而 read、patch 和 delete 会对由该标识符指定的资源执行操作。所有内容都不会写入 Pulumi 状态文件，因此不存在资源图，也无法通过 ${...} 在命令之间串联数据。要连接两个资源，请从一条命令中获取输出，并将其作为字面值传递给下一条命令。

如果目录中已有 Pulumi 项目（Pulumi.yaml），请勿使用 pulumi do 修改该项目管理的资源。所有更改都应通过程序进行。

首次调用和注册

标准调用方式是 npx pulumi <command>。只要安装了 Node.js，就可以在任何机器上使用，无需事先设置 Pulumi。如果 pulumi 位于 PATH 中，npx 补充程序会调用它；否则，命令会从 npm 注册表运行。若要在任何可能触发注册的命令之前确认 CLI 可用，请运行 npx pulumi version；此命令不会访问 Pulumi Cloud。资源操作（create、read、patch、delete、list）需要 CLI v3.243.0 或更高版本，该版本为 pulumi do 添加了资源支持。npx pulumi 会获取当前版本，但 PATH 中已有的 pulumi 可能较旧，因此请确认版本足够新。

pulumi do 不会写入 Pulumi 状态，但它会通过 Pulumi 注册表解析提供程序包，而这可能会连接到 Pulumi Cloud。在没有已保存凭据的 Agent 环境中，这意味着首次运行 pulumi do 时可能会静默创建一个临时 Agent 账户，并打印认领横幅。

CLI 会向 stderr 打印一行，提示新账户已创建，并附上认领 URL。请立即向用户提供该认领 URL，并在最终回复中再次提供，因为这是用户取得账户所有权的唯一方式；如果会话结束时用户仍未拿到该 URL，资源就会滞留在云端。访问令牌会在 3 天后过期，认领 URL 在 30 天内有效；两者均由 Pulumi Cloud 设置，因此请提供横幅中报告的有效期。

如果同一会话中多次出现账户创建横幅，凭据可能尚未缓存。Agent 凭据会写入 /tmp/.pulumi/credentials.json，认领元数据会写入 /tmp/.pulumi/agent-claim.json，但认领 URL 本身只会显示在横幅中，不会存储在这些文件里。请从每个横幅中捕获认领 URL，并在继续操作前向用户提供最新的 URL。

如果身份验证失败，请让用户运行 pulumi login。切勿改用 pulumi login --local 或设置 PULUMI_CONFIG_PASSPHRASE；这两种做法都会在用户不知情的情况下更改其设置。

提供程序凭据与 Pulumi Cloud 凭据相互独立。pulumi do 会从提供程序原生 CLI 使用的相同环境变量中读取凭据（AWS_PROFILE、CLOUDFLARE_API_TOKEN、GOOGLE_APPLICATION_CREDENTIALS）。如果未设置这些变量，请先询问用户，再调用会访问云端的命令。如果命令因提供程序授权错误而失败，请查明该提供程序所需的凭据或配置，并让用户提供，而不要猜测原因。项目创建后，ESC（第 3 级）是长期保存这些凭据的合适位置。

命令格式

下面是两条调用命令：先创建一个 S3 存储桶，再通过 create 打印的云端 ID 读取该存储桶。

npx pulumi do aws:s3:Bucket create --yes --bucket my-data
npx pulumi do aws:s3:Bucket read my-data

格式如下：

pulumi do <pkg:mod:type> create [flags]
pulumi do <pkg:mod:type> read|patch|delete <id> [flags]
pulumi do <pkg:mod:type> list [flags]

• <pkg> 是提供程序包（aws、azure-native、gcp、cloudflare、kubernetes 等）。
• <mod> 是包内的模块（compute、storage、dns）；当模块为 index 时可以省略。例如，cloudflare:index/record:Record 的调用形式为 cloudflare:Record。
• <type> 是资源类型（VirtualMachine、Bucket、Record）。
• <id> 是现有资源在云提供程序中的标识符，也就是 create 打印的 id 值。create 和 list 不接受位置参数；read、patch 和 delete 则各自恰好接受一个 <id>。
• [flags] 用于设置资源属性；也可以通过 --input-file <file> 传入请求体文件。标志和文件的组合方式，以及哪些值必须通过文件传入，请参阅下文的“属性输入”。

无需指定 Pulumi 逻辑名称。CLI 会根据资源类型生成内部名称，现有资源则通过其云端 ID 进行寻址。

动词

• create 会创建资源，并以 JSON 格式打印其属性，其中包括云端 id。请保存该 id，以便稍后读取、修补或删除资源。在非交互式环境中传入 --yes；read 和 list 从不需要它。
• read <id> 会从提供商获取资源的当前状态，并以 JSON 格式打印。它不会写入任何内容。
• patch <id> 会读取资源当前的输入，将你通过标志或 --input-file 传入的顶层属性覆盖到这些输入上，并原地更新资源。覆盖是浅层的：未提及的属性会保持原样。patch 只会更新资源，不能替换资源，因此，需要替换资源才能完成的更改会失败，而不会重新创建资源。该命令会要求你输入资源 ID 进行确认；在非交互式环境中传入 --yes 可跳过此提示。
• delete <id> 会从云端删除资源。此操作不可逆。执行前，请针对特定资源获取用户的明确确认；只有在获得确认后才使用 --yes，不要将其设为非交互式运行的默认选项。

pulumi do 还支持两种非 CRUD 操作。pulumi do <pkg:mod:type> list [flags] 会枚举某种资源类型的现有实例，但仅适用于实现了列表功能的类型。原生提供商广泛支持此操作。基于 Terraform 桥接的提供商（aws、azure、gcp）也支持此操作，但覆盖范围因资源类型而异，因此不支持此操作的类型会拒绝该动词。pulumi do <pkg:mod:function> [flags] 会调用提供商在资源之外提供的无状态函数。

属性输入

属性可通过每个属性对应的标志、主体文件或两者提供；标志会覆盖主体文件中的值。标志只能设置顶层标量属性，因此嵌套或结构化值（tags、嵌套块）必须来自主体文件。主体文件默认为 PCL，采用扁平的 name = value 属性格式；若要改用 YAML，请传入 --input yaml（这需要 YAML 转换器插件）。

cat > bucket.pcl <<'EOF'
bucket = "my-data"
tags = {
  Environment = "dev"
}
EOF
npx pulumi do aws:s3:Bucket create --yes --input-file bucket.pcl

首次为本次会话中新接触的资源编写属性之前，请运行 npx pulumi package info <pkg> --module <mod> --resource <Type>，查看该资源的输入和输出及其说明。只有在需要完整的机器可读架构（包括 info 不会展开的嵌套类型定义）时，才使用 npx pulumi package get-schema <pkg>；对于大型提供商，该命令会生成数十 MB 的内容，因此不要一次性读取全部内容。属性名采用 camelCase 格式（标志使用 kebab-case 格式）。如需查找属性名，可运行不带模块参数的 npx pulumi package info <pkg> 来列出其模块和资源，或浏览目录：https://www.pulumi.com/registry/。

连接资源

pulumi do 不保留状态，也没有资源图，因此命令之间不支持 ${...} 引用语法。要将一个资源的输出传给另一个资源，请从第一个命令的 JSON 输出中读取字段，并将其作为字面量标志传给下一个命令。

# create prints JSON containing "id": "vpc-0abc123"
npx pulumi do aws:ec2:Vpc create --yes --cidr-block 10.0.0.0/16

# pass that id to the subnet
npx pulumi do aws:ec2:Subnet create --yes --vpc-id vpc-0abc123 --cidr-block 10.0.1.0/24

同样的方法也可用于连接不同提供商的资源。这里，random 提供商的一个值会作为 AWS 资源名称，这是一种生成全局唯一名称的常见方式。

# RandomPet prints JSON containing "id": "artistic-bull"
npx pulumi do random:RandomPet create --yes

# use it in the bucket name
npx pulumi do aws:s3:Bucket create --yes --bucket assets-artistic-bull

如果命令需要链式操作无法生成的值，例如现有资源 ID 或 API 区域 ID，请从提供商函数、提供商支持的 list 操作或用户处获取。不要臆造。

输出

默认情况下，create、read 和 patch 都会向 stdout 写入一个受影响资源的 JSON 对象。每次调用后都要检查退出代码。

{
  "id":     "my-data",
  "bucket": "my-data",
  "arn":    "arn:aws:s3:::my-data"
}

资源的属性位于顶层，与保存云端标识符的 id 字段并列。没有嵌套的 outputs 对象，也没有 urn，并且不会回显你传入的类型令牌。list 则会写入一个由 {id, name} 条目组成的 JSON 数组；函数会写入其声明的结果结构。

升级到 Level 2

当一次性命令不再够用时，升级到 Level 2。由于 pulumi do 不会留下 Pulumi 状态，它创建的资源就是普通的云资源，因此你可以通过 pulumi import 将它们纳入项目。在 Pulumi 项目中，运行 pulumi import，为每个资源指定完整的类型令牌、逻辑名称，以及 create 返回的云端 id。导入会将资源记录到堆栈状态中，并且默认会生成相应的程序代码。

# the import type token is the full pkg:mod/type:Type form, not pulumi do's short aws:s3:Bucket
npx pulumi import aws:s3/bucket:Bucket assets my-data

将生成的代码移入你的程序，然后在程序中管理该资源，而不是使用 pulumi do。若要一次纳入多个资源，请通过批量 --file 传入。

---

Level 2：完整的基础设施即代码

Level 2 是一个 Pulumi 项目：使用 Python、TypeScript、Go、C# 或 Java 编写代码，描述一组相关资源及其依赖关系。当任务涉及多个相关资源、循环或条件、可复用抽象，或特定于环境的变体时，可从这里开始。如果 Level 1 的临时操作已经超出少数几次 CLI 调用所能承载的范围，这也是合适的层级。如果用户已有代码库，请使用其中的语言；否则默认使用 TypeScript。

编写任何非简单程序之前，请使用技能 pulumi-best-practices，其中涵盖 Output<T> 和 apply() 的用法、直接将输出作为输入传递、组件结构和父子关系、密钥管理卫生，以及使用 aliases 安全重构。

初始化

使用模板是启动项目最快的方式；如果愿意，也可以手动搭建：

npx pulumi new aws-typescript
npx pulumi new gcp-go

模板会设置工作目录、Pulumi.yaml、初始堆栈、该语言的包清单文件，以及一个起始程序。使用 npx pulumi template list 浏览完整目录，或使用 npx pulumi template list --name <filter> 按名称筛选。

核心生命周期

生命周期命令在各种语言中用法相同：

npx pulumi preview      # show what would change
npx pulumi up           # apply
npx pulumi refresh      # reconcile state with cloud reality

始终先运行 preview，再运行 up；它会显示将发生的更改，而且不会产生费用。

pulumi destroy 会删除堆栈中的所有资源。Pulumi 文档称其为“通常不可逆”；未经用户明确确认堆栈名称，切勿调用。

堆栈和配置

堆栈是项目的隔离实例。常见模式是每个环境使用一个堆栈，命名为 dev、staging 和 prod。

npx pulumi stack init dev
npx pulumi stack select prod

npx pulumi config set aws:region us-west-2
npx pulumi config set --secret dbPassword "..."

在程序内部使用 SDK 的 Config 对象读取配置值；具体操作名称因语言而异，请参阅各语言示例：https://www.pulumi.com/docs/iac/concepts/config/#code。使用技能 pulumi-best-practices 了解 Output<T> / apply() 的用法，以及更全面的密钥管理卫生实践。

堆栈只会处理其状态中跟踪的资源，因此从程序中移除某个资源会导致 pulumi up 将其从云端删除。对于任何无法承受丢失的资源，请设置 protect: true。

完整的 IaC 参考文档请见 https://www.pulumi.com/docs/iac/。

---

Level 3：治理和运维

Level 3 使用 Pulumi Cloud 管理的不只是状态。ESC 将项目涉及的每个提供程序的凭据集中管理，并将其注入运行环境和 shell。策略实施、托管执行、漂移检测、计划操作和审计也都属于这一层。

ESC：环境、密钥、配置

ESC 环境会将来自云端密钥管理器、通过 OIDC 签发的凭据以及其他 ESC 环境的密钥和配置组合为一个已解析的配置包，供程序和堆栈使用。

npx pulumi env init my_org/aws/prod
npx pulumi env set my_org/aws/prod aws.region us-west-2
npx pulumi env open my_org/aws/prod
npx pulumi env run my_org/aws/prod -- aws s3 ls

如果提供程序支持，应通过 OIDC 签发云凭据，而不是在环境 YAML 中使用静态密钥。 OIDC 信任策略、IdP 注册和轮换模式请参阅 pulumi-esc；请使用技能 pulumi-esc，不要手动编写 ESC YAML。

env open 会解析并打印实时凭据，因此请避免将其输出保存到日志或记录文本中。优先使用 env run -- <command>，它会将凭据注入子进程，而不是打印出来。

策略

Pulumi Policies 会在预览和更新时针对资源图运行策略包。策略可以拒绝部署、要求审批，或为资源添加调查结果注释；策略会在任何云 API 调用之前执行。

npx pulumi policy new aws-typescript          # scaffold a pack from a policy template
npx pulumi policy publish my_org              # the pack name comes from PulumiPolicy.yaml
npx pulumi policy enable my_org/<pack-name> latest --policy-group production

策略使用 TypeScript 或 Python 编写，也就是你用于编写程序的语言。

部署

Pulumi Deployments 会在 Pulumi 管理的基础设施中运行 pulumi up、preview 和 destroy，而不是在本地机器上运行。使用它进行 CI，无需维护自己的运行器；对于需要在服务端运行的任何操作，也可以使用它。

npx pulumi deployment run update --stack my_org/proj/prod

目标堆栈必须已经存在；错误的 --stack 值可能会提示你创建新堆栈，而不是直接失败。

漂移检测和计划操作

漂移检测会将堆栈状态与云端状态进行比较，并报告所有不一致之处。若要临时在本地检查，可在仅预览模式下运行刷新。Pulumi Cloud 会按 cron 计划操作（时间为 UTC），其中包括专门用于漂移检测的类型。

# Ad-hoc local drift check
npx pulumi refresh --preview-only

# Scheduled drift detection (detection only)
npx pulumi stack schedule new --kind drift --cron "0 0 * * *"

# Scheduled secret rotation for an ESC environment
npx pulumi env schedule new my_org/aws/prod --cron "0 0 1 * *"

计划任务会在会话结束后继续运行，因此创建计划任务前，请与用户确认操作、频率和堆栈。有两种类型会在没有人工介入的情况下执行操作：--kind drift --auto-remediate 会针对检测到的漂移运行 pulumi up，而 --kind ttl 会在指定时间销毁堆栈。除非用户要求修复，否则默认仅进行检测。

延伸阅读

• ESC：https://www.pulumi.com/docs/esc/
• Pulumi Policies：https://www.pulumi.com/docs/insights/policy/
• Deployments：https://www.pulumi.com/docs/pulumi-cloud/deployments/
• 漂移检测：https://www.pulumi.com/docs/pulumi-cloud/deployments/drift/

---

参考资料

如果不确定 CLI 标志、命令格式或资源属性，请查阅文档，不要猜测。npx pulumi <command> --help 会列出 CLI 本身的所有标志和子命令。完整参考资料、Provider 目录和概念文档见 https://www.pulumi.com/docs。

---

转交给专用技能

如果工作涉及其他技能深入涵盖的领域，请转交给该技能，而不要重新编写其内容。

技能	在以下情况下加载
pulumi-best-practices	编写任何非平凡的 Level 2 程序
pulumi-component	封装或使用 ComponentResource 抽象
pulumi-esc	定义 ESC 环境、OIDC 信任策略或轮换
pulumi-automation-api	将 Pulumi 嵌入其他程序（IDP、自定义 CI）
provider-upgrade	在堆栈中升级 Provider 包版本，且不产生非预期更改
package-usage	审查组织中哪些堆栈使用某个包，以及使用的版本
pulumi-context-api	有关组织基础设施图中关系和影响分析的问题
pulumi-terraform-to-pulumi、pulumi-cdk-to-pulumi、cloudformation-to-pulumi、pulumi-arm-to-pulumi	从这些工具迁移

Agent 只能看到用户已安装的技能，因此引用的技能可能并不存在。pulumi-best-practices、pulumi-component、pulumi-esc、pulumi-automation-api、provider-upgrade、package-usage 和 pulumi-context-api 与此技能一同随 pulumi 插件提供，因此只要有此技能，这些技能就可用。迁移技能通过 pulumi-migration 插件单独安装，因此可能缺失。引用的技能可用时，请加载该技能。如果不可用，不要因此停滞，也不要将其视为错误：请继续遵循此技能中的指导和 https://www.pulumi.com/docs 上的文档，并告知用户哪个技能或插件深入涵盖相关工作。