Add and configure an environment definition in Azure Deployment Environments
An environment definition is combined of least two files:
- An Azure Resource Manager template (ARM template) in JSON file format. For example, azuredeploy.json.
- A manifest YAML file (manifest.yaml).
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:
In your repository, create a subfolder in the repository folder path.
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
relativePathproperty 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
versionfield is optional. Later, the field will be used to support multiple versions of environment definitions.
In your dev center, go to Catalogs, select the repository, and then select Sync.
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:
|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.|
The following script is an example of a manifest.yaml file that includes two parameters;
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.
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.