ESC Content Enhancements (#3828)

ESC Content refactor first round updates

themes/default/content/docs/pulumi-cloud/esc/_index.md → themes/default/content/docs/esc/_index.md

@@ -3,22 +3,27 @@ title: Pulumi ESC
 title_tag: Pulumi ESC (Environments, Secrets, and Configuration)
 h1: Pulumi ESC (Environments, Secrets, and Configuration)
 meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
+meta_image: /images/docs/meta-images/docs-meta.png
 menu:
-  pulumicloud:
+  pulumiesc:
+    name: Overview
     identifier: esc
-    weight: 4
+    weight: 5
 aliases:
   - /docs/esc/
+  - /docs/pulumi-cloud/esc/
 ---
 
 Pulumi ESC (Environments, Secrets, and Configuration) allows teams to tackle secrets and configuration complexity for modern cloud environments, alleviating maintenance burden and reducing costly mistakes, and creating a "secure by default" posture. Pulumi ESC is a new category of configuration as code product, motivated by our experience working with hundreds of Pulumi IaC customers to address their needs in managing secrets and configuration at scale within their Pulumi infrastructure and across other cloud applications and infrastructure projects.
 
 Pulumi ESC enables teams to aggregate secrets and configuration from many sources into a composable collection called an [environment](/docs/concepts/environments/). Teams can then consume those configuration and secrets from a variety of different infrastructure and application services.  Pulumi ESC works hand-in-hand with Pulumi IaC to simplify configuration management, as well as a standalone CLI and API for other use cases apart from Pulumi IaC.
 
-Pulumi ESC is offered as a fully managed cloud service in Pulumi Cloud (and Pulumi Cloud Self-hosted in the near future). The pulumi/esc project is open source, and contains the evaluation engine for environments, the esc CLI, and in the future, the extensible plugins for source and target integrations.  
+Pulumi ESC is offered as a fully managed cloud service in [Pulumi Cloud](/docs/pulumi-cloud/) (and Pulumi Cloud Self-hosted in the near future). The [pulumi/esc project](https://github.com/pulumi/esc) is open source, and contains the evaluation engine for environments, the esc CLI, and in the future, the extensible plugins for source and target integrations.  
 
 ![Pulumi ESC ecosystem](img/pulumi_esc.png)
 
+The following details corresponds to the numbered sections in the above diagram:
+
 1. Pulumi ESC enables you to define environments, which contain collections of secrets and configuration. Each environment can be composed from multiple environments.
 
 2. Pulumi ESC supports a variety of configuration and secrets sources, and it has an extensible plugin model that allows third-party sources.
@@ -29,7 +34,7 @@ Pulumi ESC is offered as a fully managed cloud service in Pulumi Cloud (and Pulu
 
 ## Dynamic Secrets Providers
 
-Support for dynamic configuration providers allow Pulumi ESC to integrate with secrets stored in any other provider.  Organizations often use AWS OIDC, AWS Secrets Manager, Vault, Azure OIDC, Azure KeyVault, GCP OIDC, and GCP Secrets Manager plus many more sources of truth for their secrets and configuration.  Pulumi ESC supports them all, providing a single interface to your configuration and secrets, no matter where their source of truth is.  Pulumi ESC works with these tools to provide improved management of secrets and configuration.
+Support for dynamic configuration providers allow Pulumi ESC to [integrate with secrets stored in any other provider](/docs/esc/providers/).  Organizations often use AWS OIDC, AWS Secrets Manager, Vault, Azure OIDC, Azure KeyVault, GCP OIDC, and GCP Secrets Manager plus many more sources of truth for their secrets and configuration.  Pulumi ESC supports them all, providing a single interface to your configuration and secrets, no matter where their source of truth is.  Pulumi ESC works with these tools to provide improved management of secrets and configuration.
 
 Teams can setup OIDC in their cloud providers to allow Environments to retrieve dynamic short-lived credentials. They can also pull secrets from other secrets managers and vaults.
 
@@ -45,7 +50,7 @@ Environments are defined as YAML documents which can describe how to project and
 
 ## Authentication and RBAC
 
-Pulumi ESC brokers access to secrets and configuration that live in other systems, and so authentication and granular RBAC are critical to ensure robust access controls across your organization. Pulumi ESC leverages the same Pulumi Cloud identity, RBAC, Teams, SAML/SCIM and scoped access tokens that are used for Pulumi IaC today, extending these all to managing access to environments as well as Stacks.
+Pulumi ESC brokers access to secrets and configuration that live in other systems, and so authentication and granular RBAC are critical to ensure robust access controls across your organization. Pulumi ESC leverages the same Pulumi Cloud identity, RBAC, Teams, SAML/SCIM and scoped access tokens that are used for Pulumi IaC today, extending these all to managing access to environments as well as [Stacks](/docs/concepts/stack/).
 
 Teams can create and control access to their environments. They can control who can update and preview environments, as well as who can open environments and retrieve their secrets. Audit logs let teams know who has changed or accessed configuration.
 

themes/default/content/docs/pulumi-cloud/esc/environments.md → themes/default/content/docs/esc/environments.md

@@ -4,8 +4,7 @@ title_tag: Pulumi ESC Environments
 h1: Pulumi ESC Environments
 meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
 menu:
-  pulumicloud:
-    parent: esc
+  pulumiesc:
     identifier: environments
     weight: 2
 search:
@@ -14,6 +13,8 @@ search:
     - environments
     - secrets
     - configuration
+aliases:
+  - /docs/pulumi-cloud/esc/environments/
 ---
 
 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.

themes/default/content/docs/pulumi-cloud/esc/faq.md → themes/default/content/docs/esc/faq.md

@@ -5,8 +5,7 @@ title: FAQ
 h1: Pulumi ESC FAQs
 meta_image: /images/docs/meta-images/docs-meta.png
 menu:
-  pulumicloud:
-    parent: esc
+  pulumiesc:
     weight: 6
     identifier: faq
 ---

themes/default/content/docs/esc/get-started/_index.md

@@ -0,0 +1,20 @@
+---
+title: Get started
+title_tag: Get Started with Pulumi ESC (Environments, Secrets, and Configuration)
+h1: Get Started with Pulumi ESC (Environments, Secrets, and Configuration)
+meta_desc: Learn how to manage secrets and hierarchical configuration with Pulumi.
+menu:
+  pulumiesc:
+    identifier: esc-get-started
+    weight: 1
+aliases:
+  - /docs/pulumi-cloud/esc/get-started/
+---
+
+In a typical application or infrastructure development workflow, there's often a need to maintain multiple environments such as development, staging, and production. Each of these environments might have its own set of configuration values: API endpoints, database connection strings, third-party secrets, and more.
+
+Hardcoding these values or keeping them inside source code is a security risk and makes managing configurations complex. [Pulumi ESC (Environments, Secrets and Configuration)](/docs/esc/) offers a centralized store to manage configuration data, plain-text data, and secrets.
+
+In this tutorial, we’ll demonstrate how to use Pulumi ESC as well as the power of this service in managing configuration and secrets.
+
+{{< get-started-stepper >}}

themes/default/content/docs/esc/get-started/begin.md

@@ -0,0 +1,93 @@
+---
+title_tag: Before You Begin | Pulumi ESC
+title: Before you begin
+h1: "Pulumi ESC: Before you begin"
+meta_desc: This page provides an overview on how to get started with Pulumi ESC.
+weight: 2
+menu:
+  pulumiesc:
+    parent: esc-get-started
+    identifier: esc-get-started-begin
+---
+
+Before you get started using Pulumi ESC, let's run through a few quick steps to ensure your environment is set up correctly.
+
+### Create a Pulumi account
+
+Pulumi ESC is a service of Pulumi Cloud, meaning you will need to create a Pulumi account to be able to use it. To do so, navigate to the [Pulumi Cloud console](https://app.pulumi.com) and create a new account. Once created, you can [optionally create an access token](/docs/pulumi-cloud/access-management/access-tokens/). Doing so will provide you an alternative way to sign into the Pulumi Cloud via the CLI. The token can also be used to automate your usage of the Pulumi Cloud using the REST API.
+
+### Install the Pulumi ESC CLI
+
+{{< notes type="info" >}}
+Pulumi ESC can be used with or without Pulumi IaC. This means that if you already have the [Pulumi IaC CLI](/docs/cli/) installed, you do not need to install the Pulumi ESC CLI, and you may substitute `pulumi env` anywhere you see the `esc env` command in the rest of this tutorial.
+{{< /notes >}}
+
+Use the below option to install the Pulumi ESC CLI based on your operating system.
+
+{{< chooser os "macos,windows,linux" >}}
+
+{{% choosable os macos %}}
+
+```bash
+$ brew update && brew install pulumi/tap/esc
+```
+
+{{% /choosable %}}
+
+{{% choosable os linux %}}
+
+```bash
+$ curl -fsSL https://get.pulumi.com/esc/install.sh | sh
+```
+
+{{% /choosable %}}
+
+{{% choosable os windows %}}
+
+<div class="mb-6 border-solid border-b-2 border-gray-200">
+<div class="w-full">
+<h3 class="no-anchor pt-4"><i class="fas fa-download pr-2"></i>Windows Binary Download</h3>
+<p>
+<a class="btn btn-secondary mx-2" href="https://get.pulumi.com/esc/releases/esc-v{{< latest-version-esc >}}-windows-x64.zip">amd64</a>
+</p>
+</div>
+</div>
+
+{{% /choosable %}}
+
+{{% /chooser %}}
+
+You can explore more installation options by visiting the [ESC installation docs](/docs/install/esc/).
+
+### Login to the ESC CLI
+
+Run the following command to log into the CLI:
+
+```bash
+esc login
+```
+
+You will be prompted to log in to the Pulumi Cloud using either the browser or by optionally providing an access token.
+
+```bash
+$ esc login
+Manage your Pulumi ESC environments by logging in.
+Run `esc --help` for alternative login options.
+Enter your access token from https://app.pulumi.com/account/tokens
+    or hit <ENTER> to log in using your browser                   :
+Logged in to https://api.pulumi.com/ as your-pulumi-org (https://app.pulumi.com/your-pulumi-org)
+```
+
+### [Optional] Configure OpenID Connect (OIDC)
+
+Pulumi supports [OpenID Connect (OIDC) integration](/docs/pulumi-cloud/oidc/) across various services including Pulumi ESC. OIDC enables secure interactions between Pulumi and cloud providers by leveraging signed, short-lived tokens issued by the Pulumi Cloud. Use one of the following guides below to configure OIDC between Pulumi ESC and your chosen cloud provider:
+
+- [OIDC Configuration for AWS](/docs/pulumi-cloud/oidc/aws/)
+- [OIDC Configuration for Azure](/docs/pulumi-cloud/oidc/azure/)
+- [OIDC Configuration for Google Cloud](/docs/pulumi-cloud/oidc/gcp/)
+
+This is an optional step that is not required to get started with Pulumi ESC. There are some steps in this series that will require OIDC configuration to complete, but that will be indicated on the relevant pages.
+
+In the next section, you will start your journey with Pulumi ESC by creating a new environment.
+
+{{< get-started-stepper >}}

themes/default/content/docs/esc/get-started/create-environment.md

@@ -0,0 +1,59 @@
+---
+title_tag: Create a New Environment | Pulumi ESC
+title: Create environment
+h1: "Pulumi ESC: Create A New Environment"
+meta_desc: This page provides an overview on how to create a new Pulumi ESC environment.
+weight: 3
+menu:
+  pulumiesc:
+    parent: esc-get-started
+    identifier: esc-get-started-create-environment
+
+---
+
+## Overview
+
+In Pulumi ESC, an environment is a collection of configuration intended to capture the configuration values needed to work with a particular environment.
+
+An environment can be created one of two ways:
+
+- via the Pulumi Cloud console
+- via the CLI
+
+This tutorial will walk you through how to create a new environment.
+
+## Create an environment
+
+### Create via the console
+
+To create an environment via the console, navigate to [Pulumi Cloud](https://app.pulumi.com) and select the **Environments** link in the left-hand menu.
+
+You will be directed to the Environments landing page. To create a new environment, click the **Create Environment** button. Enter a name for your environment (e.g., `my-dev-environment` for a development environment) and then click **Create Environment**. You will then be directed to the environment definition page.
+
+{{< video title="Creating a new environment in the Pulumi ESC console" src="/docs/esc/get-started/esc-create-new-env.mp4" autoplay="true" loop="true" >}}
+
+### Create via the CLI
+
+To create an environment via the CLI, use the `esc env init` command as shown below, where `<org-name>` is optional and defaults to your Pulumi Cloud username.
+
+```bash
+esc env init [<org-name>/]<environment-name>
+```
+
+Note that environment names must be unique within an organization and may only contain alphanumeric characters, hyphens, underscores, and periods.
+
+```bash
+$ esc env init my-dev-environment
+Environment created.
+```
+
+You can validate that your environment was created by running the `esc env ls` command which will list all of the environments that you have access to.
+
+```bash
+$ esc env ls
+myorg/test
+```
+
+In the next section, you will learn how to store configuration values and secrets in your environment.
+
+{{< get-started-stepper >}}