Tutorial: Build and deploy your app to Azure Container Apps

This article demonstrates how to build and deploy a microservice to Azure Container Apps from a source repository using your preferred programming language.

This is the first tutorial in the series of articles that walk you through how to use core capabilities within Azure Container Apps. The first step is to create a back end web API service that returns a static collection of music albums.

Note

You can also build and deploy this app using the az containerapp up by following the instructions in the Quickstart: Build and deploy an app to Azure Container Apps from a repository article. The az containerapp up command is a fast and convenient way to build and deploy your app to Azure Container Apps using a single command. However, it doesn't provide the same level of customization for your container app.

The next tutorial in the series will build and deploy the front end web application to Azure Container Apps.

The following screenshot shows the output from the album API deployed in this tutorial.

Prerequisites

To complete this project, you need the following items:

Requirement	Instructions
Azure account	If you don't have one, create an account for free. You need the User Access Administrator or Owner permission on the Azure subscription to proceed. Make sure to use the most restrictive role for your context. See Assign Azure roles using the Azure portal and Azure roles, Microsoft Entra roles, and classic subscription administrator rolesfor details.
GitHub Account	Sign up for free.
git	Install git
Azure CLI	Install the Azure CLI.

Requirement	Instructions
Azure account	If you don't have one, create an account for free. You need the Contributor or Owner permission on the Azure subscription to proceed. Refer to Assign Azure roles using the Azure portal for details.
GitHub Account	Sign up for free.
git	Install git
Azure CLI	Install the Azure CLI.
Docker Desktop	Docker provides installers that configure the Docker environment on macOS, Windows, and Linux. From your command prompt, type docker to ensure Docker is running.

Setup

To sign in to Azure from the CLI, run the following command and follow the prompts to complete the authentication process.

Bash

az login

Azure PowerShell

Connect-AzAccount

To ensure you're running the latest version of the CLI, run the upgrade command.

Bash

az upgrade

Azure PowerShell

Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force

Ignore any warnings about modules currently in use.

Next, install or update the Azure Container Apps extension for the CLI.

If you receive errors about missing parameters when you run az containerapp commands in Azure CLI or cmdlets from the Az.App module in Azure PowerShell, be sure you have the latest version of the Azure Container Apps extension installed.

Bash

az extension add --name containerapp --upgrade

Note

Starting in May 2024, Azure CLI extensions no longer enable preview features by default. To access Container Apps preview features, install the Container Apps extension with --allow-preview true.

az extension add --name containerapp --upgrade --allow-preview true

Azure PowerShell

Install-Module -Name Az.App

Make sure to update the Az.App module to the latest version.

Update-Module -Name Az.App

Now that the current extension or module is installed, register the Microsoft.App and Microsoft.OperationalInsights namespaces.

Bash

az provider register --namespace Microsoft.App

az provider register --namespace Microsoft.OperationalInsights

Azure PowerShell

Register-AzResourceProvider -ProviderNamespace Microsoft.App

Register-AzResourceProvider -ProviderNamespace Microsoft.OperationalInsights

Create environment variables

Now that your Azure CLI setup is complete, you can define the environment variables that are used throughout this article.

Bash

Define the following variables in your bash shell.

RESOURCE_GROUP="album-containerapps"
LOCATION="canadacentral"
ENVIRONMENT="env-album-containerapps"
API_NAME="album-api"
FRONTEND_NAME="album-ui"
GITHUB_USERNAME="<YOUR_GITHUB_USERNAME>"

Before you run this command, make sure to replace <YOUR_GITHUB_USERNAME> with your GitHub username.

Next, define a container registry name unique to you.

ACR_NAME="acaalbums"$GITHUB_USERNAME

Azure PowerShell

Define the following variables in your PowerShell console.

$ResourceGroup = "album-containerapps"
$Location = "canadacentral"
$Environment = "env-album-containerapps"
$APIName="album-api"
$FrontendName="album-ui"
$GITHUB_USERNAME = "<YOUR_GITHUB_USERNAME>"

