You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Enhance documentation structure for Pulumi ESC getting started guides (#16533)
* Enhance documentation structure and content for Pulumi ESC getting started guides
* Implementing claude's feedback
* wip
* Add guides for Pulumi ESC, including managing secrets, integrating with Pulumi IaC, and setting up OIDC
- Introduced new "Get Started"
- Created a new index page for guides on Pulumi ESC.
- Added detailed guides for integrating external secrets from AWS, Azure, and GCP.
- Introduced a guide on importing environments to share configuration across teams.
- Developed a guide on managing secrets, including storing and retrieving them.
- Added instructions for running commands with `esc run` to inject secrets into scripts.
- Created a guide for setting up OIDC to generate dynamic cloud credentials.
- Updated references in existing documentation to point to new guides.
* Update links in documentation for Pulumi ESC and cloud credentials integration
* Refine documentation for Pulumi ESC: update links, clarify prerequisites, and enhance instructions for OIDC setup and environment importing
* Add script to add borders to PNG images in markdown files
- Created a new script `add_borders.py` that adds 1px #CCCCCC borders to PNG images referenced in markdown files.
- Implemented functionality to check for existing borders and avoid duplication.
- Added metadata to processed images to track border addition.
- Included a `Pipfile` for dependency management, requiring `pillow` and `click`.
- Added command-line interface for user interaction, supporting dry-run mode.
* Enhance "Create your first environment" section: improve clarity and formatting of steps, update YAML example, and refine secret handling explanation
* Refactor configuration retrieval in examples: update to use 'region' and 'apiKey' instead of 'myEnvironment' and 'myPassword' across multiple languages
* Refine documentation for ESC integration: streamline environment editing instructions and enhance clarity on using CLI and Pulumi Cloud console
* Enhance documentation for environment imports: add introductory notes, clarify import modes, and update related guides for better user guidance
* Add guides section with tutorials for common ESC workflows
description: Add 1px grey borders to PNG images in a documentation file.
3
+
---
4
+
5
+
# Usage
6
+
7
+
`/add-borders <doc-file-path>`
8
+
9
+
Analyze PNG images referenced in the specified markdown file at {{arg}} and add 1px #999999 (medium grey) borders to any images that don't already have them. This improves visual clarity and consistency of screenshots and diagrams in documentation.
10
+
11
+
---
12
+
13
+
## Process
14
+
15
+
### 1. Verify prerequisites
16
+
17
+
Before running the border tool, ensure dependencies are installed:
18
+
19
+
```bash
20
+
cd /workspaces/src/pulumi/docs/scripts/image-borders && pipenv install
21
+
```
22
+
23
+
If this is the first run or if Pillow is not yet installed, the installation will complete automatically.
24
+
25
+
### 2. Run the border addition tool
26
+
27
+
Execute the Python script with the provided documentation file:
28
+
29
+
```bash
30
+
cd /workspaces/src/pulumi/docs && pipenv run python scripts/image-borders/add_borders.py {{arg}}
31
+
```
32
+
33
+
The script will:
34
+
- Parse the markdown file to find all PNG image references
35
+
- Check each image's edge pixels to detect existing borders
36
+
- Add a 1px #999999 border to images that don't have one
37
+
- Skip images that already have a grey border (within tolerance)
38
+
- Display a summary of modified and skipped images
Copy file name to clipboardExpand all lines: .claude/commands/glow-up.md
+10-3Lines changed: 10 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -76,8 +76,13 @@ Read the entire target file and perform comprehensive analysis:
76
76
77
77
For each image or diagram referenced in the document:
78
78
79
-
1. Use the Read tool to view the image
80
-
2. Analyze the image for the following issues:
79
+
1.**Check for missing borders on PNG images**: Run the border detection script with dry-run mode to deterministically identify which PNG images need borders:
80
+
```bash
81
+
cd /workspaces/src/pulumi/docs/scripts/image-borders && pipenv run python add_borders.py <file-path> --dry-run
82
+
```
83
+
The script will report which images would be modified vs skipped.
84
+
85
+
2. Regardless of existing borders, use the Read tool to view the image and analyze the image for the following issues:
81
86
82
87
**Screenshots:**
83
88
- Missing or inadequate alt text (accessibility requirement)
@@ -163,6 +168,7 @@ Develop a detailed plan organized by issue category:
163
168
- Images to convert to Mermaid/GoAT
164
169
- Unnecessary images to remove
165
170
- File format or size optimizations
171
+
- PNG images that need 1px grey borders for visual clarity
166
172
167
173
**7. Content enhancements** — List specific recommendations:
168
174
- Unclear sections that need rewriting
@@ -204,7 +210,8 @@ Once approved, implement the changes in logical order:
204
210
4.**Style improvements** (remove filler, simplify sentences, active voice)
205
211
5.**Link improvements** (improve link text, add cross-references)
206
212
6.**Image improvements** (add alt text, remove unnecessary images, flag outdated screenshots)
Copy file name to clipboardExpand all lines: content/docs/deployments/deployments/cloud-credentials.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ menu:
17
17
In order for a Pulumi IaC operation like `update` or `preview` work, the Pulumi CLI must be able to access credentials that will allow it to perform the necessary CRUD operations on the resources in your stack. In order for Pulumi Deployments to access the necessary cloud credentials to run your Pulumi operation there are two common approaches you can take:
18
18
19
19
1.**Use [Pulumi Deployments' OIDC integration](/docs/deployments/deployments/oidc/)** where possible (we support [AWS](/docs/deployments/deployments/oidc/aws/), [Azure](/docs/deployments/deployments/oidc/azure/), and [Google Cloud](/docs/deployments/deployments/oidc/gcp/)), and store any remaining required secrets or configuration in [Pulumi Deployments Environment Variables](/docs/deployments/deployments/reference/#deployment-settings).
20
-
2.**Use [Pulumi ESC](/docs/esc/)** to define an Environment (or Environments), and [import the environment(s) into your stack](/docs/esc/get-started/integrate-with-pulumi-iac/).
20
+
2.**Use [Pulumi ESC](/docs/esc/)** to define an Environment (or Environments), and [import the environment(s) into your stack](/docs/esc/guides/integrate-with-pulumi-iac/).
21
21
22
22
## Choosing between Pulumi ESC Environments and Pulumi Deployments OIDC
Copy file name to clipboardExpand all lines: content/docs/esc/concepts/_index.md
+98-29Lines changed: 98 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
title: Concepts
3
3
title_tag: Pulumi ESC Concepts
4
4
h1: Pulumi ESC Concepts
5
-
meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
5
+
meta_desc: Learn the core concepts of Pulumi ESC including environments, providers, composition, and the evaluation model.
6
6
menu:
7
7
esc:
8
8
parent: esc-home
@@ -12,58 +12,127 @@ aliases:
12
12
- /docs/concepts/environments/
13
13
---
14
14
15
-
Pulumi ESC (Environments, Secrets, and Configuration) simplifies how organizations manage secrets and configurations across multiple environments. It enables teams to compose collections of configuration and secrets called *environments*, which can be consumed by various infrastructure and application services. ESC helps ensure security, consistency, and efficiency in handling secrets and configuration.
15
+
Pulumi ESC (Environments, Secrets, and Configuration) is a secrets and configuration management system built around four core concepts: environments, sources, targets, and management. Understanding these concepts will help you build a mental model of how ESC works.
16
16
17
-
Pulumi ESC is offered both as a fully managed cloud service in [Pulumi Cloud](/docs/pulumi-cloud/) and self-hosted for scenarios that require isolated environments. ESC has native integration with several products and other Pulumi products, including Pulumi Infrastructure as Code (IaC). The [pulumi/esc project](https://github.com/pulumi/esc) is open source, and contains the evaluation engine for environments, the `esc` CLI.
17
+
Pulumi ESC is available as a fully managed service in [Pulumi Cloud](/docs/pulumi-cloud/) and can be self-hosted for isolated environments. The [pulumi/esc project](https://github.com/pulumi/esc) is open source and contains the evaluation engine and CLI.
18
18
19
19
{{< figure src="/docs/esc/assets/pulumi_esc.png" caption="Figure: The Pulumi ESC ecosystem.">}}
20
20
21
-
The diagram above shows four key concepts:
21
+
## Core concepts
22
22
23
-
1.***Environments***: ESC environments are collections of secrets and configuration. Environments are composable from multiple environments and draw from both static and dynamic sources and can be shared to many targets.
23
+
### Environments
24
24
25
-
2.***Sources***: ESC can *input* configuration and secrets from a variety of sources, and it has an extensible plugin model for integrating third-party sources. ESC's built-in support for dynamic secret providers, allows for best-practices like generating short-term credentials via OIDC, and dynamically pulling secret values at the time of use, for all major cloud providers.
25
+
An environment is a named collection of configuration values and secrets defined in YAML. Environments are the fundamental unit of organization in ESC. Each environment:
26
26
27
-
3.***Targets***: ESC *outputs* configuration and secrets to a variety of popular targets. Pulumi ESC has a rich API that allows for easy integration, and provides standard output mechanisms like environment variables and key files.
27
+
- Has a unique name within a project (e.g., `my-org/my-project/production`)
28
+
- Contains a YAML document that defines values, imports other environments, and configures providers
29
+
- Is versioned—every change creates a new version
30
+
- Can be tagged for easier reference (e.g., `stable`, `v1.2.3`)
31
+
- Is evaluated when opened, resolving all dynamic values and imports
28
32
29
-
4.***Management***: ESC environments are centrally managed in Pulumi Cloud, and can be permissioned with RBAC, versioned, tagged, and audited. ESC secrets are encrypted in flight and at rest.
33
+
Environments are composable: one environment can import others, inheriting and overriding their values. This enables organizing configuration hierarchically to match team boundaries and security requirements.
30
34
31
-
##The ESC Approach
35
+
### Sources
32
36
33
-
Pulumi ESC takes a distinct approach to managing secrets and configuration that is different from other secret managers. ESC emphasizes flexibility and an open-ecosystem approach to integrations and is specifically designed for managing secrets and configurations across complex multi-cloud environments. Whether used in conjunction with [Pulumi IaC](/docs/iac/) or as a standalone tool, ESC helps streamline operations, reduce duplication, and enhance security for teams across a wide range of use cases.
37
+
ESC pulls configuration and secrets from multiple sources through an extensible provider system:
34
38
35
-
### Centralized management, composability, and reusability
39
+
-**Static values** - Key-value pairs defined directly in the environment YAML
40
+
-**Dynamic providers** - Plugins that generate or retrieve values at evaluation time:
- Secret providers retrieve values from external systems (AWS Secrets Manager, Azure Key Vault, 1Password)
43
+
- Login providers authenticate with cloud services
36
44
37
-
Pulumi ESC aggregates secrets and configuration from different sources into *environments*. These environments can be composed from other environments, allowing for flexible organization and reuse without duplication.
45
+
Dynamic providers execute when an environment is opened, not when it's defined. This ensures credentials and secrets are fresh and never stored.
38
46
39
-
Pulumi ESC provides fine-grained **Role-Based Access Control (RBAC)**, ensuring that only authorized users and teams can access specific environments and retrieve secrets. Audit logs track who accessed or changed the configurations, enhancing security and accountability.
47
+
### Targets
48
+
49
+
ESC outputs configuration and secrets to multiple targets:
50
+
51
+
-**Environment variables** - Inject secrets into processes via the `esc run` command
Pulumi ESC environments can be structured to reflect an organization’s team structure, security boundaries, or deployment targets. The above diagram shows an example of how a customer might organize and compose different security environments.
77
+
An organization might structure environments by team and security boundaries:
78
+
79
+
-**Central platform team** - Owns common configuration like OIDC settings and feature flags
80
+
-**Billing service team** - Manages payment processor secrets
81
+
-**Communications team** - Manages secrets for mailing and texting services
82
+
83
+
Each team's environment can be independently permissioned and versioned. Application environments import these base environments and add application-specific configuration. When environments import others, values are merged using JSON Merge Patch semantics—later values override earlier ones.
84
+
85
+
This structure:
86
+
87
+
- Reduces duplication by sharing common configuration
88
+
- Enforces security boundaries through separate permissions per environment
89
+
- Allows teams to update their environments without affecting others
90
+
- Enables complex applications to compose from multiple security contexts
91
+
92
+
## Static vs. dynamic values
93
+
94
+
ESC supports both static and dynamic values in the same environment:
95
+
96
+
**Static values** are defined directly in the YAML and evaluated once:
44
97
45
-
Imagine a hypothetical development organization comprised of a few teams:
98
+
```yaml
99
+
values:
100
+
region: us-west-2
101
+
apiEndpoint: https://api.example.com
102
+
```
46
103
47
-
* The *billing service* team, that manages secrets/config for the payment processor
48
-
* The *communications* team, that manages secrets/config for the mailing service and texting service.
49
-
* The *central platform* team, that owns most common config, including OIDC config and the keys/config for the feature flag system.
104
+
**Dynamic values** are generated or retrieved when the environment is opened:
50
105
51
-
Permissions to these environments can be defined separately to minimize security exposure. They can be reused independently or composed into more complex application scenarios.
106
+
```yaml
107
+
values:
108
+
aws:
109
+
login:
110
+
fn::open::aws-login:
111
+
oidc:
112
+
roleArn: arn:aws:iam::123456789012:role/my-role
113
+
environmentVariables:
114
+
AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
115
+
```
52
116
53
-
### Dynamic vs static configurations
117
+
Dynamic providers execute during evaluation, generating fresh credentials or retrieving current values. This ensures credentials are short-lived and secrets are never stale.
54
118
55
-
Pulumi ESC supports both **static** configurations (e.g. simple key-value pairs) and **dynamic** configurations (values retrieved from third-party providers) in the same environment. This allows teams to mix-and-match the type of configuration they need.
119
+
## Configuration as code
56
120
57
-
Pulumi ESC also supports **dynamic secret providers**, such as AWS OIDC, Azure KeyVault, GCP Secrets Manager, and more. This allows teams to pull short-lived credentials or other secrets dynamically from external sources.
121
+
ESC environments are defined as YAML documents that can be:
58
122
59
-
More detail on dynamic secret providers is available in [Adding OIDC and secrets providers](/docs/esc/environments/working-with-environments/#using-secrets-providers-and-oidc). The [providers list](/docs/esc/integrations/) details the currently supported integrations.
123
+
- Edited directly in the Pulumi Cloud console
124
+
- Modified via the `esc` CLI
125
+
- Managed programmatically through SDKs (TypeScript, Python, Go)
126
+
- Automated in CI/CD pipelines via the API
60
127
61
-
### Configuration-as-Code, automation, and integration everywhere
128
+
Environments support:
62
129
63
-
Like our other products, Pulumi ESC uses an "as-code" approach to configuration and secrets. ESC environments can be composed, managed, and accessed using code written in TypeScript, JavaScript, Go, Python, or YAML. The `esc` CLI and our full-featured API allows for scripted use in automated environments like CI/CD. This reduces copy/paste style duplication of credentials and allows for management from a single source of truth. ESC is already deeply integrated into Pulumi IaC and Pulumi Cloud, and provides a number of third-party product integrations both as secrets providers and consumers.
130
+
- **Interpolation** - Reference other values with `${path.to.value}` syntax
131
+
- **Functions** - Transform values with built-in functions (`fn::secret`, `fn::toJSON`)
Copy file name to clipboardExpand all lines: content/docs/esc/environments/_index.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ menu:
7
7
esc:
8
8
parent: esc-home
9
9
identifier: esc-environments
10
-
weight: 4
10
+
weight: 5
11
11
---
12
12
13
13
Pulumi ESC (Environments, Secrets, and Configuration) lets you define collections of configuration settings and secrets called _environments_ and use them in any application or service. Environments are YAML documents composed of static key-value pairs, programmatic expressions, dynamically retrieved values from supported providers including all major clouds through OpenID Connect (OIDC), and other Pulumi ESC environments.
0 commit comments