Update the concepts and how esc works pages #12960
Open
+141
−51
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
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. |
arunkumar611
reviewed
Oct 2, 2024
| @@ -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.
Suggested change
| 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. |
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| 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.
Suggested change
| 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. |
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| ## Removing Duplication |
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| 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.
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.
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| ## 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.
Suggested change
| 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. |
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| 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.
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?
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| 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.
Suggested change
| 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. |
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| 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. |
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| 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.
we should talk about composability here and not in the section above
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| ### 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.
Suggested change
| 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. |
arunkumar611
reviewed
Oct 2, 2024
|
|
||
|  | ||
| 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.
again, add a note about self-hosted
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| 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.
mention of providers here feels repetitive, we talked about it in the previous paragraph
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| ## Dynamic Secrets Providers | ||
| ### Supported secret providers |
There was a problem hiding this comment.
I would call the "Dynamic Providers" and bucket them into Login providers and secret providers - just like the integrations left nav suggests
arunkumar611
reviewed
Oct 2, 2024
|
|
||
| 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.
Suggested change
| 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. |
arunkumar611
reviewed
Oct 2, 2024
| ## Auditable | ||
| myPassword: | ||
| fn::secret: | ||
| ciphertext: ZXNjeAA.... |
There was a problem hiding this comment.
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
arunkumar611
reviewed
Oct 2, 2024
| fn::open::aws-login: | ||
| oidc: | ||
| roleArn: arn:aws:iam::01234567891011:role/some-role | ||
| sessionName: some-session |
There was a problem hiding this comment.
Suggested change
| sessionName: some-session | |
| sessionName: some-session | |
| duration: 1h |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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