[esc] update pulumi-cloud docs for projects (#12740)

* [esc] update pulumi-cloud for projects * add migration path to environments * add back api to paths
pulumi · Sep 11, 2024 · 209b81d · 209b81d
1 parent c33aeb0
commit 209b81d
Show file tree

Hide file tree

Showing 6 changed files with 80 additions and 59 deletions.
diff --git a/content/docs/pulumi-cloud/cloud-rest-api/_index.md b/content/docs/pulumi-cloud/cloud-rest-api/_index.md
@@ -3255,12 +3255,21 @@ Kubernetes Pods should not be used directly. Instead, you may want to use a Depl
 Pulumi ESC (Environments, Secrets, and Configuration) and its associated REST API endpoints are currently in public preview.
 {{< /notes >}}
 
+### Migrating from the Preview API
+
+For the majority of cases, the new API is a drop-in replacement for the preview API and the main changes are that the route itself has changed (i.e. replace `/api/preview` with `/api/esc`) and where environment name is part of the path it should be prefixed with the project (i.e. replace `/{orgName}/{envName}` with `{orgName}/{projectName}/{envName}`).
+
+However, there are a few cases where the new API has changed the behavior of the preview API. These changes are as follows:
+
+- The [Create Environment](#create-Environment) endpoint no longer takes the environment name in the request path, it has been moved to the request body.
+- The Create Version Tag endpoint no longer takes the tag name in the request path, it has been moved to the request body.
+
 <!-- ###################################################################### -->
 
 ### List Environments available to the authenticated user.
 
 ```
-GET /api/preview/environments/{organization}
+GET /esc/environments/{organization}
 ```
 
 #### Parameters
@@ -3277,7 +3286,7 @@ curl \
   -H "Accept: application/vnd.pulumi+8" \
   -H "Content-Type: application/json" \
   -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
-  https://api.pulumi.com/api/preview/environments/{organization}
+  https://api.pulumi.com/esc/environments/{organization}
 ```
 
 #### Default response
@@ -3291,6 +3300,7 @@ Status: 200 OK
 	"environments": [
 		{
 			"organization": "{organization}",
+      "project": "my-first-project",
 			"name": "my-first-environment",
 			"created": "2023-10-10 11:28:01",
 			"modified" :"2023-10-10 12:24:03",
@@ -3303,15 +3313,21 @@ Status: 200 OK
 ### Create Environment
 
 ```
-POST /api/preview/environments/{organization}/{environment}
+POST /api/esc/environments/{organization}
 ```
 
+### Body
+
+| Key                 | Type   | In    | Description       |
+|---------------------|--------|-------|-------------------|
+| `project`           | string | path  | project name      |
+| `name`              | string | path  | environment name  |
+
 #### Parameters
 
 | Parameter           | Type   | In    | Description       |
 |---------------------|--------|-------|-------------------|
 | `organization`      | string | path  | organization name |
-| `environment`       | string | path  | environment name  |
 
 #### Example
 
@@ -3321,7 +3337,7 @@ curl \
   -H "Content-Type: application/json" \
   -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
   --request POST \
-  https://api.pulumi.com/api/preview/environments/{organization}/{environment}
+  https://api.pulumi.com/api/esc/environments/{organization}/{environment}
 ```
 
 #### Default response
@@ -3333,12 +3349,13 @@ Status: 200 OK
 ### Get Environment
 
 ```
-GET /api/preview/environments/{organization}/{environment}
+GET /api/esc/environments/{organization}/{project}/{environment}
 ```
 
 | Parameter           | Type   | In    | Description       |
 |---------------------|--------|-------|-------------------|
 | `organization`      | string | path  | organization name |
+| `project`           | string | path  | project name      |
 | `environment`       | string | path  | environment name  |
 
 #### Example
@@ -3349,7 +3366,7 @@ curl \
   -H "Content-Type: application/json" \
   -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
   --request GET \
-  https://api.pulumi.com/api/preview/environments/{organization}/{environment}
+  https://api.pulumi.com/api/esc/environments/{organization}/{project}/{environment}
 ```
 
 #### Default response
@@ -3378,12 +3395,13 @@ Status: 200 OK
 ### Update Environment
 
 ```
-PATCH /api/preview/environments/{organization}/{environment}
+PATCH /api/esc/environments/{organization}/{project}/{environment}
 ```
 
 | Parameter           | Type   | In    | Description       |
 |---------------------|--------|-------|-------------------|
 | `organization`      | string | path  | organization name |
+| `project`           | string | path  | project name      |
 | `environment`       | string | path  | environment name  |
 
 #### Example
@@ -3395,7 +3413,7 @@ curl \
   -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
   --request PATCH \
   --data '<yaml content>' \
-  https://api.pulumi.com/api/preview/environments/{organization}/{environment}
+  https://api.pulumi.com/api/esc/environments/{organization}/{project}/{environment}
 ```
 
 #### Default response
@@ -3407,12 +3425,13 @@ Status: 200 OK
 ### Delete Environment
 
 ```
-DELETE /api/preview/environments/{organization}/{environment}
+DELETE /api/esc/environments/{organization}/{project}/{environment}
 ```
 
 | Parameter           | Type   | In    | Description       |
 |---------------------|--------|-------|-------------------|
 | `organization`      | string | path  | organization name |
+| `project`           | string | path  | project name      |
 | `environment`       | string | path  | environment name  |
 
 #### Example
@@ -3423,7 +3442,7 @@ curl \
   -H "Content-Type: application/json" \
   -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
   --request DELETE \
-  https://api.pulumi.com/api/preview/environments/{organization}/{environment}
+  https://api.pulumi.com/api/esc/environments/{organization}/{project}/{environment}
 ```
 
 #### Default response
@@ -3435,12 +3454,13 @@ Status: 200 OK
 ### Open Environment
 
 ```
-POST /api/preview/environments/{organization}/{environment}/open
+POST /api/esc/environments/{organization}/{project}/{environment}/open
 ```
 
 | Parameter           | Type   | In    | Description       |
 |---------------------|--------|-------|-------------------|
 | `organization`      | string | path  | organization name |
+| `project`           | string | path  | project name      |
 | `environment`       | string | path  | environment name  |
 | `duration`          | string | query | **Optional.** open duration - A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". |
 
@@ -3452,7 +3472,7 @@ curl \
   -H "Content-Type: application/json" \
   -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
   --request POST \
-  https://api.pulumi.com/api/preview/environments/{organization}/{environment}/open
+  https://api.pulumi.com/api/esc/environments/{organization}/{project}/{environment}/open
 ```
 
 #### Default response
@@ -3471,12 +3491,13 @@ Status: 200 OK
 ### Read Open Environment
 
 ```
-GET /api/preview/environments/{organization}/{environment}/open/{openSessionID}
+GET /api/esc/environments/{organization}/{project}/{environment}/open/{openSessionID}
 ```
 
 | Parameter           | Type   | In    | Description       |
 |---------------------|--------|-------|-------------------|
 | `organization`      | string | path  | organization name |
+| `project`           | string | path  | project name      |
 | `environment`       | string | path  | environment name  |
 | `openSessionID`     | string | path  | open session id   |
 | `property`          | string | query | **Optional.** path to a specific property |
@@ -3489,7 +3510,7 @@ curl \
   -H "Content-Type: application/json" \
   -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
   --request GET \
-  https://api.pulumi.com/api/preview/environments/{organization}/{environment}/open/{openSessionID}
+  https://api.pulumi.com/api/esc/environments/{organization}/{project}/{environment}/open/{openSessionID}
 ```
 
 #### Default response

diff --git a/content/docs/pulumi-cloud/oidc/provider/_index.md b/content/docs/pulumi-cloud/oidc/provider/_index.md
@@ -69,7 +69,7 @@ Valid custom claims for this service are listed in the table below:
 
 The default format of the subject claim for this service is:
 
-`pulumi:environments:org:<organization name>:env:<environment name>`
+`pulumi:environments:org:<organization name>:env:<project name>/<environment name>`
 
 If you want to have granular permissions, then we recommend using `subjectAttributes` property to customize the OIDC subject claims if you plan to use subject claims in your cloud provider trust policy. The default prefix when using `subjectAttributes` will be
 
@@ -82,34 +82,34 @@ Additional options for customization include:
 * `pulumi.user.login`: the login identifier of the user opening the environment
 * `pulumi.organization.login`: the login identifier of the organization
 
-Let's explain how `rootEnvironment.name` and `currentEnvironment.name` work with an example. Consider the following definitions for two environments, `Environment-A` and `Environment-B`:
+Let's explain how `rootEnvironment.name` and `currentEnvironment.name` work with an example. Consider the following definitions for two environments, `Project/Environment-A` and `Project/Environment-B`:
 
 ```yaml
-#Environment-A
+#Project/Environment-A
 values:
   enva-rootEnv: ${context.rootEnvironment.name}
   enva-currentEnv: ${context.currentEnvironment.name}
 
-#Environment-B
+#Project/Environment-B
 imports:
-- EnvironmentA
+- Project/EnvironmentA
 values:
   envb-rootEnv: ${context.rootEnvironment.name}
   envb-currentEnv: ${context.currentEnvironment.name}
 ```
 
-If you open `Environment-B`, the output would be:
+If you open `Project/Environment-B`, the output would be:
 
 ```
 {
-  "enva-currentEnv-name": "Environment-A",
-  "enva-rootEnv-name": "Environment-B",
-  "envb-currentEnv": "Environment-B",
-  "envb-rootEnv": "Environment-B"
+  "enva-currentEnv-name": "Project/Environment-A",
+  "enva-rootEnv-name": "Project/Environment-B",
+  "envb-currentEnv": "Project/Environment-B",
+  "envb-rootEnv": "Project/Environment-B"
 }
 ```
 
-Notice how `enva-rootEnv-name` is resolved to `Environment-B`. That's because Environment-A is opened from Environment-B which is the root, i.e. the top-level environment to be opened.
+Notice how `enva-rootEnv-name` is resolved to `Project/Environment-B`. That's because Project/Environment-A is opened from Project/Environment-B which is the root, i.e. the top-level environment to be opened.
 
 When importing multiple environments into Pulumi IaC Stack Config, each environment is resolved separately. For example, if you import multiple environments into your Pulumi Stack with `rootEnvironment.name` attribute defined in all of them, then each `rootEnvironment.name` will resolve to the environment name where it is defined.
 

diff --git a/content/docs/pulumi-cloud/oidc/provider/aws.md b/content/docs/pulumi-cloud/oidc/provider/aws.md
@@ -77,7 +77,7 @@ In the following example, the role may only be assumed by stacks within the `Cor
 
 ### Pulumi ESC
 
-Consider the following ESC definition for `development` environment opened by user `personA`:
+Consider the following ESC definition for `project/development` environment opened by user `personA`:
 
 ```yaml
 values:
@@ -91,13 +91,13 @@ values:
             - pulumi.user.login
 ```
 
-The OIDC subject claim for this environment would be `pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:development:pulumi.user.login:personA`. The role may only be assumed by `development` environment and user `personA` within the `contoso` organization:
+The OIDC subject claim for this environment would be `pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:project/development:pulumi.user.login:personA`. The role may only be assumed by `project/development` environment and user `personA` within the `contoso` organization:
 
 ```json
 "Condition": {
   "StringEquals": {
     "api.pulumi.com/oidc:aud": "contoso",
-    "api.pulumi.com/oidc:sub": "pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:development:pulumi.user.login:personA"
+    "api.pulumi.com/oidc:sub": "pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:project/development:pulumi.user.login:personA"
   }
 }
 ```
@@ -111,7 +111,7 @@ The subject always contains the prefix `pulumi:environments:pulumi.organization.
 
 When importing multiple environments into Pulumi IaC Stack Config, each environment is resolved separately. For example, if you import multiple environments into your Pulumi Stack with `rootEnvironment.name` attribute defined in all of them, then each `rootEnvironment.name` will resolve to the environment name where it is defined.
 
-The default format of the subject claim when subjectAttributes are not used is `pulumi:environments:org:<organization name>:env:<environment name>`
+The default format of the subject claim when subjectAttributes are not used is `pulumi:environments:org:<organization name>:env:<project name>/<environment name>`
 
 {{< notes type="info" >}}
 
@@ -145,7 +145,7 @@ To configure OIDC for Pulumi ESC, create a new environment in the [Pulumi Consol
 
 1. Click the **Environments** link.
 2. Click the **Create environment** button.
-3. Provide a name for your environment.
+3. Provide a project to create your new environment in and a name for your environment.
 4. Click the  **Create environment** button.
   {{< video title="Creating a new Pulumi ESC environment" src="https://www.pulumi.com/uploads/create-new-environment.mp4" autoplay="true" loop="true" >}}
 5. You will be presented with a split-pane editor view. Delete the default placeholder content in the editor and replace it with the following code:
@@ -175,10 +175,10 @@ To configure OIDC for Pulumi ESC, create a new environment in the [Pulumi Consol
 
 You can validate that your configuration is working by running either of the following:
 
-* `esc open <your-org>/<your-environment>` command of the [ESC CLI](/docs/esc-cli/)
-* `pulumi env open <your-org>/<your-environment>` command of the [Pulumi CLI](/docs/install/)
+* `esc open <your-org>/<your-project>/<your-environment>` command of the [ESC CLI](/docs/esc-cli/)
+* `pulumi env open <your-org>/<your-project>/<your-environment>` command of the [Pulumi CLI](/docs/install/)
 
-Make sure to replace `<your-org>` and `<your-environment>` with the values of your Pulumi organization and environment file respectively. You should see output similar to the following:
+Make sure to replace `<your-org>`, `<your-project>`, and `<your-environment>` with the values of your Pulumi organization, project, and environment file respectively. You should see output similar to the following:
 
 ```bash
 {

diff --git a/content/docs/pulumi-cloud/oidc/provider/azure.md b/content/docs/pulumi-cloud/oidc/provider/azure.md
@@ -76,9 +76,9 @@ Because Azure's federated credentials require that the subject identifier exactl
 
 #### Pulumi ESC
 
-The below is an example of a valid subject claim for the `development` environment of the `contoso` organization:
+The below is an example of a valid subject claim for the `project/development` environment of the `contoso` organization:
 
-* `pulumi:environments:org:contoso:env:development`
+* `pulumi:environments:org:contoso:env:project/development`
 
 {{< notes type="warning" >}}
 
@@ -110,7 +110,7 @@ values:
           - pulumi.user.login
 ```
 
-The subject will be `pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:development:pulumi.user.login:userLogin`. Note how the keys and values are appended along with the prefix.
+The subject will be `pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:project/development:pulumi.user.login:userLogin`. Note how the keys and values are appended along with the prefix.
 
 ## Create a Service Principal
 
@@ -150,8 +150,8 @@ To configure OIDC for Pulumi ESC, create a new environment in the [Pulumi Consol
 
 1. Click the **Environments** link.
 2. Click the **Create environment** button.
-3. Provide a name for your environment.
-    * This should be the same as the name provided in the subject claim of your federated credentials.
+3. Provide a project to create your new environment in and a name for your environment.
+    * This should be the same as the identifier provided in the subject claim of your federated credentials.
 4. Click the  **Create environment** button.
   {{< video title="Creating a new Pulumi ESC environment" src="https://www.pulumi.com/uploads/create-new-environment.mp4" autoplay="true" loop="true" >}}
 5. You will be presented with a split-pane editor view. Delete the default placeholder content in the editor and replace it with the following code:
@@ -178,10 +178,10 @@ To configure OIDC for Pulumi ESC, create a new environment in the [Pulumi Consol
 
 You can validate that your configuration is working by running either of the following:
 
-* `esc open <your-org>/<your-environment>` command of the [ESC CLI](/docs/esc-cli/)
-* `pulumi env open <your-org>/<your-environment>` command of the [Pulumi CLI](/docs/install/)
+* `esc open <your-org>/<your-project>/<your-environment>` command of the [ESC CLI](/docs/esc-cli/)
+* `pulumi env open <your-org>/<your-project>/<your-environment>` command of the [Pulumi CLI](/docs/install/)
 
-Make sure to replace `<your-org>` and `<your-environment>` with the values of your Pulumi organization and environment file respectively. You should see output similar to the following:
+Make sure to replace `<your-org>`, `<your-project>`, and `<your-environment>` with the values of your Pulumi organization, project, and environment file respectively. You should see output similar to the following:
 
 ```bash
 {

diff --git a/content/docs/pulumi-cloud/oidc/provider/gcp.md b/content/docs/pulumi-cloud/oidc/provider/gcp.md
@@ -83,9 +83,9 @@ For example, to enable all of the valid operations on a stack named `dev` of the
 
 #### Pulumi ESC
 
-The below is an example of a valid subject claim for the `development` environment of the `contoso` organization:
+The below is an example of a valid subject claim for the `project/development` environment of the `contoso` organization:
 
-* `pulumi:environments:org:contoso:env:development`
+* `pulumi:environments:org:contoso:env:project/development`
 
 You can learn more about setting up OIDC for Pulumi ESC by referring to the [relevant Pulumi documentation](/docs/pulumi-cloud/esc/providers/#setting-up-oidc).
 
@@ -120,7 +120,7 @@ values:
             - pulumi.user.login
 ```
 
-The subject will be `pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:development:pulumi.user.login:userLogin`. Note how the keys and values are appended along with the prefix.
+The subject will be `pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:project/development:pulumi.user.login:userLogin`. Note how the keys and values are appended along with the prefix.
 
 ## Configure OIDC in the Pulumi Console
 
@@ -148,8 +148,8 @@ To configure OIDC for Pulumi ESC, create a new environment in the [Pulumi Consol
 
 1. Click the **Environments** link.
 2. Click the **Create environment** button.
-3. Provide a name for your environment.
-    * This should be the same as the name provided in the subject claim in the previous steps.
+3. Provide a project to create your new environment in and a name for your environment.
+    * This should be the same as the identifier provided in the subject claim of your federated credentials.
 4. Click the  **Create environment** button.
   {{< video title="Creating a new Pulumi ESC environment" src="https://www.pulumi.com/uploads/create-new-environment.mp4" autoplay="true" loop="true" >}}
 5. You will be presented with a split-pane editor view. Delete the default placeholder content in the editor and replace it with the following code:
@@ -176,10 +176,10 @@ To configure OIDC for Pulumi ESC, create a new environment in the [Pulumi Consol
 
 You can validate that your configuration is working by running either of the following:
 
-* `esc open <your-org>/<your-environment>` command of the [ESC CLI](/docs/esc-cli/)
-* `pulumi env open <your-org>/<your-environment>` command of the [Pulumi CLI](/docs/install/)
+* `esc open <your-org>/<your-project>/<your-environment>` command of the [ESC CLI](/docs/esc-cli/)
+* `pulumi env open <your-org>/<your-project>/<your-environment>` command of the [Pulumi CLI](/docs/install/)
 
-Make sure to replace `<your-org>` and `<your-environment>` with the values of your Pulumi organization and environment file respectively. You should see output similar to the following:
+Make sure to replace `<your-org>`, `<your-project>`, and `<your-environment>` with the values of your Pulumi organization, project, and environment file respectively. You should see output similar to the following:
 
 ```bash
 {