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:

Diagram of Azure Developer CLI template workflow.

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 azd to analyze the code in your directory to identity which technologies it uses, such as the programming language, framework and database system. azd will then automatically generate template assets for you, such as the azure.yaml service definition file and the infra folder with infrastructure-as-code files.

  • Select a template: Select this option to use an existing template as a starting point. By default, azd allows 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.

  1. 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
    
  2. Open your command line tool of choice to the root directory of the project.

  3. Run the azd init command to initialize the template.

    azd init
    
  4. When prompted, select the option to Use code in the current directory. azd analyzes the project and provides a summary of the detected services and recommended Azure hosting resources.

  5. Select Confirm and continue initializing my app. azd generates the following assets in the project root directory:

    • An azure.yaml file with appropriate service definitions.
    • An infra folder with infrastructure-as-code files to provision and deploy the project to Azure.
    • A .azure folder with environment variables set in a .env file.

    More details on this detection and generation process are provided later in the article.

  6. 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 infra folder if your app relies on Azure resources beyond those that were identified by azd.

  7. Run the azd up command to provision and deploy your app to Azure.

    azd up
    
  8. When prompted, select the desired subscription and location to begin the provisioning and deployment process.

  9. When the process completes, click the link in the azd output 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:

  1. Create a .devcontainer folder at the root of your project.

  2. Create a devcontainer.json file inside of the .devcontainer folder with the desired configurations. The azd starter template provides a sample devcontainer.json file 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:

  1. Add a .github folder for GitHub actions or a .ado folder for Azure DevOps to the root of your project.

  2. Add a workflow file into the new folder. The azd starter 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.

  3. You may also need to update the main.parameters.json file in your infra folder 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:

  1. Run the following command to push updates to the repository. The GitHub Actions workflow is triggered because of the update.

    azd pipeline config    
    
  2. Using your browser, go to the GitHub repository for your project.

  3. 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

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