Build a minimal template using the Azure Developer CLI compose feature

The Azure Developer CLI (azd) composability (compose) feature enables you to progressively compose the Azure resources required for your app without manually writing Bicep code. In this article, you learn how to work with the compose feature to build a minimal template. Visit the azd compose overview article for more conceptual information about this feature.

Note

The azd compose feature is currently in alpha and shouldn't be used in production apps. Changes to alpha features in subsequent releases can result in breaking changes. Visit the azd feature versioning and release strategy and feature stages pages for more information. Use the Feedback button on the upper right to share feedback about the compose feature and this article.

Work with the compose feature

Access azd compose features through the azd add command. The azd add command works with templates created using the following azd init workflows:

• Use code in the current directory (for apps that target Azure Container Apps for hosting)
• Create a minimal project

Templates initialized through the Select a template flow aren't currently supported. The azd compose feature manages infrastructure for you and isn't compatible with templates that have existing infra folder assets. Visit the Generate the Bicep code article and template creation workflows page for more information.

Complete the following steps to add new resources to your template without writing any code:

1. In a terminal window, navigate to the root of your azd template.

2. Run the azd add command to add a new resource and start the compose workflow:

   azd add
   

3. Select one of the supported resources to add to your app. For this example, select Database.

   ? What would you like to add? [Use arrows to move, type to filter]
   > AI
     Database
     Host service
     Key Vault
     Messaging
     Storage account
     ~Existing resource
   

4. For the type of database, select PostgreSQL.

   ? Which type of database?  [Use arrows to move, type to filter]
     MongoDB
   > PostgreSQL
     Redis
   

5. Enter a name for the new resource, such as azddb.

   ? Input the name of the app database (PostgreSQL)
   

6. If your app contains services, azd prompts you to select the service that uses this resource.

   ? Select the service(s) that uses this resource
   > [✓]  webfrontend
   

7. azd generates a preview of the required changes to the azure.yaml file. Press Enter to accept and apply the changes.

   Previewing changes to azure.yaml:
   
   +  azddata:
   +      type: db.postgres
   
      webfrontend:
          type: host.containerapp
          uses:
              - azddb
   +          - azddata
          port: 80
   

8. Run the azd up command to provision any changes made through the azd add command. In this example, azd provisions a PostgreSQL database in Azure.

9. Run the azd add command again to add other resources, such as an OpenAI service.

Explore the azure.yaml file

azure.yaml is the configuration file that azd uses to manage your app. azd manages the services and resources composed through the azd add command using the corresponding services and resources nodes. Consider the following example of an azure.yaml file updated entirely through azd add:

name: azdcomposesample
metadata:
  template: azd-init@1.11.0
services:
  webfrontend:
    project: src
    host: containerapp
    language: dotnet
resources:
  webfrontend:
    type: host.containerapp
    port: 80
    uses:
      - azdsql
      - azdchat
  azdsql:
    type: db.postgres
  azdchat:
    type: ai.openai.model
    model:
      name: gpt-4o
      version: "2024-08-06"

• The services node declares:
  • A deployment mapping named webfrontend between a .NET web app in the src directory and Azure Container Apps.
• The resources node declares:
  • An Azure container app and a matching dependency mapping named webfrontend between the hosted .NET container app and the database and AI service it depends on. The uses node maps the app to the other resources it depends on.
  • An Azure Database for PostgreSQL resource named azdsql.
  • An Azure OpenAI resource named azdchat.

Next steps

Generate Bicep code using the compose feature