Merge pull request #274232 from RoseHJM/ade-extensibility-env-def-updates

ADE - Updates to environment definitions how-to.

Author: JamesJBarnett

articles/deployment-environments/configure-environment-definition.md

@@ -1,28 +1,30 @@
 ---
 title: Add and configure an environment definition in a catalog
 titleSuffix: Azure Deployment Environments
-description: Learn how to add and configure an environment definition to use in your Azure Deployment Environments projects.
+description: Learn how to add and configure an environment definition to use in ADE projects. Learn how to reference a container image to deploy your environment.
 services: Azure Deployment Environments
 author: RoseHJM
 ms.author: rosemalcolm
 ms.service: deployment-environments
 ms.topic: how-to
-ms.date: 03/29/2024
+ms.date: 05/03/2024
 ms.custom: devdivchpfy22, build-2023
+
+#customer intent: As a platform engineer, I want to add and configure an environment definition in a catalog so that I can provide my development teams with a curated set of predefined infrastructure as code templates to deploy environments in Azure.
 ---
 
 # Add and configure an environment definition
 
-This guide explains how to add or update an environment definition in an Azure Deployment Environments catalog.
+This article explains how to add, update, or delete an environment definition in an Azure Deployment Environments catalog. It also explains how to reference a container image to deploy your environment.
 
