Merge pull request #226783 from RoseHJM/ade-new-quickstart

ADE | Updates to attach catalog workflow

Author: prmerger-automator[bot]

articles/deployment-environments/how-to-configure-catalog.md

@@ -54,13 +54,13 @@ You can choose from two types of repositories:
 
 1. Go to the home page of the GitHub repository that contains the template definitions.
 1. [Get the clone URL](/azure/devops/repos/git/clone#get-the-clone-url-of-a-github-repo).
-1. Copy and save the URL. You'll use it later.
+1. Copy and save the URL. You use it later.
 
 #### Get the clone URL of an Azure DevOps repository
 
 1. Go to the home page of your team collection (for example, `https://contoso-web-team.visualstudio.com`), and then select your project.
 1. [Get the clone URL](/azure/devops/repos/git/clone#get-the-clone-url-of-an-azure-repos-git-repo).
-1. Copy and save the URL. You'll use it later.
+1. Copy and save the URL. You use it later.
 
 ### Create a personal access token
 
@@ -77,17 +77,17 @@ Next, create a personal access token. Depending on the type of repository you us
 1. In the **Expiration** dropdown, select an expiration for your token.
 1. For a private repository, under **Select scopes**, select the **repo** scope.
 1. Select **Generate token**.
-1. Save the generated token. You'll use the token later.
+1. Save the generated token. You use the token later.
 
 #### Create a personal access token in Azure DevOps
 
 1. Go to the home page of your team collection (for example, `https://contoso-web-team.visualstudio.com`), and then select your project.
 1. Create a [personal access token](/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate#create-a-pat).
-1. Save the generated token. You'll use the token later.
+1. Save the generated token. You use the token later.
 
 ### Store the personal access token as a key vault secret
 
-To store the personal access token you generated as a [key vault secret](../key-vault/secrets/about-secrets.md) and copy the secret identifier:
+To store the personal access token, you generated as a [key vault secret](../key-vault/secrets/about-secrets.md) and copy the secret identifier:
 
 1. Create a [key vault](../key-vault/general/quick-create-portal.md#create-a-vault).
 1. Add the personal access token as a [secret to the key vault](../key-vault/secrets/quick-create-portal.md#add-a-secret-to-key-vault).
@@ -105,8 +105,8 @@ To store the personal access token you generated as a [key vault secret](../key-
     | **Name** | Enter a name for the catalog. |
     | **Git clone URI**  | Enter or paste the [clone URL](#get-the-clone-url-for-your-repository) for either your GitHub repository or your Azure DevOps repository.<br/>*Sample Catalog Example:* https://github.com/Azure/deployment-environments.git |
     | **Branch**  | Enter the repository branch to connect to.<br/>*Sample Catalog Example:* main|
-    | **Folder path**  | Enter the folder path relative to the clone URI that contains subfolders with your catalog items. </br> This folder path should be the path to the folder that contains the subfolders with the catalog item manifests, and not the path to the folder with the catalog item manifest itself.<br/>*Sample Catalog Example:* /Environments|
-    | **Secret identifier**| Enter the [secret identifier](#create-a-personal-access-token) that contains your personal access token for the repository.|
+    | **Folder path**  | Enter the folder path relative to the clone URI that contains subfolders with your catalog items. </br> This folder path should be the path to the folder that contains the subfolders with the catalog item manifests, and not the path to the folder with the catalog item manifest itself.<br/>*Sample Catalog Example:* /Environments</br> The folder path can begin with or without a '/'.|
+    | **Secret identifier**| Enter the [secret identifier](#create-a-personal-access-token) that contains your personal access token for the repository.</br>When you copy a Secret Identifier, the connection string includes a version identifier at the end, like this: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a. </br>Removing the version identifier ensures that Deployment Environments fetches the latest version of the secret from the key vault. If your PAT expires, only the key vault needs to be updated. </br> *Example secret identifier: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat*|
 
    :::image type="content" source="media/how-to-configure-catalog/add-catalog-form-inline.png" alt-text="Screenshot that shows how to add a catalog to a dev center." lightbox="media/how-to-configure-catalog/add-catalog-form-expanded.png":::
 
@@ -123,7 +123,7 @@ To sync an updated catalog:
 
 ## Delete a catalog
 
-You can delete a catalog to remove it from the dev center. Any templates in a deleted catalog won't be available to development teams when they deploy new environments. Update the catalog item reference for any existing environments that were created by using the catalog items in the deleted catalog. If the reference isn't updated and the environment is redeployed, the deployment fails.
+You can delete a catalog to remove it from the dev center. Templates in a deleted catalog are not available to development teams when they deploy new environments. Update the catalog item reference for any existing environments that were created by using the catalog items in the deleted catalog. If the reference isn't updated and the environment is redeployed, the deployment fails.
 
 To delete a catalog:
 

articles/deployment-environments/how-to-configure-managed-identity.md

@@ -1,7 +1,7 @@
 ---
 title: Configure a managed identity
 titleSuffix: Azure Deployment Environments
-description: Learn how to configure a managed identity that will be used to deploy environments in your Azure Deployment Environments Preview dev center.
+description: Learn how to configure a managed identity to deploy environments in your Azure Deployment Environments Preview dev center.
 ms.service: deployment-environments
 ms.custom: ignite-2022
 author: RoseHJM
@@ -34,6 +34,8 @@ In Azure Deployment Environments, you can choose between two types of managed id
 
 - **System-assigned identity**: A system-assigned identity is tied either to your dev center or to the project environment type. A system-assigned identity is deleted when the attached resource is deleted. A dev center or a project environment type can have only one system-assigned identity.
 - **User-assigned identity**: A user-assigned identity is a standalone Azure resource that you can assign to your dev center or to a project environment type. For Azure Deployment Environments Preview, a dev center or a project environment type can have only one user-assigned identity.
+ 
+As a security best practice, if you choose to use user-assigned identities, use different identities for your project and your dev center. Project identities should have more limited access to resources compared to a dev center.
 
 > [!NOTE]
 > In Azure Deployment Environments Preview, if you add both a system-assigned identity and a user-assigned identity, only the user-assigned identity is used.
@@ -66,7 +68,7 @@ In Azure Deployment Environments, you can choose between two types of managed id
 
 ## Assign a subscription role assignment to the managed identity
 
-The identity that's attached to the dev center should be assigned the Owner role for all the deployment subscriptions and the Reader role for all subscriptions that contain the relevant project. When a user creates or deploys an environment, the service grants appropriate access to the deployment identity that's attached to a project environment type. The deployment identity uses the access to perform deployments on behalf of the user. You can use the managed identity to empower developers to create environments without granting them access to the subscription.
+The identity that's attached to the dev center should be assigned the Owner role for all the deployment subscriptions and the Reader role for all subscriptions that contain the relevant project. When a user creates or deploys an environment, the service grants appropriate access to the deployment identity that's attached to the project environment type. The deployment identity uses the access to perform deployments on behalf of the user. You can use the managed identity to empower developers to create environments without granting them access to the subscription.
 
 ### Add a role assignment to a system-assigned managed identity
 

articles/deployment-environments/quickstart-create-and-configure-devcenter.md

@@ -7,7 +7,7 @@ ms.author: rosemalcolm
 ms.topic: quickstart
 ms.service: deployment-environments
 ms.custom: ignite-2022
-ms.date: 12/20/2022
+ms.date: 02/08/2023
 ---
 
 # Quickstart: Create and configure a dev center
@@ -47,16 +47,18 @@ To create and configure a Dev center in Azure Deployment Environments by using t
 
     :::image type="content" source="media/quickstart-create-and-configure-devcenter/create-devcenter-review.png" alt-text="Screenshot that shows the Review tab of a dev center to validate the deployment details.":::
 
-1. Confirm that the dev center was successfully created by checking your Azure portal notifications. Then, select **Go to resource**.
+1. You can check the progress of the deployment in your Azure portal notifications. 
 
     :::image type="content" source="media/quickstart-create-and-configure-devcenter/azure-notifications.png" alt-text="Screenshot that shows portal notifications to confirm the creation of a dev center.":::
 
+1. When the creation of the dev center is complete, select **Go to resource**.
+
 1. In **Dev centers**, verify that the dev center appears.
 
     :::image type="content" source="media/quickstart-create-and-configure-devcenter/deployment-environments-devcenter-created.png" alt-text="Screenshot that shows the Dev centers overview, to confirm that the dev center is created.":::
 
 ## Create a Key Vault
-You'll need an Azure Key Vault to store the GitHub personal access token (PAT) that is used to grant Azure access to your GitHub repository. 
+You need an Azure Key Vault to store the GitHub personal access token (PAT) that is used to grant Azure access to your GitHub repository. 
 If you don't have an existing key vault, use the following steps to create one:
 
 1.	Sign in to the [Azure portal](https://portal.azure.com).
@@ -89,7 +91,7 @@ Using an authentication token like a GitHub personal access token (PAT) enables
 
     :::image type="content" source="media/quickstart-create-and-configure-devcenter/github-pat.png" alt-text="Screenshot that shows the GitHub Tokens (classic) option.":::
 
-    Fine grained and classic tokens work with Azure Deployment Environments.
+    Fine-grained and classic tokens work with Azure Deployment Environments. Fine-grained tokens give you more granular control over the repos to which you're allowing access.
 
 1. On the New personal access token (classic) page:
     - In the **Note** box, add a note describing the token’s intended use.
@@ -118,13 +120,13 @@ Using an authentication token like a GitHub personal access token (PAT) enables
     :::image type="content" source="media/quickstart-create-and-configure-devcenter/create-secret-in-key-vault.png" alt-text="Screenshot that shows the Create a secret page with the Name and Secret value text boxes highlighted.":::
 
     - Select **Create**.
-1.	Leave this tab open, you’ll need to come back to the Key Vault later.
+1.	Leave this tab open, you need to come back to the Key Vault later.
 
 ## Attach an identity to the dev center
 
 After you create a dev center, attach an [identity](concept-environments-key-concepts.md#identities) to the dev center. You can attach either a system-assigned managed identity or a user-assigned managed identity. Learn about the two [types of identities](how-to-configure-managed-identity.md#add-a-managed-identity).
 
-In this quickstart, you'll configure a system-assigned managed identity for your dev center. 
+In this quickstart, you configure a system-assigned managed identity for your dev center. 
 
 ## Attach a system-assigned managed identity
 
@@ -139,23 +141,23 @@ To attach a system-assigned managed identity to your dev center:
 1.	In the **Enable system assigned managed identity** dialog, select **Yes**.
 
 ### Assign the system-assigned managed identity access to the key vault secret
-Make sure that the identity has access to the key vault secret that contains the personal access token to access your repository.
+Make sure that the identity has access to the key vault secret that contains the personal access token to access your repository. Key Vaults support two methods of access; Azure role-based access control or Vault access policy. In this quickstart, you use a vault access policy.
 
-Configure a key vault access policy:
+Configure a vault access policy:
 1.	In the Azure portal, go to the key vault that contains the secret with the personal access token.
 2.	In the left menu, select **Access policies**, and then select **Create**.
 3.	In Create an access policy, enter or select the following information:
-    - On the Permissions tab, under **Secret permissions**, select **Select all**, and then select **Next**.
+    - On the Permissions tab, under **Secret permissions**, select **Get**, and then select **Next**.
     - On the Principal tab, select the identity that's attached to the dev center, and then select **Next**.
     - Select **Review + create**, and then select **Create**.
 
 
 ## Add a catalog to the dev center
 Azure Deployment Environments Preview supports attaching Azure DevOps repositories and GitHub repositories. You can store a set of curated IaC templates in a repository. Attaching the repository to a dev center as a catalog gives your development teams access to the templates and enables them to quickly create consistent environments.
 
-In this quickstart, you'll attach a GitHub repository that contains samples created and maintained by the Azure Deployment Environments team.
+In this quickstart, you attach a GitHub repository that contains samples created and maintained by the Azure Deployment Environments team.
 
-To add a catalog to your dev center, you'll first need to gather some information.
+To add a catalog to your dev center, you first need to gather some information.
 
 ### Gather GitHub repo information
 To add a catalog, you must specify the GitHub repo URL, the branch, and the folder that contains your catalog items. You can gather this information before you begin the process of adding the catalog to the dev center, and paste it somewhere accessible, like notepad.
@@ -170,7 +172,7 @@ To add a catalog, you must specify the GitHub repo URL, the branch, and the fold
      :::image type="content" source="media/quickstart-create-and-configure-devcenter/github-info.png" alt-text="Screenshot that shows the GitHub repo with Code, branch, and folder highlighted.":::
 
 ### Gather the secret identifier
-You'll also need the path to the secret you created in the key vault. 
+You also need the path to the secret you created in the key vault. 
 
 1. In the Azure portal, navigate to your key vault.
 1. On the key vault page, from the left menu, select **Secrets**.
@@ -199,8 +201,8 @@ You'll also need the path to the secret you created in the key vault.
     | **Name** | Enter a name for the catalog. |
     | **Git clone URI**  | Enter or paste the clone URL for either your GitHub repository or your Azure DevOps repository.<br/>*Sample Catalog Example:* https://github.com/Azure/deployment-environments.git |
     | **Branch**  | Enter the repository branch to connect to.<br/>*Sample Catalog Example:* main|
-    | **Folder path**  | Enter the folder path relative to the clone URI that contains subfolders with your catalog items. </br>This folder path should be the path to the folder that contains the subfolders with the catalog item manifests, and not the path to the folder with the catalog item manifest itself.<br/>*Sample Catalog Example:* /Environments|
-    | **Secret identifier**| Enter the secret identifier that contains your personal access token for the repository.|
+    | **Folder path**  | Enter the folder path relative to the clone URI that contains subfolders with your catalog items. </br>This folder path should be the path to the folder that contains the subfolders with the catalog item manifests, and not the path to the folder with the catalog item manifest itself.<br/>*Sample Catalog Example:* /Environments </br> The folder path can begin with or without a '/'.|
+    | **Secret identifier**| Enter the secret identifier that contains your personal access token for the repository. When you copy a Secret Identifier, the connection string includes a version identifier at the end, like this: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a. </br>Removing the version identifier ensures that Deployment Environments fetches the latest version of the secret from the key vault. If your PAT expires, only the key vault needs to be updated. </br> *Example secret identifier: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat*|
 
    :::image type="content" source="media/how-to-configure-catalog/add-catalog-form-inline.png" alt-text="Screenshot that shows how to add a catalog to a dev center." lightbox="media/how-to-configure-catalog/add-catalog-form-expanded.png":::
 

articles/deployment-environments/quickstart-create-and-configure-projects.md

@@ -7,7 +7,7 @@ ms.author: rosemalcolm
 ms.service: deployment-environments
 ms.custom: ignite-2022
 ms.topic: quickstart
-ms.date: 10/26/2022
+ms.date: 02/08/2023
 ---
 
 # Quickstart: Create and configure a project
@@ -40,7 +40,7 @@ To create a project in your dev center:
      |----------|-----------|
      |**Subscription**     |Select the subscription in which you want to create the project.       |
      |**Resource group**|Either use an existing resource group or select **Create new** and enter a name for the resource group.   |
-     |**Dev center**|Select a dev center to associate with this project. All settings for the dev center will apply to the project.   |
+     |**Dev center**|Select a dev center to associate with this project. All settings for the dev center apply to the project.   |
      |**Name**|Enter a name for the project.  |
      |**Description** (Optional) |Enter any project-related details.  |
 
@@ -55,9 +55,9 @@ To create a project in your dev center:
     :::image type="content" source="media/quickstart-create-configure-projects/created-project.png" alt-text="Screenshot that shows the project overview pane.":::
 
 ### Assign a managed identity the owner role to the subscription
-Before you can create environment types, you must give the managed identity that represents your dev center access to the subscriptions where you'll configure the [project environment types](concept-environments-key-concepts.md#project-environment-types). 
+Before you can create environment types, you must give the managed identity that represents your dev center access to the subscriptions where you configure the [project environment types](concept-environments-key-concepts.md#project-environment-types). 
 
-In this quickstart you'll assign the Owner role to the system-assigned managed identity that you configured previously: [Attach a system-assigned managed identity](quickstart-create-and-configure-devcenter.md#attach-a-system-assigned-managed-identity).
+In this quickstart you assign the Owner role to the system-assigned managed identity that you configured previously: [Attach a system-assigned managed identity](quickstart-create-and-configure-devcenter.md#attach-a-system-assigned-managed-identity).
 
 1.	Navigate to your dev center.
 1.  On the left menu under Settings, select **Identity**.