4. Pulumi CLI 漂移检测：核心命令与输出解读
漂移检测是堆栈复核流程中的关键环节。Pulumi CLI 提供了两个核心命令用于检测和修复漂移：pulumi refresh 和 pulumi preview --diff。前者用于将云资源的最新状态同步到状态文件，后者用于对比期望状态与当前状态，并高亮差异。本节将深入讲解这两个命令的用法、输出解读以及最佳实践。
4.1 使用 pulumi refresh 命令同步状态
pulumi refresh 命令会查询云服务提供商的 API，获取当前部署资源的最新属性，并将其更新到 Pulumi 的状态文件中。它本身不会修改云资源，只更新 Pulumi 对资源状态的认知。
命令格式与常用参数
# 基本用法
pulumi refresh
# 跳过交互式确认，直接执行
pulumi refresh --yes
# 指定堆栈
pulumi refresh --stack production
# 仅刷新特定资源
pulumi refresh --target urn:pulumi:prod::myapp::aws:s3/bucket:Bucket::my-bucket| 参数 | 说明 | 典型场景 |
|---|---|---|
--yes |
跳过确认提示，直接执行 | CI/CD 流水线中自动执行 |
--stack |
指定目标堆栈名称 | 多环境管理时切换上下文 |
--target |
指定要刷新的资源 URN | 仅刷新已知发生漂移的特定资源 |
--skip-preview |
跳过预览，直接刷新 | 信任刷新操作且需要快速执行 |
最佳实践：在复核流程中，建议先执行
pulumi refresh 让状态文件与真实世界对齐，然后再执行 pulumi preview --diff 来发现真正的配置漂移。这样可以避免因状态文件过时而产生的误报。
4.2 使用 pulumi preview --diff 检测漂移
pulumi preview 命令会展示从当前状态到期望状态需要执行的操作。加上 --diff 标志后，它会以类似 diff 命令的格式，逐字段显示资源属性的变化，是发现漂移最直观的工具。
命令格式与常用参数
# 显示详细的属性级差异
pulumi preview --diff
# 仅显示将发生变化的资源
pulumi preview --diff --expect-no-changes
# 指定堆栈
pulumi preview --diff --stack staging| 参数 | 说明 | 漂移检测中的用途 |
|---|---|---|
--diff |
显示属性级别的详细差异 | 精确识别哪些字段发生了漂移 |
--expect-no-changes |
如果检测到任何变化，则退出码非零 | CI/CD 中断言堆栈无漂移 |
--target |
仅预览特定资源的变化 | 聚焦于关键资源的漂移情况 |
注意：
pulumi preview --diff 的输出基于当前状态文件。如果状态文件本身已过时，应先执行 pulumi refresh，否则预览结果可能不准确。在复核流程中，标准的操作顺序是：refresh → preview --diff。
4.3 解读 CLI 输出中的漂移信息
理解 CLI 的输出是漂移复核的核心能力。下面通过一个典型场景来解读输出信息。
典型输出示例
Previewing update (dev)
Type Name Plan Info
pulumi:pulumi:Stack myapp-dev
+ └─ aws:s3/bucket:Bucket my-bucket create
└─ aws:ec2/securityGroup:SecurityGroup web-sg update [diff: +ingress]
Resources:
+ 1 to create
~ 1 to update
2 unchanged
Detailed Diff for aws:ec2/securityGroup:SecurityGroup "web-sg":
~ ingress: [
~ { ~ protocol: "tcp" -> "udp"
fromPort: 80
toPort: 80
cidrBlocks: ["0.0.0.0/0"]
}
]输出字段解读
| 字段/符号 | 含义 | 漂移类型 |
|---|---|---|
+ |
资源将被创建 | 期望状态有，实际状态无（资源缺失） |
~ |
资源将被更新 | 属性值发生漂移 |
- |
资源将被删除 | 实际状态有，期望状态无（资源多余） |
[diff: ...] |
显示发生变化的属性路径 | 精确指示漂移发生的字段 |
~ protocol: "tcp" -> "udp" |
属性从旧值变为新值 | 属性级漂移的具体内容 |
漂移信息分类
- 新增漂移（+）：云资源被手动删除，或基础设施即代码中新增了资源但尚未创建。
- 修改漂移（~）：资源属性被手动修改（如通过云控制台、CLI 或第三方工具），与代码定义不一致。
- 删除漂移（-）：云资源被手动创建，或代码中删除了资源定义但尚未执行销毁。
实战要点：在复核流程中，重点关注
[diff: ...] 标记。它直接告诉你哪些属性发生了漂移。例如 [diff: +ingress,-tags,~size] 表示入站规则新增、标签被删除、大小被修改。这些信息是后续制定修复策略的依据。
4.4 漂移检测命令对比
| 命令 | 核心作用 | 是否修改云资源 | 是否修改状态文件 | 漂移检测中的角色 |
|---|---|---|---|---|
pulumi refresh |
将云资源实际状态同步到状态文件 | 否 | 是 | 校准基线，消除状态文件漂移 |
pulumi preview --diff |
对比期望状态与当前状态，显示差异 | 否 | 否 | 发现配置漂移，定位具体差异 |
pulumi up |
执行变更，使实际状态对齐期望状态 | 是 | 是 | 修复漂移（非检测阶段） |
效率技巧：在 CI/CD 流水线中，可以使用
pulumi preview --diff --expect-no-changes 作为漂移检测的断言。如果命令返回非零退出码，说明存在漂移，流水线应告警并触发复核流程。这样可以实现漂移检测的自动化。