Before you run this command, make sure to replace <YOUR_GITHUB_USERNAME> with your GitHub username.

Next, define a container registry name unique to you.

$ACRName = "acaalbums"+$GITHUB_USERNAME

Prepare the GitHub repository

Navigate to the repository for your preferred language and fork the repository.

C#

Select the Fork button at the top of the album API repo to fork the repo to your account.

Now you can clone your fork of the sample repository.

Use the following git command to clone your forked repo into the code-to-cloud folder:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-csharp.git code-to-cloud

Go

Select the Fork button at the top of the album API repo to fork the repo to your account.

Now you can clone your fork of the sample repository.

Use the following git command to clone your forked repo into the code-to-cloud folder:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-go.git code-to-cloud

Java

Select the Fork button at the top of the album API repo to fork the repo to your account.

Now you can clone your fork of the sample repository.

Use the following git command to clone your forked repo into the code-to-cloud folder:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-java.git code-to-cloud

Note

The Java sample only supports a Maven build, which results in an executable JAR file. The build uses the default settings, as passing in environment variables is not supported.

JavaScript

Select the Fork button at the top of the album API repo to fork the repo to your account.

Now you can clone your fork of the sample repository.

Use the following git command to clone your forked repo into the code-to-cloud folder:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-javascript.git code-to-cloud

Python

Select the Fork button at the top of the album API repo to fork the repo to your account.

Now you can clone your fork of the sample repository.

Use the following git command to clone your forked repo into the code-to-cloud folder:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-python.git code-to-cloud

Next, change the directory into the root of the cloned repo.

cd code-to-cloud/src

Create an Azure resource group

Create a resource group to organize the services related to your container app deployment.

Bash

az group create \
  --name $RESOURCE_GROUP \
  --location "$LOCATION"

Azure PowerShell

New-AzResourceGroup -Location $Location -Name $ResourceGroupName

Create an Azure Container Registry

1. After the album API container image is built, create an Azure Container Registry (ACR) instance in your resource group to store it.

   Bash

   az acr create \
       --resource-group $RESOURCE_GROUP \
       --location $LOCATION \
       --name $ACR_NAME \
       --sku Basic
   

   Azure PowerShell

   $acr = New-AzContainerRegistry `
       -ResourceGroupName $ResourceGroup `
       -Location $Location `
       -Name $ACRName `
       -Sku Basic
   

