-
Notifications
You must be signed in to change notification settings - Fork 221
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update the concepts and how esc works pages #12960
base: master
Are you sure you want to change the base?
Conversation
Your site preview for commit 49c27b4 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-12960-49c27b4c.s3-website.us-west-2.amazonaws.com. |
Thx Troy adding @komalali and @arunkumar611 for review as well. |
@@ -12,51 +12,60 @@ aliases: | |||
- /docs/concepts/environments/ | |||
--- | |||
|
|||
Do you have secrets and configuration that is copy/pasted around multiple environments, that is prone to drift and accidental disclosure? Have you ever made a change to a config or secret and were unsure what the impact would be? Is it hard for developers in your organization to get access to short-lived credentials to work in the environments they need to develop and deploy into? Do you struggle to audit access levels and who has accessed or changed your secrets and configuration? | |||
Pulumi ESC (Environments, Secrets, and Configuration) is a tool that simplifies how organizations manage secrets and configurations across multiple environments. It enables teams to compose collections of configuration and secrets, which can be consumed by various infrastructure and application services. ESC helps ensure security, consistency, and efficiency in handling secrets and configuration. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pulumi ESC (Environments, Secrets, and Configuration) is a tool that simplifies how organizations manage secrets and configurations across multiple environments. It enables teams to compose collections of configuration and secrets, which can be consumed by various infrastructure and application services. ESC helps ensure security, consistency, and efficiency in handling secrets and configuration. | |
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. |
|
||
Pulumi ESC (Environments, Secrets, and Configuration) enables teams to create collections of configuration and secrets called Environments. Teams can then access those environment collections using the `esc` CLI, `pulumi` CLI, Pulumi SDK, or Pulumi Cloud REST API for various application and infrastructure needs. These environments can be composed of other environments to allow teams increased flexibility and fine-grained access control. Teams can have as many environments as they need. | ||
Pulumi ESC is offered as a fully managed cloud service in [Pulumi Cloud](/docs/pulumi-cloud/). ESC is a standalone tool that can be applied to many uses cases. It has native integration with our other 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pulumi ESC is offered as a fully managed cloud service in [Pulumi Cloud](/docs/pulumi-cloud/). ESC is a standalone tool that can be applied to many uses cases. It has native integration with our other 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. | |
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. |
|
||
## Removing Duplication |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would keep this
|
||
1. Pulumi ESC enables you to define environments, which contain collections of secrets and configuration. Each environment can be composed from multiple environments. | ||
{{< figure src="/docs/esc/assets/esc-octopus-diagram.png" caption="Figure: A diagram showing the architecture of Pulumi ESC.">}} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can you ensure we use the image consistency? In www.pulumi.com/esc - we use the other image for "How ESC works" - here we use this octopus diagram.
|
||
## Dynamic Secret Providers | ||
4. ***Management***: ESC environments are centrally managed in Pulumi Cloud, and can be locked down with RBAC, versioned, tagged, and audited. ESC secrets are encrypted in flight and at rest. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
4. ***Management***: ESC environments are centrally managed in Pulumi Cloud, and can be locked down with RBAC, versioned, tagged, and audited. ESC secrets are encrypted in flight and at rest. | |
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. |
|
||
For more detail, see [adding OIDC and Secrets providers](/docs/esc/environments/working-with-environments/#adding-oidc-and-secrets-providers). | ||
### Centralized management, composability, and reusability |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the explanation under this section seems to talk about only the "management" piece - more specifically RBAC - and doesn't talk anything about composability/reusability.... And composability and reusability are synonyms?
|
||
Access permissions can be set to only allow select members or teams to "open" an environment and retrieve secrets. | ||
Pulumi ESC takes a distinct approach to managing secrets and configuration that is different from other secret managers. ESC emphasizes flexiblity and integration, 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pulumi ESC takes a distinct approach to managing secrets and configuration that is different from other secret managers. ESC emphasizes flexiblity and integration, 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. | |
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. |
|
||
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. | ||
|
||
More detail on dynamic secret providers is available in [Adding OIDC and secrets providers](/docs/esc/environments/working-with-environments/#adding-oidc-and-secrets-providers). The [providers list](/docs/esc/integrations/) details the currently supported integrations. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this link seems incorrect
|
||
More detail on dynamic secret providers is available in [Adding OIDC and secrets providers](/docs/esc/environments/working-with-environments/#adding-oidc-and-secrets-providers). The [providers list](/docs/esc/integrations/) details the currently supported integrations. | ||
|
||
### Configuration-as-Code, automation, and integration everywhere |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we should talk about composability here and not in the section above
|
||
### Configuration-as-Code, automation, and integration everywhere | ||
|
||
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. ESC is already deeply integrated into Pulumi IaC and Pulumi Cloud, and its plugin AP makes it easy to integrate ESC with any third-party product either as a provider or consumer. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. ESC is already deeply integrated into Pulumi IaC and Pulumi Cloud, and its plugin AP makes it easy to integrate ESC with any third-party product either as a provider or consumer. | |
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 allow for scripted use in automated environments like CI/CD. ESC is integrated into Pulumi IaC and Pulumi Cloud, and its plugin AP makes it easy to integrate ESC with any third-party product either as a provider or consumer. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What's Plugin AP?
|
||
![Pulumi ESC ecosystem](/docs/esc/assets/pulumi_esc.png) | ||
Pulumi ESC is a hosted service provided as part of [Pulumi Cloud](/docs/pulumi-cloud/). ESC stores your secrets and configuration and proxies access to other secret stores through provider plugins. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
again, add a note about self-hosted
|
||
3. Pulumi ESC has a rich API that allows for easy integration. Every value in an environment can be accessed from any target execution environment. | ||
By default, Pulumi ESC stores your configuration and secrets in Pulumi Cloud. However, ESC also integrates with a variety of third-party sources through an extensible *provider* plugin model. This allows teams to use their preferred providers without needing to manually copy or paste secrets across environments. The secrets will be dynamically fetched from the third-party API and integrated into your ESC environments. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
mention of providers here feels repetitive, we talked about it in the previous paragraph
|
||
## Dynamic Secrets Providers | ||
### Supported secret providers |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would call the "Dynamic Providers" and bucket them into Login providers and secret providers - just like the integrations left nav suggests
|
||
Environments are defined as YAML documents which can describe how to project and compose secrets and configuration, integrate dynamic configuration providers, and compute new configuration from other values (constructing a URL from a DNS name, or concatenating multiple configuration values into a derived value). The incredible flexibility of a code-based approach over traditional point-and-click interfaces allows Pulumi ESC to offer rich expressiveness for managing complex configuration. | ||
A simple static environment can be thought of as a collection of key/value pairs. They can also contain interpolated values and complex [structured configuration](/docs/esc/environments/working-with-environments/#structured-configuration). Static secrets are also defined in YAML, but the static values are encrypted. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A simple static environment can be thought of as a collection of key/value pairs. They can also contain interpolated values and complex [structured configuration](/docs/esc/environments/working-with-environments/#structured-configuration). Static secrets are also defined in YAML, but the static values are encrypted. | |
A simple static environment can be thought of as a collection of key/value pairs. They can also contain interpolated values and complex [structured configuration](/docs/esc/environments/working-with-environments/#structured-configuration). Static secrets are also defined in YAML and are encrypted before they are stored to ensure security. |
## Auditable | ||
myPassword: | ||
fn::secret: | ||
ciphertext: ZXNjeAA.... |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ciphertext is the resulting output of a secret... I wonder whether we should specify the input and what happens after the use saves. Right now if they copy this text, it won't work
fn::open::aws-login: | ||
oidc: | ||
roleArn: arn:aws:iam::01234567891011:role/some-role | ||
sessionName: some-session |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sessionName: some-session | |
sessionName: some-session | |
duration: 1h |
This makes some changes to the ESC docs Concepts and How ESC Works pages. The goal of this is to reduce the overlap/redundancy between the two pages and structure them better. It also includes the "octopus" diagram from the ESC product homepage.
Fixes: #12861 #12863