Make your project compatible with Azure Developer CLI
Azure Developer CLI (azd) enables developers to scaffold their applications for the cloud using templates hosted on GitHub. Microsoft provides several templates to get you started. In this article, you learn how to make your own application azd compatible.
Understand the template architecture
The following diagram gives a quick overview of the process to create an azd template:
All azd templates have the same file structure, based on azd conventions. The following hierarchy shows the directory structure you'll build in this tutorial.
├── .azdo [ Configures an Azure Pipeline ]
├── .devcontainer [ For DevContainer ]
├── .github [ Configures a GitHub workflow ]
├── .vscode [ VS Code workspace configurations ]
├── .azure [ Stores Azure configurations and environment variables ]
├── infra [ Contains infrastructure as code files ]
│ ├── main.bicep/main.tf [ Main infrastructure file ]
│ ├── main.parameters.json/main.tfvars.json [ Parameters file ]
│ └── core/modules [ Contains reusable Bicep/Terraform modules ]
└── azure.yaml [ Describes the app and type of Azure resources]
Initialize the template
The azd init command is used to initialize your application for provisioning and deploying the app resources on Azure. This command prompts you to choose between two different workflows to initialize a template that are outlined in the following sections.
Use code in the current directory: Select this option to instruct
azdto analyze the code in your directory to identity which technologies it uses, such as the programming language, framework and database system.azdwill then automatically generate template assets for you, such as theazure.yamlservice definition file and theinfrafolder with infrastructure-as-code files.Select a template: Select this option to use an existing template as a starting point. By default,
azdallows you to browse templates from the Awesome AZD gallery, but you can also configure your own template galleries. When you select a template, the assets of that template will be added to your existing project directory.
The details of each of these workflows are outlined in the sections below.
You can follow the steps ahead using your own project. However, if you'd prefer to follow along using a sample application, clone the following starter repo to an empty directory on your computer:
git clone https://github.com/Azure-Samples/msdocs-python-flask-webapp-quickstartOpen your command line tool of choice to the root directory of the project.
Run the
azd initcommand to initialize the template.azd initWhen prompted, select the option to Use code in the current directory.
azdanalyzes the project and provides a summary of the detected services and recommended Azure hosting resources.Select Confirm and continue initializing my app.
azdgenerates the following assets in the project root directory:- An
azure.yamlfile with appropriate service definitions. - An
infrafolder with infrastructure-as-code files to provision and deploy the project to Azure. - A
.azurefolder with environment variables set in a.envfile.
More details on this detection and generation process are provided later in the article.
- An
The generated files work as-is for the provided sample app and may for your own apps as well. If necessary, the generated files can be modified to fit your needs. For example, you may need to further modify the infrastructure-as-code files in the
infrafolder if your app relies on Azure resources beyond those that were identified byazd.Run the
azd upcommand to provision and deploy your app to Azure.azd upWhen prompted, select the desired subscription and location to begin the provisioning and deployment process.
When the process completes, click the link in the
azdoutput to open the app in the browser.
Explore the initialization steps
When you select the Use code in the current directory workflow, the azd init command analyzes your project and autogenerates code based on what it discovers. The sections below explain the details of how this process works and which technologies are currently supported.
Detection
The azd init command detects project files for supported languages located in your project directory and subdirectories. azd will also scan package dependencies to gather information about the web frameworks or databases your app uses. If needed, you can manually add or edit the detected components as presented in the confirmation summary prompt.
The current detection logic is as follows:
- Supported languages:
- Python
- JavaScript/TypeScript
- .NET
- Java
- Supported databases:
- MongoDB
- PostgreSQL
- For Python and JavaScript/TypeScript, web frameworks and databases are automatically detected.
- When a JavaScript/TypeScript project uses a front-end (or client-side) web framework, it is classified as a front-end service. If your service uses a front-end web framework that is currently undetected, you may select JQuery to provide equivalent front-end service classification and behavior.
Generation
After you confirm the detected components, azd init generates the infrastructure-as-code files needed to deploy your application to Azure.
The generation logic is as follows:
- Supported hosts:
- Azure Container Apps.
- For databases, the supported mapping between database technology and service used:
- MongoDB: Azure CosmosDB API for MongoDB
- PostgreSQL: Azure Database for PostgreSQL flexible server
- Redis: Azure Container Apps Redis add-on
- Services using databases will have environment variables that provide connection to the database pre-configured by default.
- When both front-end and back-end services are detected, CORS configuration on the Azure host for back-end services will be updated to allow the default hosting domain of front-end services. This can be modified or removed as necessary in the Infrastructure as Code configuration files.
Add support for dev containers
You can also make your template compatible with development containers and Codespaces. A dev container allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud. (Source: https://containers.dev/)
To add support for dev containers:
Create a .devcontainer folder at the root of your project.
Create a
devcontainer.jsonfile inside of the.devcontainerfolder with the desired configurations. Theazdstarter template provides a sampledevcontainer.jsonfile that you can copy into your project and modify as needed.
Read more about working with dev containers on the Visual Studio Code documentation.
Add support for a CI/CD pipeline
You can also add support for CI/CD in your template using GitHub actions or Azure DevOps using the following steps:
Add a
.githubfolder for GitHub actions or a.adofolder for Azure DevOps to the root of your project.Add a workflow file into the new folder. The
azdstarter template provides a Sample GitHub Actions workflow file and Sample Azure DevOps Pipelines files for each platform that you can copy into your project and modify as needed.You may also need to update the
main.parameters.jsonfile in yourinfrafolder with the required environment variables for your workflow to run.
Configure the CI/CD pipeline
If your template includes support for GitHub Actions or Azure Pipelines, you can configure a CI/CD pipeline using the following steps:
Run the following command to push updates to the repository. The GitHub Actions workflow is triggered because of the update.
azd pipeline configUsing your browser, go to the GitHub repository for your project.
Select Actions to see the workflow running.
Clean up resources
When you no longer need the resources created in this article, run the following command:
azd down
See also
- Create Bicep files with Visual Studio Code for an introduction to working with Bicep files.
- Bicep Samples
- How to decompile Azure Resource Manager templates (ARM templates) to Bicep
- Azure Developer CLI's azure.yaml schema
Request help
For information on how to file a bug, request help, or propose a new feature for the Azure Developer CLI, please visit the troubleshooting and support page.
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for