Back to Details

pulumi-esc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pulumi ESC (Environments, Secrets, and Configuration)

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

Pulumi ESC is a centralized service for managing environments, secrets, and configuration across cloud infrastructure and applications.
Pulumi ESC是一款用于跨云基础设施和应用集中管理环境、密钥与配置的服务。

What is ESC?

什么是ESC？

ESC enables teams to:
  • Centralize secrets and configuration in one secure location
  • Compose environments by importing and layering configuration
  • Generate dynamic credentials via OIDC for AWS, Azure, GCP
  • Integrate external secret stores (AWS Secrets Manager, Azure Key Vault, Vault, 1Password)
  • Version and audit all configuration changes
  • Control access with fine-grained RBAC
ESC支持团队：
  • 集中管理密钥与配置，将其存储在一个安全位置
  • 组合环境，通过导入和分层配置实现
  • 通过OIDC生成动态凭证，支持AWS、Azure、GCP
  • 集成外部密钥存储（AWS Secrets Manager、Azure Key Vault、Vault、1Password）
  • 版本控制与审计所有配置变更
  • 通过细粒度RBAC控制访问权限

Essential CLI Commands

核心CLI命令

bash
undefined
bash
undefined

Create a new environment

创建新环境

pulumi env init <org>/<project-name>/<environment-name>
pulumi env init <org>/<project-name>/<environment-name>

Edit environment (opens in editor)

编辑环境（在编辑器中打开）

pulumi env edit <org>/<project-name>/<environment-name>
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
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>
pulumi env get <org>/<project-name>/<environment-name>

Open and resolve (reveals secrets)

打开并解析（显示密钥）

pulumi env open <org>/<project-name>/<environment-name>
pulumi env open <org>/<project-name>/<environment-name>

Run command with environment

在环境中运行命令

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

Link to Pulumi stack

关联到Pulumi栈

pulumi config env add <project-name>/<environment-name>
undefined
pulumi config env add <project-name>/<environment-name>
undefined

Key Concepts

核心概念

Command Distinctions

命令区别

  • pulumi env get
    : Shows static definition, secrets appear as 
    [secret]
  • pulumi env open
    : Resolves and reveals all values including secrets and dynamic credentials
  • pulumi env run
    : Executes commands with environment variables loaded
  • pulumi config env add
    : Only takes the <project-name>/<environment-name> portion
  • pulumi env get
    ：显示静态定义，密钥会显示为
    [secret]
  • pulumi env open
    ：解析并显示所有值，包括密钥和动态凭证
  • pulumi env run
    ：加载环境变量后执行命令
  • pulumi config env add
    ：仅需传入<project-name>/<environment-name>部分

Environment Structure

环境结构

Environments are YAML documents with reserved top-level keys:
  • imports
    : Import and compose other environments
  • values
    : Define configuration and secrets
Reserved sub-keys under 
values
:
  • environmentVariables
    : Map values to shell environment variables
  • pulumiConfig
    : Configure Pulumi stack settings
  • files
    : Generate files with environment data
环境是包含保留顶级键的YAML文档：
  • imports
    ：导入并组合其他环境
  • values
    ：定义配置与密钥
values
下的保留子键：
  • environmentVariables
    ：将值映射为Shell环境变量
  • pulumiConfig
    ：配置Pulumi栈设置
  • files
    ：使用环境数据生成文件

Basic Example

基础示例

yaml
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}
yaml
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}

Working with the User

与用户协作的方式

For Simple Questions

处理简单问题

If the user asks basic questions like "How do I create an environment?" or "What's the difference between get and open?", answer directly using the information above.
如果用户询问基础问题，比如“如何创建环境？”或“get和open命令有什么区别？”，直接使用上述信息作答。

For Detailed Documentation

提供详细文档

When users need more information, use the web-fetch tool to get content from the official Pulumi ESC documentation:
Use the web-fetch tool with specific prompts to extract relevant information from these docs.
当用户需要更多信息时，使用网页抓取工具从Pulumi ESC官方文档获取内容：
使用网页抓取工具并传入特定提示，从这些文档中提取相关信息。

For Complex Tasks

处理复杂任务

When helping users:
  1. Understand the goal: Are they setting up new environments, migrating from stack config, or debugging?
  2. Check existing setup: Use 
    pulumi env
    commands to list environments or read definitions
  3. Fetch relevant documentation: Use the web-fetch to get specific examples or syntax from the official docs
  4. Provide step-by-step guidance: Walk through the process with specific commands
  5. Validate: Help them test with 
    pulumi env get
    or 
    pulumi preview
    a. Only use 
    pulumi env open
    when the full resolved values are needed, but use cautiously as it reveals secrets.
