Merge pull request #288231 from RoseHJM/ade-azd-updates

ADE - ADE with azd updates

Author: v-dirichards

articles/deployment-environments/concept-azure-developer-cli-with-deployment-environments.md

@@ -5,7 +5,7 @@ author: RoseHJM
 ms.author: rosemalcolm
 ms.service: azure-deployment-environments
 ms.topic: concept-article
-ms.date: 02/24/2024
+ms.date: 10/11/2024
 
 # Customer intent: As a platform engineer, I want to understand ADE and `azd` work together to provision application infrastructure and deploy application code to the new infrastructure.
 
@@ -15,7 +15,7 @@ ms.date: 02/24/2024
 
 In this article, you learn about Azure Developer CLI (`azd`) and how it works with Azure Deployment Environments (ADE) to provision application infrastructure and deploy application code to the new infrastructure.
 
-The Azure Developer CLI (`azd`) is an open-source command-line tool that provides developer-friendly commands that map to key stages in your workflow. You can install `azd` locally on your machine or use it in other environments.
+`azd` is an open-source command-line tool that provides developer-friendly commands that map to key stages in your workflow. You can install `azd` locally on your machine or use it in other environments.
 
 With ADE, you can create environments from an environment definition in a catalog attached to your dev center. By adding `azd`, you can deploy your application code to the new infrastructure.
 
@@ -31,7 +31,7 @@ At scale, using ADE and `azd` together enables you to provide a way for develope
 
 The Azure Developer CLI commands are designed to work with standardized templates. Each template is a code repository that adheres to specific file and folder conventions. The templates contain the assets `azd` needs to provision an Azure Deployment Environment environment. When you run a command like `azd up`, the tool uses the template assets to execute various workflow steps, such as provisioning or deploying resources to Azure.
 
-The following is a typical template structure:
+The following diagram shows a typical template structure:
 
 ```txt
 ├── infra                                        [ Contains infrastructure as code files ]
@@ -46,7 +46,7 @@ The following is a typical template structure:
 
 All `azd` templates include the following assets:
 
-- *infra folder* - The infra folder is not used in `azd` with ADE. It contains all of the Bicep or Terraform infrastructure as code files for the azd template. ADE provides the infrastructure as code files for the `azd` template. You don't need to include these files in your `azd` template.
+- *infra folder* - The infra folder is not used in `azd` with ADE. It contains all of the Bicep or Terraform infrastructure as code files for the `azd` template. ADE provides the infrastructure as code files for the `azd` template. You don't need to include these files in your `azd` template.
 
 - *azure.yaml file* - A configuration file that defines one or more services in your project and maps them to Azure resources for deployment. For example, you might define an API service and a web front-end service, each with attributes that map them to different Azure resources for deployment.
 
@@ -56,9 +56,9 @@ All `azd` templates include the following assets:
 
 Most `azd` templates also optionally include one or more of the following folders:
 
-- *.devcontainer folder* - Allows you to set up a Dev Container environment for your application. This is a common development environment approach that isn't specific to azd.
+- *.devcontainer folder* - Allows you to set up a Dev Container environment for your application. This common development environment approach that isn't specific to `azd` .
 
-- *.github folder* - Holds the CI/CD workflow files for GitHub Actions, which is the default CI/CD provider for azd.
+- *.github folder* - Holds the CI/CD workflow files for GitHub Actions, which is the default CI/CD provider for `azd` .
 
 - *.azdo folder* - If you decide to use Azure Pipelines for CI/CD, define the workflow configuration files in this folder.
 
@@ -91,7 +91,7 @@ To learn more about how to make your ADE environment definition compatible with
 
 ## Enable `azd` support in ADE
 
-To enable `azd` support with ADE, you need to set the `platform.type` to devcenter. This configuration allows `azd` to leverage new dev center components for remote environment state and provisioning, and means that  the infra folder in your templates will effectively be ignored. Instead, `azd` will use one of the infrastructure templates defined in your dev center catalog for resource provisioning.
+To enable `azd` support with ADE, you need to set the `platform.type` to devcenter. This configuration allows `azd` to use new dev center components for remote environment state and provisioning, and means that  the infra folder in your templates is ignored. Instead, `azd` uses one of the infrastructure templates defined in your dev center catalog for resource provisioning.
 
 To enable `azd` support, run the following command:
 
@@ -100,7 +100,7 @@ To enable `azd` support, run the following command:
    ```
 ### Explore `azd` commands
 
