Add and configure a catalog item

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

A catalog item is combined of least two files:


Azure Deployment Environments Preview 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 catalog items 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 catalog items 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 catalog item files.

In this article, you learn how to:

  • Add a catalog item
  • Update a catalog item
  • Delete a catalog item


Azure Deployment Environments currently is in preview. For legal terms that apply to Azure features that are in beta, in preview, or otherwise are not yet released into general availability, see the Supplemental Terms of Use for Microsoft Azure Previews.

Add a catalog item

To add a catalog item:

  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 catalog items.
    • 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


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

      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 catalog items. After you sync the repository, new catalog items are available to all projects in the dev center.

Update a catalog item

To modify the configuration of Azure resources in an existing catalog item, 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 catalog item. The update also is applied when you redeploy an environment that's associated with that catalog item.

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

Delete a catalog item

To delete an existing catalog item, 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 a catalog item, development teams can no longer use the specific catalog item to deploy a new environment. Update the catalog item reference for any existing environments that were created by using the deleted catalog item. If the reference isn't updated and the environment is redeployed, the deployment fails.

Next steps