Tutorial: Deploy an Aspire project using the Azure Developer CLI

• Create an Azure DevOps organization or choose an existing organization
• Create an Azure DevOps Personal Access Token (PAT) and save it for later use. Configure the token with the following permissions:
  • Agent Pools (read, manage)
  • Build (read and execute)
  • Code (full)
  • Project and team (read, write and manage)
  • Release (read, write, execute and manage)
  • Service Connections (read, query and manage)

Create the GitHub repository and pipeline

The Azure Developer CLI enables you to automatically create CI/CD pipelines with the correct configurations and permissions to provision and deploy resources to Azure. azd can also create a GitHub repository for your app if it doesn't exist already.

1. Run the azd pipeline config command to configure your deployment pipeline and securely connect it to Azure:

   azd pipeline config
   

2. Select the subscription to provision and deploy the app resources to.

3. Select the Azure location to use for the resources.

4. When prompted whether to create a new Git repository in the directory, enter y and press Enter.

   Note

   Creating a GitHub repository required you being logged into GitHub. There are a few selections that vary based on your preferences. After logging in, you will be prompted to create a new repository in the current directory.

5. Select Create a new private GitHub repository to configure the git remote.

6. Enter a name of your choice for the new GitHub repository or press enter to use the default name. azd creates a new repository in GitHub and configures it with the necessary secrets required to authenticate to Azure.

   

7. Enter y to proceed when azd prompts you to commit and push your local changes to start the configured pipeline.

Explore the GitHub Actions workflow and deployment

1. Navigate to your new GitHub repository using the link output by azd.

2. Select the Actions tab to view the repository workflows. You should see the new workflow either running or already completed. Select the workflow to view the job steps and details in the logs of the run. For example, you can expand steps such as Deploy application to see the details of the completed action.

   

3. Select Deploy Application to expand the logs for that step. You should see two endpoint urls printed out for the apiservice and webfrontend. Select either of these links to open them in another browser tab and explore the deployed application.

   

Congratulations! You successfully deployed an Aspire project using the Azure Developer CLI and GitHub Actions.

Configure working directory for multi-project solutions

When you add GitHub Actions to an existing multi-project Aspire solution where the AppHost project isn't in the root directory, you might need to configure the working-directory parameter for certain workflow steps. This section explains when and how to make these adjustments.

When working-directory configuration is needed

The azd pipeline config command generates a GitHub Actions workflow that assumes your Aspire AppHost project is in the root directory of your repository. However, in many real-world scenarios, especially when adding Aspire to existing applications, the AppHost project might be in a subdirectory.

For example, if your repository structure looks like this:

└───📂 MyAspireApp
    ├───📂 MyAspireApp.ApiService
    ├───📂 MyAspireApp.AppHost
    │    ├─── MyAspireApp.AppHost.csproj
    │    └─── AppHost.cs
    ├───📂 MyAspireApp.Web
    └─── MyAspireApp.sln

The generated workflow steps for Provision Infrastructure and Deploy Application need to run from the MyAspireApp.AppHost directory, not from the repository root.

Updating the GitHub Actions workflow

After running azd pipeline config, examine the generated workflow file in .github/workflows/azure-dev.yml. Look for steps that run azd commands and add the working-directory parameter as needed.

Here's an example of the original generated steps:

- name: Provision Infrastructure
  run: azd provision --no-prompt
  env:
    AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
    AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
    AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}

- name: Deploy Application
  run: azd deploy --no-prompt
  env:
    AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
    AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
    AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}

Update these steps to include the working-directory parameter:

- name: Provision Infrastructure
  run: azd provision --no-prompt
  working-directory: ./MyAspireApp.AppHost
  env:
    AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
    AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
    AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}

- name: Deploy Application
  run: azd deploy --no-prompt
  working-directory: ./MyAspireApp.AppHost
  env:
    AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
    AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
    AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}

Finding the correct working directory

The working directory should point to the folder containing your Aspire AppHost project (the project that contains the azure.yaml file generated by azd init). You can identify this directory by:

1. Look for the project with the Aspire.AppHost package reference in its .csproj file.
2. Find the directory containing the azure.yaml file.
3. Locate the project referenced in your solution that orchestrates other services.

Create the Azure DevOps repository and pipeline