-In Azure Deployment Environments, you can use a [catalog](concept-environments-key-concepts.md#catalogs) to provide your development teams with a curated set of predefined [infrastructure as code (IaC)](/devops/deliver/what-is-infrastructure-as-code) templates called [environment definitions](concept-environments-key-concepts.md#environment-definitions).
+In Azure Deployment Environments, you use a [catalog](concept-environments-key-concepts.md#catalogs) to provide your development teams with a curated set of predefined [infrastructure as code (IaC)](/devops/deliver/what-is-infrastructure-as-code) templates called [environment definitions](concept-environments-key-concepts.md#environment-definitions).
 
-An environment definition is composed of least two files:
+An environment definition is composed of at least two files:
 
 - A template from an IaC framework. For example:
     - An Azure Resource Manager (ARM) template might use a file called *azuredeploy.json*.
-    - A Bicep template might use a file called *azuredeploy.bicep*.
-    - A Terraform template might use a file called *azuredeploy.tf*, or *azuredeploy.tf.json*.
+    - A Bicep template might use a file called *main.bicep*.
+    - A Terraform template might use a file called *azuredeploy.tf*.
 - A configuration file that provides metadata about the template. This file should be named *environment.yaml*.
 
 Your development teams use the environment definitions that you provide in the catalog to deploy environments in Azure.
@@ -31,14 +33,6 @@ Microsoft offers a [sample catalog](https://aka.ms/deployment-environments/Sampl
 
 After you [add a catalog](how-to-configure-catalog.md) to your dev center, the service scans the specified folder path to identify folders that contain a template and an associated environment file. The specified folder path should be a folder that contains subfolders that hold the environment definition files.
 
-In this article, you learn how to:
-
-> [!div class="checklist"]
->
-> - Add an environment definition
-> - Update an environment definition
-> - Delete an environment definition
-
 <a name="add-a-new-environment-definition"></a>
 
 ## Add an environment definition
@@ -83,32 +77,68 @@ To add an environment definition:
 
 1. In your dev center, go to **Catalogs**, select the repository, and then select **Sync**.
 
-    :::image type="content" source="../deployment-environments/media/configure-environment-definition/sync-catalog-list.png" alt-text="Screenshot that shows how to sync the catalog." lightbox="../deployment-environments/media/configure-environment-definition/sync-catalog-list.png":::
+    :::image type="content" source="../deployment-environments/media/configure-environment-definition/sync-catalog-list.png" alt-text="Screenshot that shows how to synchronize the catalog." lightbox="../deployment-environments/media/configure-environment-definition/sync-catalog-list.png":::
+
+The service scans the repository to find new environment definitions. After you synchronize the repository, new environment definitions are available to all projects in the dev center.
+
+## Use container images to deploy environments
+
+ADE uses container images to define how templates for deployment environments are deployed. ADE supports ARM and Bicep natively, so you can configure an environment definition that deploys Azure resources for a deployment environment by adding the template files (azuredeploy.json and environment.yaml) to your catalog. ADE then uses a standard ARM or Bicep container image to create the deployment environment.
 
-The service scans the repository to find new environment definitions. After you sync the repository, new environment definitions are available to all projects in the dev center.
+You can create custom container images for more advanced environment deployments. For example, you can run scripts before or after the deployment. ADE supports custom container images for environment deployments, which can help deploy IaC frameworks such as Pulumi and Terraform.
 
-### Specify a Terraform image
+The ADE team provides sample ARM and Bicep container images accessible through the Microsoft Artifact Registry (also known as the Microsoft Container Registry) to help you get started. 
 
-The ADE extensibility model enables you to use your own custom container image to deploy your preferred choice of IaC framework. You can build and use your own container image to execute deployments using Terraform. Learn how to [Configure a container image to execute deployments with Terraform](https://aka.ms/deployment-environments/container-image-terraform).
+For more information on building a custom container image, see:
+- [Configure a container image to execute deployments](how-to-configure-extensibility-generic-container-image.md)
+- [Configure container image to execute deployments with ARM and Bicep](how-to-configure-extensibility-bicep-container-image.md)
+- [Configure a container image to execute deployments with Terraform](how-to-configure-extensibility-terraform-container-image.md)
 
-When creating environment definitions that use a custom image in their deployment, the runner property provides a link to a container registry where this container image is stored.
+### Specify the ARM or Bicep sample container image
+In the environment.yaml file, the runner property specifies the location of the image you want to use. To use the sample image published on the Microsoft Artifact Registry, use the respective identifiers runner, as listed in the following table.
 
-The runner property specifies the location of the image you want to use. When you're using a Terraform image from a container registry, edit the runner property to specify the location that image, as shown in the following example:
+| IaC framework | Runner value |
+|---------------|--------------|
+| ARM           | ARM |
+| Bicep         | Bicep |
+| Terraform     | No sample image. Use a custom container image instead. |
 
+The following example shows a runner that references the sample Bicep container image:
 ```yaml
-runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"
+    name: WebApp
+    version: 1.0.0
+    summary: Azure Web App Environment
+    description: Deploys a web app in Azure without a datastore
+    runner: Bicep
+    templatePath: azuredeploy.json
 ```
 
-### Specify an ARM or Bicep image
+### Specify a custom container image
 
-The ADE team provides sample ARM and Bicep templates accessible through the Microsoft Artifact registry (also known as the Microsoft Container Registry) to help you get started. When you perform deployments by using ARM or Bicep, you can use the standard image that is published on [Microsoft Artifact Registry](https://mcr.microsoft.com/) (previously known as the Microsoft Container Registry).
+To use a custom container image stored in a repository, use the following runner format in the environment.yaml file:
+```yaml
+runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}”`
+```
+
+Edit the runner value to reference your repository and custom image, as shown in the following example:
 
-To use the sample image published on the Microsoft Artifact Registry, use the respective identifiers `runner: ARM` for ARM and `runner:Bicep` for Bicep deployments.
+```yaml
+    name: WebApp
+    version: 1.0.0
+    summary: Azure Web App Environment
+    description: Deploys a web app in Azure without a datastore
+    runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"
+    templatePath: azuredeploy.json
+```
 
-For more information how to build and utilize ARM or Bicep container images within environment definitions, see [Configure container image to execute deployments with ARM and Bicep](https://aka.ms/deployment-environments/container-image-bicep).
+| Property |	Description |
+|----------|--------------|
+| YOUR_REGISTRY |	The registry that stores the custom image. |
+| YOUR_REPOSITORY |	Your repository on that registry. |
+| YOUR_TAG |	A tag such as a version number. |
 
 
-### Specify parameters for an environment definition
+## Specify parameters for an environment definition
 
 You can specify parameters for your environment definitions to allow developers to customize their environments.