Merge pull request #303189 from v-albemi/congigure-environment-definition

Freshness Edit: Azure Deployment Environments

Author: AnnaMHuff

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

@@ -1,13 +1,13 @@
 ---
-title: Add and configure an environment definition in a catalog
+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 ADE projects. Learn how to reference a container image to deploy your environment.
+description: Learn how to add and configure an environment definition to use in Azure Deployment Environments projects. 
 services: Azure Deployment Environments
 author: RoseHJM
 ms.author: rosemalcolm
 ms.service: azure-deployment-environments
 ms.topic: how-to
-ms.date: 05/03/2024
+ms.date: 07/25/2025
 ms.custom:
   - devdivchpfy22
   - build-2023
@@ -20,7 +20,7 @@ ms.custom:
 
 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 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 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 at least two files:
 
@@ -32,15 +32,15 @@ An environment definition is composed of at least two files:
 
 Your development teams use the environment definitions that you provide in the catalog to deploy environments in Azure.
 
-Microsoft offers a [sample catalog](https://aka.ms/deployment-environments/SampleCatalog) that you can use as your repository. You can also use your own private repository, or you can fork and customize the environment definitions in the sample catalog.
+Microsoft provides a [sample catalog](https://aka.ms/deployment-environments/SampleCatalog) that you can use as your repository. You can also use your own private repository, or you can fork and customize the environment definitions in the sample catalog.
 
 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.
 
 <a name="add-a-new-environment-definition"></a>
 
 ## Add an environment definition
 
-To add an environment definition to a catalog in Azure Deployment Environments (ADE), you first add the files to the repository. You then synchronize the dev center catalog with the updated repository.
+To add an environment definition to a catalog in Deployment Environments, you first add the files to the repository. You then synchronize the dev center catalog with the updated repository.
 
 To add an environment definition:
 
@@ -52,9 +52,9 @@ To add an environment definition:
 
    - An environment as a YAML file.
 
-      The *environment.yaml* file contains metadata related to the IaC template.
+      The environment.yaml file contains metadata related to the IaC template.
 
-       The following script is an example of the contents of an *environment.yaml* file for an ARM template:
+       The following script is an example of the contents of an environment.yaml file for an ARM template:
 
        ```yaml
            name: WebApp
@@ -65,48 +65,47 @@ To add an environment definition:
            templatePath: azuredeploy.json
        ```  
 
-      Use the following table to understand the fields in the *environment.yaml* file:
+      This table describes the fields in the environment.yaml file:
 
       | Field | Description |
       |-------|-------------|
-      | name | The name of the environment definition. |
-      | version | The version of the environment definition. This field is optional. |
-      | summary | A brief description of the environment definition. |
-      | description | A detailed description of the environment definition. |
-      | runner | The IaC framework that the template uses. The value can be `ARM` or `Bicep`. You can also specify a path to a template stored in a container registry. |
-      | templatePath | The path to the IaC template file. |
+      | `name` | The name of the environment definition. |
+      | `version` | The version of the environment definition. This field is optional. |
+      | `summary` | A brief description of the environment definition. |
+      | `description` | A detailed description of the environment definition. |
+      | `runner` | The IaC framework that the template uses. The value can be `ARM` or `Bicep`. You can also specify a path to a template stored in a container registry. |
+      | `templatePath` | The path to the IaC template file. |
 
-      To learn more about the options and data types you can use in *environment.yaml*, see [Parameters and data types in environment.yaml](concept-environment-yaml.md#what-is-environmentyaml).
+      To learn more about the options and data types you can use in environment.yaml, see [Parameters and data types in environment.yaml](concept-environment-yaml.md#what-is-environmentyaml).
 
-1. In your dev center, go to **Catalogs**, select the repository, and then select **Sync**.
+1. In your dev center, under **Environment configuration**, select **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 synchronize 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 a 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.
+Deployment Environments uses container images to define how templates for deployment environments are deployed. Deployment Environments 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. Deployment Environments then uses a standard ARM or Bicep container image to create the deployment environment.
 
-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.
+You can create custom container images for more advanced environment deployments. For example, you can run scripts before or after the deployment. Deployment Environments supports custom container images for environment deployments, which can help deploy IaC frameworks such as Pulumi and Terraform.
 
-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. 
+To get started, you can get sample ARM and Bicep container images via the Microsoft Artifact Registry (also known as the Microsoft Container Registry). 
 
-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)
+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).
 
 ### 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.
 
-| IaC framework | Runner value |
+In the environment.yaml file, the `runner` property specifies the location of the image you want to use. To use the sample image published in the Microsoft Artifact Registry, use the `runner` values listed in the following table.
+
+| 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:
+The following example shows a `runner` property that references the sample Bicep container image:
+
 ```yaml
     name: WebApp
     version: 1.0.0
@@ -118,12 +117,13 @@ The following example shows a runner that references the sample Bicep container
 
 ### Specify a custom container image
 
-To use a custom container image stored in a repository, use the following runner format in the environment.yaml file:
+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:
+Edit the `runner` value to reference your repository and custom image, as shown in this example:
 
 ```yaml
     name: WebApp
@@ -137,17 +137,16 @@ Edit the runner value to reference your repository and custom image, as shown in
 | 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. |
-
+| YOUR_REPOSITORY |	Your repository in that registry. |
+| YOUR_TAG |	A tag, such as a version number. |
 
 ## Specify parameters for an environment definition
 
 You can specify parameters for your environment definitions to allow developers to customize their environments. 
 
-Parameters are defined in the *environment.yaml* file. 
+Parameters are defined in the environment.yaml file. 
 
-The following script is an example of an *environment.yaml* file for an ARM template that includes two parameters; `location` and `name`: 
+The following script is an example of an environment.yaml file for an ARM template that includes two parameters: `location` and `name`. 
 
 ```YAML
 name: WebApp
@@ -164,19 +163,19 @@ parameters:
   required: false
 - id: "name"
   name: "name"
-  description: "Name of the Web App "
+  description: "Name of the web app "
   default: ""
   type: "string"
   required: false
 ```
 
-To learn more about the parameters and their data types that you can use in *environment.yaml*, see [Parameters and data types in environment.yaml](concept-environment-yaml.md#parameters-in-environmentyaml).
+For more information, see [Parameters and data types in environment.yaml](concept-environment-yaml.md#parameters-in-environmentyaml).
 
-Developers can supply values for specific parameters for their environments through the [developer portal](https://devportal.microsoft.com).
+Developers can supply values for specific parameters for their environments via the [developer portal](https://devportal.microsoft.com).
 
-:::image type="content" source="media/configure-environment-definition/parameters.png" alt-text="Screenshot of the developer portal of the developer portal showing the parameters pane." lightbox="media/configure-environment-definition/parameters.png":::
+:::image type="content" source="media/configure-environment-definition/parameters.png" alt-text="Screenshot of the parameters pane in the developer portal.":::
 
-Developers can also supply values for specific parameters for their environments through the CLI.
+Developers can also supply values for specific parameters for their environments via the Azure CLI:
 
 ```azurecli
 az devcenter dev environment create --environment-definition-name
@@ -193,19 +192,19 @@ az devcenter dev environment create --environment-definition-name
                                     [--user-id]
 ```
 
-To learn more about the `az devcenter dev environment create` command, see the [Azure CLI devcenter extension](/cli/azure/devcenter/dev/environment).
+To learn more about the `az devcenter dev environment create` command, see [Azure CLI devcenter extension](/cli/azure/devcenter/dev/environment).
 
 ## Update an environment definition
 
-To modify the configuration of Azure resources in an existing environment definition in Azure Deployment Environments, update the associated template  file in the repository. The change is immediately reflected when you create a new environment by using the specific environment definition. The update also is applied when you redeploy an environment associated with that environment definition.
+To modify the configuration of Azure resources in an existing environment definition in Deployment Environments, update the associated template file in the repository. The change is immediately reflected when you create a new environment by using the specific environment definition. The update is also applied when you redeploy an environment associated with that environment definition.
 
-To update any metadata related to the template, modify *environment.yaml*, and then [update the catalog](how-to-configure-catalog.md#update-a-catalog).
+To update any metadata related to the template, modify environment.yaml, and then [update the catalog](how-to-configure-catalog.md#update-a-catalog).
 
 ## Delete an environment definition
 
-To delete an existing environment definition, in the repository, delete the subfolder that contains the template file and the associated environment YAML file. Then, [update the catalog](how-to-configure-catalog.md#update-a-catalog).
+To delete an environment definition, in the repository, delete the subfolder that contains the template file and the associated environment.yaml file. Then [update the catalog](how-to-configure-catalog.md#update-a-catalog).
 
-After you delete an environment definition, development teams can no longer use the specific environment definition to deploy a new environment. Update the environment definition reference for any existing environments that use the deleted environment definition. If the reference isn't updated and the environment is redeployed, the deployment fails.
+After you delete an environment definition, development teams can no longer use it to deploy a new environment. Update the environment definition reference for any existing environments that use the deleted environment definition. If the reference isn't updated and the environment is redeployed, the deployment fails.
 
 ## Related content