协助用户时：
  1. 明确目标：用户是要搭建新环境、从栈配置迁移还是调试问题？
  2. 检查现有设置：使用
    pulumi env
    命令列出环境或读取定义
  3. 获取相关文档：使用网页抓取工具从官方文档获取特定示例或语法
  4. 提供分步指导：通过具体命令引导用户完成流程
  5. 验证：帮助用户使用
    pulumi env get
    或
    pulumi preview
    进行测试 a. 仅当需要完整解析值时才使用
    pulumi env open
    ，但需谨慎操作，因为它会暴露密钥。

Example: Helping with AWS OIDC Setup

示例：协助配置AWS OIDC

text
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
text
用户：“如何在ESC中配置AWS OIDC凭证？”

1. 使用网页抓取工具从“https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/”获取AWS OIDC文档
2. 为用户提供配置内容
3. 询问用户是否已有预定义角色，还是需要创建新角色
4. 尽可能完成环境配置，然后引导用户完成无法代劳的步骤
5. 必要时帮助用户使用`pulumi env get`或`pulumi env open`进行测试

Common Workflows

常见工作流

Creating an Environment

创建环境

bash
pulumi env init my-org/my-project/dev-config
bash
pulumi env init my-org/my-project/dev-config

Edit environment (accepts new definition from a file, better for agents, more difficult for users)

编辑环境（支持从文件加载新定义，适合Agent使用，对用户而言难度较高）

pulumi env edit --file /tmp/example.yml my-org/my-project/dev-config
undefined
pulumi env edit --file /tmp/example.yml my-org/my-project/dev-config
undefined

Linking to Stack

关联到栈

bash
pulumi config env add my-project/dev-config
pulumi config  # Verify environment values are accessible
bash
pulumi config env add my-project/dev-config
pulumi config  # 验证环境值是否可访问

API Access (Rare)

API访问（罕见场景）

Always prefer CLI commands. Only use the API when absolutely necessary (e.g., bulk operations, automation).
Available API endpoints include:
  • GET /api/esc/environments/{orgName}
    - List environments
  • GET /api/esc/environments/{orgName}/{projectName}/{envName}
    - Read environment definition
  • GET /api/esc/providers?orgName={orgName}
    - List available providers
Use 
call_pulumi_cloud_api()
tool to make requests when needed.
优先使用CLI命令。仅在绝对必要时才使用API（例如批量操作、自动化）。
可用API端点包括：
  • GET /api/esc/environments/{orgName}
    - 列出环境
  • GET /api/esc/environments/{orgName}/{projectName}/{envName}
    - 读取环境定义
  • GET /api/esc/providers?orgName={orgName}
    - 列出可用提供商
必要时使用
call_pulumi_cloud_api()
工具发起请求。

Best Practices

最佳实践

  1. Always use 
    fn::secret
    for sensitive values
  2. Prefer OIDC over static keys
  3. Use descriptive names like 
    <org>/my-app/production-aws
    not 
    <org>/app/prod
  4. Layer environments: base → cloud-provider → stack-specific
  5. Verify that 
    pulumi config
    shows expected values after linking an environment to a stack
  6. Prefer using 
    pulumi env run
    for commands needing environment variables
  7. Only use 
    pulumi env open
    when absolutely necessary, as it reveals secrets
  1. 敏感值始终使用
    fn::secret
    标记
  2. 优先使用OIDC而非静态密钥
  3. 使用描述性名称，例如
    <org>/my-app/production-aws
    而非
    <org>/app/prod
  4. 分层环境：基础层 → 云提供商层 → 栈特定层
  5. 关联环境到栈后，验证
    pulumi config
    是否显示预期值
  6. 运行需要环境变量的命令时，优先使用
    pulumi env run
  7. 仅在绝对必要时使用
    pulumi env open
    ，因为它会暴露密钥

Quick Troubleshooting

快速故障排除

  • "Environment not found": Check permissions with 
    pulumi env ls -o <org>
  • "Secret decryption failed": Use 
    pulumi env open
    not 
    pulumi env get
  • "Stack can't read values": Verify 
    pulumi config env ls
    to ensure the stack is listed.
    • Ensure the environment is referenced only by the project-name/environment-name format.
    • Get the specific environment definition with 
      pulumi env get <org>/<project-name>/<environment-name>
      .
    • Verify the 
      pulumiConfig
      key exists and is nested under the 
      values
      key.
  • “环境未找到”：使用
    pulumi env ls -o <org>
    检查权限
  • “密钥解密失败”：使用
    pulumi env open
    而非
    pulumi env get
  • “栈无法读取值”：验证
    pulumi config env ls
    确保栈已列出。
    • 确保环境仅以project-name/environment-name格式引用。
    • 使用
      pulumi env get <org>/<project-name>/<environment-name>
      获取具体环境定义。
    • 验证
      pulumiConfig
      键存在且嵌套在
      values
      键下。