-When the dev center feature is enabled, the default behavior of some common azd commands changes to work with these remote environments. For more information, see [Work with Azure Deployment Environments](/azure/developer/azure-developer-cli/ade-integration?branch=main#work-with-azure-deployment-evironments).
+When the dev center feature is enabled, the default behavior of some common `azd` commands changes to work with these remote environments. For more information, see [Work with Azure Deployment Environments](/azure/developer/azure-developer-cli/ade-integration?branch=main#work-with-azure-deployment-evironments).
 
 
 ## Related content

articles/deployment-environments/how-to-configure-azure-developer-cli-deployment-environments.md

@@ -1,21 +1,21 @@
 ---
-title: Configure Azure Developer CLI templates for use with ADE
-description: Understand how ADE and AZD work together to provision application infrastructure and deploy application code to the new infrastructure.
+title: Create an environment with Azure Developer CLI
+description: Use an `azd` template to provision application infrastructure and deploy application code to the new infrastructure.
 author: RoseHJM
 ms.author: rosemalcolm
 ms.service: azure-deployment-environments
 ms.topic: how-to
-ms.date: 03/26/2024
+ms.date: 10/11/2024
 
-# Customer intent: As a platform engineer, I want to use ADE and AZD together to provision application infrastructure and deploy application code to the new infrastructure.
+# Customer intent: As a developer, I want to use ADE and `azd` together to provision application infrastructure and deploy application code to the new infrastructure.
 
 ---
 
 # Configure Azure Developer CLI with Azure Deployment Environments
 
-In this article, you create a new environment from an existing Azure Developer CLI (AZD) compatible template by using AZD. You learn how to configure Azure Deployment Environments (ADE) and AZD to work together to provision application infrastructure and deploy application code to the new infrastructure.
+In this article, you create a new environment from an existing Azure Developer CLI (`azd`) compatible template by using `azd`. You learn how to configure Azure Deployment Environments (ADE) and `azd` to work together to provision application infrastructure and deploy application code to the new infrastructure.
 
-To learn the key concepts of how AZD and ADE work together, see [Use Azure Developer CLI with Azure Deployment Environments](concept-azure-developer-cli-with-deployment-environments.md).
+To learn the key concepts of how `azd` and ADE work together, see [Use Azure Developer CLI with Azure Deployment Environments](concept-azure-developer-cli-with-deployment-environments.md).
 
 ## Prerequisites
 
@@ -24,13 +24,13 @@ To learn the key concepts of how AZD and ADE work together, see [Use Azure Devel
 
 ## Attach Microsoft quick start catalog
 
-Microsoft provides a quick start catalog that contains a set of AZD compatible templates that you can use to create environments. You can attach the quick start catalog to your dev center at creation or add it later. The quick start catalog contains a set of templates that you can use to create environments.
+Microsoft provides a quick start catalog that contains a set of `azd` compatible templates that you can use to create environments. You can attach the quick start catalog to your dev center at creation or add it later. The quick start catalog contains a set of templates that you can use to create environments.
 
-## Examine an AZD compatible template
+## Examine an `azd` compatible template
 
-You can use an existing AZD compatible template to create a new environment, or you can add an azure.yaml file to your repository. In this section, you examine an existing AZD compatible template.
+You can use an existing `azd` compatible template to create a new environment, or you can add an azure.yaml file to your repository. In this section, you examine an existing `azd` compatible template.
 
-AZD provisioning for environments relies on curated templates from the catalog. Templates in the catalog might assign tags to provisioned Azure resources for you to associate your app services with in the azure.yaml file, or specify the resources explicitly. In this example, resources are specified explicitly.
+`azd` provisioning for environments relies on curated templates from the catalog. Templates in the catalog might assign tags to provisioned Azure resources for you to associate your app services with in the azure.yaml file, or specify the resources explicitly. In this example, resources are specified explicitly.
 
 For more information on tagging resources, see [Tagging resources for Azure Deployment Environments](/azure/developer/azure-developer-cli/ade-integration#tagging-resources-for-azure-deployment-environments).
 
@@ -55,21 +55,21 @@ For more information on tagging resources, see [Tagging resources for Azure Depl
 1. In the azure.yaml file, in the **services** section, you see the **web** and **API** services that are defined in the template.
 
 > [!NOTE]
-> Not all AZD compatible catalogs use the linked templates structure shown in the example. You can use a single catalog for all your environments by including the azure.yaml file. Using multiple catalogs and code repositories allows you more flexibility in configuring secure access for platform engineers and developers. 
+> Not all `azd` compatible catalogs use the linked templates structure shown in the example. You can use a single catalog for all your environments by including the azure.yaml file. Using multiple catalogs and code repositories allows you more flexibility in configuring secure access for platform engineers and developers. 
 
 If you're working with your own catalog & environment definition, you can create an azure.yaml file in the root of your repository. Use the azure.yaml file to define the services that you want to deploy to the environment.
 
 ## Create an environment from an existing template
 
-Use an existing AZD compatible template to create a new environment.
+Use an existing `azd` compatible template to create a new environment.
 
-### Prepare to work with AZD 
+### Prepare to work with `azd` 
 
-When you work with AZD for the first time, there are some one-time setup tasks you need to complete. These tasks include installing the Azure Developer CLI, signing in to your Azure account, and enabling AZD support for Azure Deployment Environments.
+When you work with `azd` for the first time, there are some one-time setup tasks you need to complete. These tasks include installing the Azure Developer CLI, signing in to your Azure account, and enabling `azd` support for Azure Deployment Environments.
 
-#### Install the Azure Developer CLI extension for Visual Studio Code
+#### Install the Azure Developer CLI extension
 
-When you install AZD, the AZD tools are installed within an AZD scope rather than globally, and are removed if AZD is uninstalled. You can install AZD in Visual Studio Code or from the command line.
+When you install `azd`, the `azd` tools are installed within an `azd` scope rather than globally, and are removed if `azd` is uninstalled. You can install `azd` in Visual Studio Code, from the command line, or in Visual Studio.
 
 # [Visual Studio Code](#tab/visual-studio-code)
 
@@ -89,7 +89,7 @@ powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1'
 
 Access your Azure resources by logging in. When you initiate a log in, a browser window opens and prompts you to log in to Azure. After you sign in, the terminal displays a message that you're signed in to Azure.
 
-Sign in to AZD using the command palette:
+Sign in to `azd` using the command palette:
 
 # [Visual Studio Code](#tab/visual-studio-code)
 
@@ -111,9 +111,9 @@ Sign in to Azure at the CLI using the following command:
 
 ---
 
-#### Enable AZD support for ADE
+#### Enable `azd` support for ADE
 
-When `platform.type` is set to `devcenter`, all AZD remote environment state and provisioning uses dev center components. AZD uses one of the infrastructure templates defined in your dev center catalog for resource provisioning. In this configuration, the *infra* folder in your local templates isn't used. 
+When `platform.type` is set to `devcenter`, all `azd` remote environment state and provisioning uses dev center components. `azd` uses one of the infrastructure templates defined in your dev center catalog for resource provisioning. In this configuration, the *infra* folder in your local templates isn't used. 
 
 # [Visual Studio Code](#tab/visual-studio-code)
 
@@ -128,7 +128,7 @@ When `platform.type` is set to `devcenter`, all AZD remote environment state and
 
 ### Create a new environment
 
-Now you're ready to create an environment to work in. You begin with an existing template. ADE defines the infrastructure for your application, and the AZD template provides sample application code.
+Now you're ready to create an environment to work in. You begin with an existing template. ADE defines the infrastructure for your application, and the `azd` template provides sample application code.
 
 # [Visual Studio Code](#tab/visual-studio-code)
 
@@ -142,7 +142,7 @@ Now you're ready to create an environment to work in. You begin with an existing
 
    :::image type="content" source="media/how-to-configure-azure-developer-cli-deployment-environments/command-palette-functionapp-template.png" alt-text="Screenshot of the Visual Studio Code command palette with a list of templates, Function App highlighted." lightbox="media/how-to-configure-azure-developer-cli-deployment-environments/command-palette-functionapp-template.png":::
 
-1. In the AZD terminal, enter an environment name.
+1. In the `azd` terminal, enter an environment name.
 
    :::image type="content" source="media/how-to-configure-azure-developer-cli-deployment-environments/enter-environment-name.png" alt-text="Screenshot of the Azure Developer terminal, showing prompt for a new environment name." lightbox="media/how-to-configure-azure-developer-cli-deployment-environments/enter-environment-name.png":::
 
@@ -154,14 +154,14 @@ Now you're ready to create an environment to work in. You begin with an existing
 
    :::image type="content" source="media/how-to-configure-azure-developer-cli-deployment-environments/initialize-select-environment-definition.png" alt-text="Screenshot of the Azure Developer terminal, showing prompt to select an environment definition." lightbox="media/how-to-configure-azure-developer-cli-deployment-environments/initialize-select-environment-definition.png":::
 
-   AZD creates the project resources, including an *azure.yaml* file in the root of your project.
+   `azd` creates the project resources, including an *azure.yaml* file in the root of your project.
 
 
 # [Azure Developer CLI](#tab/azure-developer-cli)
 
 1. At the CLI, navigate to an empty folder.
 
-1. To list the templates available, in the AZD terminal, run the following command:
+1. To list the templates available, in the `azd` terminal, run the following command:
 
    ```bash
    azd template list
@@ -176,7 +176,7 @@ Now you're ready to create an environment to work in. You begin with an existing
    ```bash
    azd init
    ```
-1. In the AZD terminal, enter an environment name.
+1. In the `azd` terminal, enter an environment name.
 
    :::image type="content" source="media/how-to-configure-azure-developer-cli-deployment-environments/enter-environment-name.png" alt-text="Screenshot of the Azure Developer terminal, showing prompt for a new environment name." lightbox="media/how-to-configure-azure-developer-cli-deployment-environments/enter-environment-name.png":::
 
@@ -188,13 +188,13 @@ Now you're ready to create an environment to work in. You begin with an existing
 
    :::image type="content" source="media/how-to-configure-azure-developer-cli-deployment-environments/initialize-select-environment-definition.png" alt-text="Screenshot of the Azure Developer terminal, showing prompt to select an environment definition." lightbox="media/how-to-configure-azure-developer-cli-deployment-environments/initialize-select-environment-definition.png":::
 
-   AZD creates the project resources, including an *azure.yaml* file in the root of your project.
+   `azd` creates the project resources, including an *azure.yaml* file in the root of your project.
 
 ---
 
 ## Configure your devcenter 
 
-You can define AZD settings for your dev centers so that you don't need to specify them each time you update an environment. In this example, you define the names of the catalog, dev center, and project that you're using for your environment. 
+You can define `azd` settings for your dev centers so that you don't need to specify them each time you update an environment. In this example, you define the names of the catalog, dev center, and project that you're using for your environment. 
 
 1. In Visual Studio Code, navigate to the *azure.yaml* file in the root of your project.
 
@@ -215,11 +215,11 @@ To learn more about the settings you can configure, see [Configure dev center se
 
 ## Provision your environment
 
-You can use AZD to provision and deploy resources to your deployment environments using commands like `azd up` or `azd provision`. 
+You can use `azd` to provision and deploy resources to your deployment environments using commands like `azd up` or `azd provision`. 
 
 To learn more about provisioning your environment, see [Create an environment by using the Azure Developer CLI](how-to-create-environment-with-azure-developer.md#provision-infrastructure-to-azure-deployment-environment).
 
-To how common AZD commands work with ADE, see [Work with Azure Deployment Environments](/azure/developer/azure-developer-cli/ade-integration?branch=main#work-with-azure-deployment-evironments).
+To how common `azd` commands work with ADE, see [Work with Azure Deployment Environments](/azure/developer/azure-developer-cli/ade-integration?branch=main#work-with-azure-deployment-evironments).
 
 
 ## Related content

articles/deployment-environments/index.yml

@@ -95,3 +95,15 @@ landingContent:
             url: how-to-configure-project-admin.md
           - text: Grant access to create environments
             url: how-to-configure-deployment-environments-user.md
+
+  # Card
+  - title: Use Azure Developer CLI with ADE
+    linkLists:
+      - linkListType: concept
+        links:
+          - text: Use Azure Developer CLI (azd) with ADE
+            url: concept-azure-developer-cli-with-deployment-environments.md
+      - linkListType: how-to-guide
+        links:
+          - text: Create environments with Azure Developer CLI (azd)
+            url: how-to-create-environment-with-azure-developer.md