pulumi-esc

Name: pulumi-esc
Author: pulumi

github.com/pulumi云与 DevOps781.4k 次安装3 周前更新

代码仓库

关于 pulumi-esc

面向管理云基础设施和应用配置的团队，介绍 Pulumi ESC 环境、密钥与配置的管理方式。涵盖环境组合、动态凭证、外部密钥存储、版本审计和访问控制。

主要功能

01集中管理环境与密钥
02组合分层配置
03通过 OIDC 生成动态凭证
04接入外部密钥存储
05版本审计与访问控制

适用场景

01集中维护团队环境配置
02为云操作配置动态凭证
03从其他 Pulumi Stack 读取输出

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pulumi/agent-skills --skill pulumi-esc

安装后在 Claude Code 中输入/pulumi-esc确认已加载。

附带文件agents/openai.yamluse_cases.yaml

详细介绍

Pulumi ESC（环境、密钥与配置）

Pulumi ESC 是一项集中式服务，用于管理云基础设施和应用中的环境、密钥与配置。

什么是 ESC？

ESC 支持团队：

集中管理密钥和配置，并将其存储在一个安全的位置
通过导入和叠加配置来组合环境
通过 OIDC 为 AWS、Azure、GCP 生成动态凭据
集成外部密钥存储（AWS Secrets Manager、Azure Key Vault、Vault、1Password）
对所有配置更改进行版本管理和审计
通过精细化 RBAC 控制访问权限

必备 CLI 命令

# Create a new environment
pulumi env init <org>/<project-name>/<environment-name>

# Edit environment (opens in editor)
pulumi env edit <org>/<project-name>/<environment-name>

# Set values
pulumi env set <org>/<project-name>/<environment-name> <key> <value>
pulumi env set <org>/<project-name>/<environment-name> <key> <value> --secret

# View definition (secrets hidden)
pulumi env get <org>/<project-name>/<environment-name>

# Open and resolve (reveals secrets)
pulumi env open <org>/<project-name>/<environment-name>

# Run command with environment
pulumi env run <org>/<project-name>/<environment-name> -- <command>

# Link to Pulumi stack
pulumi config env add <project-name>/<environment-name>

核心概念

命令区别

pulumi env get：显示静态定义，密钥会显示为 [secret]
pulumi env open：解析并显示所有值，包括密钥和动态凭据
pulumi env run：加载环境变量后执行命令
pulumi config env add：仅接受 / 部分

环境结构

环境是 YAML 文档，包含以下保留的顶层键：

imports：导入并组合其他环境
values：定义配置和密钥

values 下的保留子键：

environmentVariables：将值映射到 shell 环境变量
pulumiConfig：配置 Pulumi 堆栈设置
files：使用环境数据生成文件

基本示例

imports:
  - common/base-config

values:
  environment: production
  region: us-west-2

  dbPassword:
    fn::secret: super-secure-password

  environmentVariables:
    AWS_REGION: ${region}
    DB_PASSWORD: ${dbPassword}

  pulumiConfig:
    aws:region: ${region}
    app:dbPassword: ${dbPassword}

读取另一个堆栈的输出

使用 fn::open::pulumi-stacks 提供程序来使用另一个堆栈的输出。下面的 stacks 和 network 键是你自行选择的任意名称。函数解析后，会用指定堆栈的输出替换 stacks.network，因此，输出名称（vpcId、subnetIds）不会出现在静态 YAML 中，而是来自生产者堆栈导出的内容。以下两点很容易弄错：

堆栈通过单个带项目限定的 stack: <project>/<stackName> 字段命名，而不是使用单独的 projectName/stackName 字段。
输出直接解析到堆栈名称之下，没有 .outputs. 这一层（使用 ${stacks.network.vpcId}，而不是 ${stacks.network.outputs.vpcId}）。

示例 — 将堆栈名称和输出名称替换为你自己的名称：

values:
  stacks:
    fn::open::pulumi-stacks:
      stacks:
        network:                 # arbitrary local name for the referenced stack
          stack: my-project/dev  # producer stack to read outputs from
  pulumiConfig:
    # vpcId / subnetIds are whatever the producer stack exports; after the function
    # resolves they are available directly under `stacks.network` (no `.outputs.`).
    vpcId: ${stacks.network.vpcId}
    subnetIds: ${stacks.network.subnetIds}

完整架构：https://www.pulumi.com/docs/esc/providers/pulumi-stacks/

在 Pulumi Cloud 控制台中查看环境

环境的控制台 URL 为 https://app.pulumi.com/<org>/esc/<project>/<environment>。路由段是 esc，不是 environments。

与用户协作

针对简单问题

如果用户提出“如何创建环境？”或“get 和 open 有什么区别？”之类的基本问题，请直接使用以上信息作答。

详细文档

当用户需要更多信息时，请使用网页抓取工具获取 Pulumi ESC 官方文档中的内容：

完整的 YAML 语法和函数 → https://www.pulumi.com/docs/esc/environments/syntax/
Provider 集成（AWS、Azure、GCP、Vault、1Password）：
- AWS：https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/
- Azure：https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/azure-login/
- GCP：https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/gcp-login/
- 短期凭证（OIDC）Provider：https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/
- 动态密钥 Provider：https://www.pulumi.com/docs/esc/integrations/dynamic-secrets/
- Pulumi 堆栈输出（fn::open::pulumi-stacks）：https://www.pulumi.com/docs/esc/providers/pulumi-stacks/
- 所有 Provider（索引）：https://www.pulumi.com/docs/esc/providers/
入门指南 → https://www.pulumi.com/docs/esc/get-started/
CLI 参考 → https://www.pulumi.com/docs/esc/cli/commands/
- 优先使用 pulumi env 子命令，而不是 esc CLI。

