Edit

Add and configure an environment definition in Azure Deployment Environments

  • Article

In Azure Deployment Environments, you can use a catalog to provide your development teams with a curated set of predefined infrastructure as code (IaC) templates called environment definitions.

An environment definition is combined of least two files:

Note

Azure Deployment Environments currently supports only ARM templates.

The IaC template contains the environment definition (template), and the manifest file provides metadata about the template. Your development teams use the environment definitions that you provide in the catalog to deploy environments in Azure.

We offer a sample catalog that you can use as your repository. You also can use your own private repository, or you can fork and customize the environment definitions in the sample catalog.

After you add a catalog to your dev center, the service scans the specified folder path to identify folders that contain an ARM template and an associated manifest 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:

  • Add an environment definition
  • Update an environment definition
  • Delete an environment definition

Add an environment definition

To add an environment definition:

  1. In your repository, create a subfolder in the repository folder path.

  2. Add two files to the new repository subfolder:

    • An ARM template as a JSON file.

      To implement IaC for your Azure solutions, use ARM templates. ARM templates help you define the infrastructure and configuration of your Azure solution and repeatedly deploy it in a consistent state.

      To learn how to get started with ARM templates, see the following articles:

      • Understand the structure and syntax of ARM templates: Describes the structure of an ARM template and the properties that are available in the different sections of a template.
      • Use linked templates: Describes how to use linked templates with the new ARM template relativePath property to easily modularize your templates and share core components between environment definitions.

    • A manifest as a YAML file.

      The manifest.yaml file contains metadata related to the ARM template.

      The following script is an example of the contents of a manifest.yaml file:

          name: WebApp
    version: 1.0.0
    summary: Azure Web App Environment
    description: Deploys a web app in Azure without a datastore
    runner: ARM
    templatePath: azuredeploy.json

      Note

      The version field is optional. Later, the field will be used to support multiple versions of environment definitions.

      Screenshot that shows a folder path with a subfolder that contains an ARM template and a manifest file.

  3. In your dev center, go to Catalogs, select the repository, and then select Sync.

    Screenshot that shows how to sync the catalog.

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.

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 manifest.yaml file. You can use the following options for parameters:

Option Description
ID Enter an ID for the parameter.
name Enter a name for the parameter.
description Enter a description for the parameter.
default Optional. Enter a default value for the parameter. The default value can be overwritten at creation.
type Enter the data type for the parameter.
required Enter true for a value that's required, and false for a value that's not required.

The following script is an example of a manifest.yaml file that includes two parameters; location and name:

name: WebApp
summary: Azure Web App Environment
description: Deploys a web app in Azure without a datastore
runner: ARM
templatePath: azuredeploy.json
parameters:
- id: "location"
  name: "location"
  description: "Location to deploy the environment resources"
  default: "[resourceGroup().location]"
  type: "string"
  required: false
- id: "name"
  name: "name"
  description: "Name of the Web App "
  default: ""
  type: "string"
  required: false

Developers can supply values for specific parameters for their environments through the developer portal.

Screenshot showing the parameters pane.

Developers can also supply values for specific parameters for their environments through the CLI.

az devcenter dev environment create --environment-definition-name
                                    --catalog-name
                                    --dev-center
                                    --environment-name
                                    --environment-type
                                    --project
                                    [--description]
                                    [--no-wait]
                                    [--parameters]
                                    [--tags]
                                    [--user]
                                    [--user-id]

Refer to the Azure CLI devcenter extension for full details of the az devcenter dev environment create command.

Update an environment definition

To modify the configuration of Azure resources in an existing environment definition, update the associated ARM template JSON 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 that's associated with that environment definition.

To update any metadata related to the ARM template, modify manifest.yaml, and then update the catalog.

Delete an environment definition

To delete an existing environment definition, in the repository, delete the subfolder that contains the ARM template JSON file and the associated manifest YAML file. Then, update the 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 were created by using the deleted environment definition. If the reference isn't updated and the environment is redeployed, the deployment fails.

Next steps