The Azure Developer CLI enables you to automatically create pipelines with the correct configurations and permissions to provision and deploy resources to Azure. azd can also create an Azure Pipelines repository for your app if it doesn't exist already.

1. Run the azd pipeline config command to configure your deployment pipeline and securely connect it to Azure. Include the --provider azdo option to use Azure Pipelines instead of the default GitHub Actions configuration.

   azd pipeline config --provider azdo
   

   Important

   Before running azd pipeline config, ensure you have successfully run azd init to initialize your project. If you encounter errors like "no project exists" during pipeline execution, see the troubleshooting section for solutions.

2. Select the subscription to provision and deploy the app resources to.

3. Select the Azure location to use for the resources.

4. Paste the Personal Access Token you created earlier.

5. Enter the Azure DevOps Organization name you created or selected.

6. When prompted to create a new repository in the current directory, enter y and press Enter.

7. When prompted to configure the git remote, select Create a new Azure DevOps Project.

8. Enter a unique name of your choice for the new repository, such as aspireazd. azd creates a new repository in Azure Repos and configures it with the necessary secrets required to authenticate to Azure.

   

9. Enter y to proceed when azd prompts you to commit and push your local changes to start the configured pipeline.

Explore the pipeline and deployed app

1. Navigate to your new Azure Pipeline using the status link output by azd.

   

2. Select the completed pipeline run to view the summary.

   

3. Select the job link at the bottom of the view to navigate to the job details.

   

4. The job details page shows the status of all the individual stages. Select Provision Infrastructure to view the logs for that stage, which detail all of the provisioning steps completed by azd. At the bottom of the logs take note of the final status message and link to the provisioned Azure resource group.

5. Select the link at the bottom of the provisioning output logs to navigate to the new Azure resource group.

   

   Note

   You can also navigate directly to your new resource group by searching for it in the Azure Portal. Your resource group name will be the environment name you provided to azd prefixed with rg-.

6. Select the webfrontend container app, which hosts the public facing portion of your site.

7. On the webfrontend details page, select the Application Url link to open your site in the browser.

Congratulations! You successfully deployed an Aspire project using the Azure Developer CLI and Azure Pipelines.

Troubleshoot Azure DevOps pipeline deployment

This section covers common issues you might encounter when deploying Aspire projects using Azure DevOps pipelines.

ERROR: no project exists; to create a new project, run azd init

Problem: During the provisioning step of your Azure DevOps pipeline, you encounter the error message:

ERROR: no project exists; to create a new project, run azd init

Cause: This error occurs because the azd init command generates files (azure.yaml and the .azure folder) that are typically not committed to your repository. When the pipeline runs in a clean environment, these files don't exist, causing azd commands to fail.

Solution: There are several approaches to resolve this issue:

Option 1: Run azd init in your pipeline (Recommended)

Add an azd init step to your Azure DevOps pipeline before the provisioning step. You can use the --from-code and --no-prompt flags to run the command non-interactively:

- task: AzureCLI@2
  displayName: 'Initialize Azure Developer CLI'
  inputs:
    azureSubscription: '$(AZURE_SERVICE_CONNECTION)'
    scriptType: 'bash'
    scriptLocation: 'inlineScript'
    inlineScript: |
      azd init --from-code --no-prompt
      azd env new $(AZURE_ENV_NAME) --location $(AZURE_LOCATION) --subscription $(AZURE_SUBSCRIPTION_ID)

Make sure to define the following variables in your pipeline:

• AZURE_ENV_NAME: Your environment name (for example, dev or prod).
• AZURE_LOCATION: Your Azure region (for example, eastus2).
• AZURE_SUBSCRIPTION_ID: Your Azure subscription ID.

Option 2: Commit required files to your repository

If you prefer to commit the generated files to your repository:

1. Run azd init locally in your project directory.
2. Add the generated azure.yaml file to your repository.
3. Optionally, add the .azure folder to your repository if you want to preserve environment-specific settings.

Option 3: Use azd pipeline config with proper initialization

Ensure that you run azd pipeline config --provider azdo after successfully running azd init locally. This command should set up the pipeline with the correct configuration that handles the initialization automatically.

If you continue to experience issues, verify that:

• Your project structure matches what azd expects for Aspire projects.
• You're running the commands from the correct directory (typically where your .sln file is located).
• Your Azure DevOps service connection has the necessary permissions for provisioning resources.