|
| 1 | +--- |
| 2 | +title: Use Azure Developer CLI with Azure Deployment Environments |
| 3 | +description: Understand ADE and `azd` work together to provision application infrastructure and deploy application code to the new infrastructure. |
| 4 | +author: RoseHJM |
| 5 | +ms.author: rosemalcolm |
| 6 | +ms.service: dev-box |
| 7 | +ms.topic: concept-article |
| 8 | +ms.date: 02/24/2024 |
| 9 | + |
| 10 | +# Customer intent: As a platform engineer, I want to understand ADE and `azd` work together to provision application infrastructure and deploy application code to the new infrastructure. |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +# Use Azure Developer CLI with Azure Deployment Environments |
| 15 | + |
| 16 | +In this article, you learn about Azure Developer CLI (`azd`) and how it works with Azure Deployment Environments (ADE) to provision application infrastructure and deploy application code to the new infrastructure. |
| 17 | + |
| 18 | +The Azure Developer CLI (`azd`) is an open-source command-line tool that provides developer-friendly commands that map to key stages in your workflow. You can install `azd` locally on your machine or use it in other environments. |
| 19 | + |
| 20 | +With ADE, you can create environments from an environment definition in a catalog attached to your dev center. By adding `azd`, you can deploy your application code to the new infrastructure. |
| 21 | + |
| 22 | +## How does `azd` work with ADE? |
| 23 | + |
| 24 | +`azd` works with ADE to enable you to create environments from where you’re working. |
| 25 | + |
| 26 | +With ADE and `azd`, individual developers working with unique infrastructure and code that they want to upload to the cloud can create an environment from a local folder. They can use `azd` to provision an environment and deploy their code seamlessly. |
| 27 | + |
| 28 | +At scale, using ADE and `azd` together enables you to provide a way for developers to create app infrastructure and code. Your team can create multiple ADE environments from the same `azd` compatible environment definition, and provision code to the cloud in a consistent way. |
| 29 | + |
| 30 | +## Understand `azd` templates |
| 31 | + |
| 32 | +The Azure Developer CLI commands are designed to work with standardized templates. Each template is a code repository that adheres to specific file and folder conventions. The templates contain the assets `azd` needs to provision an Azure Deployment Environment environment. When you run a command like `azd up`, the tool uses the template assets to execute various workflow steps, such as provisioning or deploying resources to Azure. |
| 33 | + |
| 34 | +The following is a typical `azd` template structure: |
| 35 | + |
| 36 | +```txt |
| 37 | +├── infra [ Contains infrastructure as code files ] |
| 38 | +├── .azdo [ Configures an Azure Pipeline ] |
| 39 | +├── .devcontainer [ For DevContainer ] |
| 40 | +├── .github [ Configures a GitHub workflow ] |
| 41 | +├── .vscode [ VS Code workspace configurations ] |
| 42 | +├── .azure [ Stores Azure configurations and environment variables ] |
| 43 | +├── src [ Contains all of the deployable app source code ] |
| 44 | +└── azure.yaml [ Describes the app and type of Azure resources] |
| 45 | +``` |
| 46 | + |
| 47 | +All `azd` templates include the following assets: |
| 48 | + |
| 49 | +- *infra folder* - Contains all of the Bicep or Terraform infrastructure as code files for the azd template. The infra folder is not used in `azd` with ADE. ADE provides the infrastructure as code files for the `azd` template. You don't need to include these files in your `azd` template. |
| 50 | + |
| 51 | +- *azure.yaml file* - A configuration file that defines one or more services in your project and maps them to Azure resources for deployment. For example, you might define an API service and a web front-end service, each with attributes that map them to different Azure resources for deployment. |
| 52 | + |
| 53 | +- *.azure folder* - Contains essential Azure configurations and environment variables, such as the location to deploy resources or other subscription information. |
| 54 | + |
| 55 | +- *src folder* - Contains all of the deployable app source code. Some `azd` templates only provide infrastructure assets and leave the src directory empty for you to add your own application code. |
| 56 | + |
| 57 | +Most `azd` templates also optionally include one or more of the following folders: |
| 58 | + |
| 59 | +- *.devcontainer folder* - Allows you to set up a Dev Container environment for your application. This is a common development environment approach that isn't specific to azd. |
| 60 | + |
| 61 | +- *.github folder* - Holds the CI/CD workflow files for GitHub Actions, which is the default CI/CD provider for azd. |
| 62 | + |
| 63 | +- *.azdo folder* - If you decide to use Azure Pipelines for CI/CD, define the workflow configuration files in this folder. |
| 64 | + |
| 65 | +## `azd` compatible catalogs |
| 66 | + |
| 67 | +Azure Deployment Environments catalogs consist of environment definitions: IaC templates that define the infrastructure resources that are provisioned for a deployment environment. Azure Developer CLI uses environment definitions in the catalog attached to the dev center to provision new environments. |
| 68 | + |
| 69 | +> [!NOTE] |
| 70 | +> Currently, Azure Developer CLI works with ARM templates stored in the Azure Deployment Environments dev center catalog. |
| 71 | +
|
| 72 | +To properly support certain Azure Compute services, Azure Developer CLI requires more configuration settings in the IaC template. For example, you must tag app service hosts with specific information so that `azd` knows how to find the hosts and deploy the app to them. |
| 73 | + |
| 74 | +You can see a list of supported Azure services here: [Supported Azure compute services (host)](/azure/developer/azure-developer-cli/supported-languages-environments#supported-azure-compute-services-host). |
| 75 | + |
| 76 | +## Make your ADE catalog compatible with `azd` |
| 77 | + |
| 78 | +To enable your development teams to us `azd` with ADE, you need to create an environment definition in your catalog that is compatible with `azd`. You can create a new `azd`compatible environment definition, or you can use an existing environment definition from the Azure Deployment Environments dev center catalog. If you choose to use an existing environment definition, you need to make a few changes to make it compatible with `azd`. |
| 79 | + |
| 80 | +Changes include: |
| 81 | +- If you're modifying an existing `azd` template, remove the `infra` folder. ADE uses the following files to create the infrastructure: |
| 82 | + - ARM template (azuredeploy.json.) |
| 83 | + - Configuration file that defines parameters (environment.yaml or manifest.yaml) |
| 84 | +- Tag resources in *azure.yaml* with specific information so that `azd` knows how to find the hosts and deploy the app to them. |
| 85 | + - Learn about [Tagging resources for Azure Deployment Environments](/azure/developer/azure-developer-cli/ade-integration?branch=main#tagging-resources-for-azure-deployment-environments). |
| 86 | + - Learn about [Azure Developer CLI's azure.yaml schema](/azure/developer/azure-developer-cli/azd-schema). |
| 87 | +- Configure dev center settings like environment variables, `azd` environment configuration, `azd` project configuration, and user configuration. |
| 88 | + - Learn about [Configuring dev center settings](/azure/developer/azure-developer-cli/ade-integration?branch=main#configure-dev-center-settings). |
| 89 | + |
| 90 | +To learn more about how to make your ADE environment definition compatible with `azd`, see [Make your project compatible with Azure Developer CLI](/azure/developer/azure-developer-cli/ade-integration). |
| 91 | + |
| 92 | +## Enable `azd` support in ADE |
| 93 | + |
| 94 | +To enable `azd` support with ADE, you need to set the `platform.type` to devcenter. This configuration allows `azd` to leverage new dev center components for remote environment state and provisioning, and means that the infra folder in your templates will effectively be ignored. Instead, `azd` will use one of the infrastructure templates defined in your dev center catalog for resource provisioning. |
| 95 | + |
| 96 | +To enable `azd` support, run the following command: |
| 97 | + |
| 98 | + ```bash |
| 99 | + azd config set platform.type devcenter |
| 100 | + ``` |
| 101 | +### Explore `azd` commands |
| 102 | + |
| 103 | +When the dev center feature is enabled, the default behavior of some common azd commands changes to work with these remote environments. For more information, see [Work with Azure Deployment Environments](/azure/developer/azure-developer-cli/ade-integration?branch=main#work-with-azure-deployment-evironments). |
| 104 | + |
| 105 | + |
| 106 | +## Related content |
| 107 | + |
| 108 | +- [Add and configure an environment definition](./configure-environment-definition.md) |
| 109 | +- [Create an environment by using the Azure Developer CLI](./how-to-create-environment-with-azure-developer.md) |
| 110 | +- [Make your project compatible with Azure Developer CLI](/azure/developer/azure-developer-cli/make-azd-compatible?pivots=azd-create) |
0 commit comments