2. Your container registry must allow Azure Resource Manager (ARM) audience tokens for authentication in order to use managed identity to pull images.

   Use the following command to check if ARM tokens are allowed to access your Azure Container Registry (ACR).

   Bash

   az acr config authentication-as-arm show --registry "$ACR_NAME"
   

   If ARM tokens are allowed, the command outputs the following.

   {
     "status": "enabled"
   }
   

   If the status is disabled, allow ARM tokens with the following command.

   az acr config authentication-as-arm update --registry "$ACR_NAME" --status enabled
   

   Azure PowerShell

   $acr.AzureAdAuthenticationAsArmPolicyStatus
   

   If the command returns disabled, allow ARM tokens with the following command.

   Update-AzContainerRegistry `
       -ResourceGroupName $acr.ResourceGroupName `
       -Name $acr.Name `
       -AzureAdAuthenticationAsArmPolicyStatus enabled
   

Create a user-assigned managed identity

To avoid using administrative credentials, pull images from private repositories in Microsoft Azure Container Registry using managed identities for authentication. When possible, use a user-assigned managed identity to pull images.

Bash

1. Create a user-assigned managed identity. Before you run the following commands, choose a name for your managed identity and replace the \<PLACEHOLDER\> with the name.

   IDENTITY="<YOUR_IDENTITY_NAME>"
   

   az identity create \
       --name $IDENTITY \
       --resource-group $RESOURCE_GROUP
   

2. Get the identity's resource ID.

   IDENTITY_ID=$(az identity show \
       --name $IDENTITY \
       --resource-group $RESOURCE_GROUP \
       --query id \
       --output tsv)
   

Azure PowerShell

1. Create a user-assigned managed identity. Before you run the following commands, choose a name for your managed identity and replace the \<PLACEHOLDER\> with the name.

   $IdentityName="<YOUR_IDENTITY_NAME>"
   $Identity = New-AzUserAssignedIdentity -ResourceGroupName $ResourceGroup -Name $IdentityName
   

2. Get the identity's resource and principal ID.

   $IdentityId = $Identity.Id
   $PrincipalId = (Get-AzUserAssignedIdentity -Name $IdentityName -ResourceGroupName $ResourceGroup).PrincipalId
   

3. Get the registry's resource ID. Before you run the following command, replace the <placeholders> with the resource group name for your registry.

   $RegistryId = (Get-AzContainerRegistry -ResourceGroupName $ResourceGroup -Name $ACRName).Id
   

4. Create the acrpull role assignment for the identity.

   New-AzRoleAssignment -ObjectId $PrincipalId -Scope $RegistryId -RoleDefinitionName acrpull
   

Build your application

With ACR tasks, you can build and push the docker image for the album API without installing Docker locally.

Build the container with ACR

Run the following command to initiate the image build and push process using ACR. The . at the end of the command represents the docker build context, meaning this command should be run within the src folder where the Dockerfile is located.

Bash

az acr build --registry $ACR_NAME --image $API_NAME .

Azure PowerShell

The az acr build command does not have a PowerShell equivalent, but can be run in PowerShell.

To sign into Azure with the Azure CLI, run the following command and follow the prompts to complete the authentication process.

az login

Then build the container.

az acr build --registry $AcrName --image $APIName .

Output from the az acr build command shows the upload progress of the source code to Azure and the details of the docker build and docker push operations.

Build your application

The following steps show how to build your container image locally using Docker and push the image to the new container registry.

Build the container with Docker

The following command builds a container image for the album API and tags it with the fully qualified name of the ACR login server. The . at the end of the command represents the docker build context, meaning this command should be run within the src folder where the Dockerfile is located.

Bash

docker build --tag $ACR_NAME.azurecr.io/$API_NAME .

Azure PowerShell

docker build --tag "$ACRName.azurecr.io/$APIName" .

Push the image to your container registry

First, sign in to your Azure Container Registry.

Bash

az acr login --name $ACR_NAME

Azure PowerShell

Connect-AzContainerRegistry -Name $ACRName

Now, push the image to your registry.

Bash

docker push $ACR_NAME.azurecr.io/$API_NAME

Azure PowerShell

docker push "$ACRName.azurecr.io/$APIName"

Create a Container Apps environment

The Azure Container Apps environment acts as a secure boundary around a group of container apps.

Create the Container Apps environment using the following command.

Bash

az containerapp env create \
  --name $ENVIRONMENT \
  --resource-group $RESOURCE_GROUP \
  --location "$LOCATION"

Azure PowerShell

A Log Analytics workspace is required for the Container Apps environment. The following commands create a Log Analytics workspace and save the workspace ID and primary shared key to variables.

$WorkspaceArgs = @{
    Name = 'my-album-workspace'
    ResourceGroupName = $ResourceGroup
    Location = $Location
    PublicNetworkAccessForIngestion = 'Enabled'
    PublicNetworkAccessForQuery = 'Enabled'
}
New-AzOperationalInsightsWorkspace @WorkspaceArgs
$WorkspaceId = (Get-AzOperationalInsightsWorkspace -ResourceGroupName $ResourceGroup -Name $WorkspaceArgs.Name).CustomerId
$WorkspaceSharedKey = (Get-AzOperationalInsightsWorkspaceSharedKey -ResourceGroupName $ResourceGroup -Name $WorkspaceArgs.Name).PrimarySharedKey

To create the environment, run the following command:

$EnvArgs = @{
    EnvName = $Environment
    ResourceGroupName = $ResourceGroup
    Location = $Location
    AppLogConfigurationDestination = 'log-analytics'
    LogAnalyticConfigurationCustomerId = $WorkspaceId
    LogAnalyticConfigurationSharedKey = $WorkspaceSharedKey
}

New-AzContainerAppManagedEnv @EnvArgs

Deploy your image to a container app

Now that you have an environment created, you can create and deploy your container app with the az containerapp create command.

Create and deploy your container app with the following command.

Bash

az containerapp create \
  --name $API_NAME \
  --resource-group $RESOURCE_GROUP \
  --environment $ENVIRONMENT \
  --image $ACR_NAME.azurecr.io/$API_NAME \
  --target-port 8080 \
  --ingress external \
  --registry-server $ACR_NAME.azurecr.io \
  --user-assigned "$IDENTITY_ID" \
  --registry-identity "$IDENTITY_ID" \
  --query properties.configuration.ingress.fqdn

• By setting --ingress to external, your container app is accessible from the public internet.

• The target-port is set to 8080 to match the port that the container is listening to for requests.

• Without a query property, the call to az containerapp create returns a JSON response that includes a rich set of details about the application. Adding a query parameter filters the output to just the app's fully qualified domain name (FQDN).

• This command adds the acrPull role to your user-assigned managed identity, so it can pull images from your container registry.

Azure PowerShell

To create the container app, create template objects that you pass in as arguments to the New-AzContainerApp command.

1. Create a template object to define your container image parameters.

   $ImageParams = @{
       Name = $APIName
       Image = $ACRName + '.azurecr.io/' + $APIName + ':latest'
   }
   $TemplateObj = New-AzContainerAppTemplateObject @ImageParams
   

2. Create a registry credential object to define your registry information.

   $RegistryArgs = @{
       Server = $ACRName + '.azurecr.io'
       Identity = $IdentityId
   }
   $RegistryObj = New-AzContainerAppRegistryCredentialObject @RegistryArgs
   

3. Get your environment ID.

   $EnvId = (Get-AzContainerAppManagedEnv -EnvName $Environment -ResourceGroup $ResourceGroup).Id
   

4. Create the container app.

   $AppConfig = @{
       IngressTargetPort = 8080
       IngressExternal = $true
       Registry = $RegistryObj
   }
   $AppConfigObj = New-AzContainerAppConfigurationObject @AppConfig
   
   $AppArgs = @{
       Name = $APIName
       Location = $Location
       ResourceGroupName = $ResourceGroup
       ManagedEnvironmentId = $EnvId
       TemplateContainer = $TemplateObj
       Configuration = $AppConfigObj
       UserAssignedIdentity = @($IdentityId)
   }
   $MyApp = New-AzContainerApp @AppArgs
   
   # Show the app's fully qualified domain name (FQDN).
   $MyApp.LatestRevisionFqdn
   

   • By setting IngressExternal to $true, your container app is accessible from the public internet.
   • The IngressTargetPort parameter is set to 8080 to match the port that the container is listening to for requests.

Verify deployment

Copy the FQDN to a web browser. From your web browser, navigate to the /albums endpoint of the FQDN.

Clean up resources

If you're not going to continue on to the Communication between microservices tutorial, you can remove the Azure resources created during this quickstart. Run the following command to delete the resource group along with all the resources created in this quickstart.

Bash

az group delete --name $RESOURCE_GROUP

Azure PowerShell

Remove-AzResourceGroup -Name $ResourceGroup -Force

Tip

Having issues? Let us know on GitHub by opening an issue in the Azure Container Apps repo.

Next steps

This quickstart is the entrypoint for a set of progressive tutorials that showcase the various features within Azure Container Apps. Continue on to learn how to enable communication from a web front end that calls the API you deployed in this article.

Tutorial: Communication between microservices