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
Understand the template architecture
The following diagram gives a quick overview of the process to create an
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
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 the
azure.yamlservice definition file and the
infrafolder 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-quickstart
Open your command line tool of choice to the root directory of the project.
azd initcommand to initialize the template.
When 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:
azure.yamlfile with appropriate service definitions.
infrafolder with infrastructure-as-code files to provision and deploy the project to Azure.
.azurefolder with environment variables set in a
More details on this detection and generation process are provided later in the article.
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 by
azd upcommand to provision and deploy your app to Azure.
When 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.
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:
- Supported databases:
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.
devcontainer.jsonfile inside of the
.devcontainerfolder with the desired configurations. The
azdstarter template provides a sample
devcontainer.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:
.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 your
infrafolder 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 config
Using 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:
- 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
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.