使用网页抓取工具，并提供具体提示词，从这些文档中提取相关信息。

复杂任务

帮助用户时：

了解目标：他们是在设置新环境、从堆栈配置迁移，还是在排查问题？
检查现有设置：使用 pulumi env 命令列出环境或读取定义
获取相关文档：使用网页抓取工具，从官方文档中获取具体示例或语法
提供分步指导：使用具体命令逐步说明操作流程
验证：帮助他们使用 pulumi env get 或 pulumi preview 进行测试 a. 仅当需要完整的解析后值时才使用 pulumi env open，但请谨慎使用，因为这会暴露密钥。

示例：设置 AWS OIDC

User: "How do I set up AWS OIDC credentials in ESC?"

1. Use the web-fetch tool to get AWS OIDC documentation from "https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/"
2. Provide the user with the configuration
3. Ask the user if they have a pre-defined role or need one created for them
4. Set up as much of the environment as possible, then guide them through any steps that you can't do for them
5. Help them test with `pulumi env get` or `pulumi env open` if necessary

常见工作流

创建环境

pulumi env init my-org/my-project/dev-config
# Edit environment (accepts new definition from a file, better for agents, more difficult for users)
pulumi env edit --file /tmp/example.yml my-org/my-project/dev-config

链接到堆栈

pulumi config env add my-project/dev-config
pulumi config  # Verify environment values are accessible

API 访问（少见）

始终优先使用 CLI 命令。 只有在绝对必要时（例如批量操作、自动化）才使用 API。

可用的 API 端点包括：

GET /api/esc/environments/{orgName} - 列出环境
GET /api/esc/environments/{orgName}/{projectName}/{envName} - 读取环境定义
GET /api/esc/providers?orgName={orgName} - 列出可用的 Provider

需要时，使用 pulumi api CLI 子命令发送请求，例如 pulumi api /api/esc/providers -F orgName={orgName}。

最佳实践

敏感值始终使用 fn::secret
优先使用 OIDC，而不是静态密钥
使用描述性名称，例如 <org>/my-app/production-aws，而不是 <org>/app/prod
按层组织环境：基础 → 云 Provider → 堆栈专用
将环境链接到堆栈后，验证 pulumi config 是否显示预期值
对于需要环境变量的命令，优先使用 pulumi env run
仅在绝对必要时使用 pulumi env open，因为这会暴露密钥
使用现有环境前，先核实其账号和角色，并取得用户确认；绝不能仅凭名称选择环境。未经用户明确确认，绝不要将环境链接到堆栈（pulumi config env add），也绝不要传入 --yes。

处理凭证错误和现有环境

凭据错误

先按错误消息中的修复方法处理。登录过期或缺失时，通常只需让用户重新进行身份验证，而且大多数提供商都会指出修复方法或相应命令：

AWS SSO：Failed to refresh cached SSO credentials. Please refresh SSO login. → aws sso login
AWS 临时凭据：ExpiredToken: The security token included in the request is expired → 刷新会话或密钥
Azure：重新运行 az login
GCP：重新运行 gcloud auth application-default login
Pulumi Cloud（401 / 未授权）：pulumi login

告知用户如何修复，并让他们重试。如果错误没有指出修复方法（例如单独出现 Unable to locate credentials，或者访问被拒绝，但原因可能是账户或配置文件不正确，而非登录过期），不要猜测；应查明项目的身份验证方式（提供商配置、当前活动的配置文件，以及任何已关联的 ESC 环境），然后处理。

更改项目获取凭据的位置（添加或切换 ESC 环境、编辑提供商配置）是一项有意为之的更改，不应作为修复会话过期的惯常做法。只有在用户提出要求时才这样做，并遵循以下规则。

绝不能仅凭名称选择现有环境

不要因为某个环境的名称看起来相关（*-aws-oidc、*-creds、*-workshop 等）就选择它。名称相符并不意味着该环境正确，也不意味着它属于当前用户的工作。

在建议使用任何现有环境之前：

使用 pulumi env get <org>/<project>/<env> 检查该环境。
确认它进行身份验证的目标与用户资源的实际所在位置一致。OIDC roleArn 指定了一个具体的 AWS 账户；如果它指向不同的账户（共享的 workshop、讲师角色或其他团队），那这个环境就是错误的，使用它会针对错误的账户执行操作，或导致操作失败。
向用户展示候选环境，并在使用之前确认该环境属于用户且正确无误。

关联环境会改变操作所用的凭据——先确认

pulumi config env add 会编辑堆栈配置（Pulumi.<stack>.yaml），并改变 Pulumi 操作所使用的凭据。未经用户明确确认，绝不能运行该命令；也绝不能传入 --yes 跳过确认。告诉用户会发生哪些更改，并让他们决定。

声称修复成功前先验证

关联后，在环境打开或运行之前，解析出的凭据值通常会显示为 [unknown]。在验证之前，不要声称错误已修复，也不要声称下一项操作会成功；请检查 pulumi config，并确认凭据解析到预期账户后，再宣布成功。

快速故障排查

“Environment not found”：使用 pulumi env ls -o <org> 检查权限
“Secret decryption failed”：使用 pulumi env open，而不是 pulumi env get
“Stack can't read values”：检查 pulumi config env ls，确认堆栈已列出。
- 确保环境仅使用项目名称/环境名称格式引用。
- 使用 pulumi env get <org>/<project-name>/<environment-name> 获取特定的环境定义。
- 确认 pulumiConfig 键存在，并嵌套在 values 键下。

支持 Markdown

登录后评论

基本信息

作者: pulumi
仓库: pulumi/agent-skills
分类: 云与 DevOps
安装次数: 1,428
GitHub Stars: 78

报告问题