Proposed Pull Request Change

📄 Document Links

View on GitHub View on Microsoft Learn

--- title: Kubernetes on Azure tutorial - Create an Azure Container Registry and build images description: In this Azure Kubernetes Service (AKS) tutorial, you create an Azure Container Registry instance and upload sample application container images. ms.topic: tutorial ms.date: 04/07/2026 author: davidsmatlak ms.author: davidsmatlak ms.custom: mvc, devx-track-azurecli, devx-track-azurepowershell, aks-getting-started # Customer intent: As a developer, I want to learn how to create and use a container registry so that I can deploy my own applications to Azure Kubernetes Service. --- # Tutorial - Create an Azure Container Registry (ACR) and build images Azure Container Registry (ACR) is a private registry for container images. A private container registry allows you to securely build and deploy your applications and custom code. In this tutorial, you deploy an ACR instance and push a container image to it. You learn how to: > [!div class="checklist"] > > - Create an ACR instance. > - Use [ACR Tasks][acr-tasks] to build and push container images to ACR. > - View images in your registry. ## Before you begin In the [previous tutorial][aks-tutorial-prepare-app], you cloned the application code repository and used Docker to create a container image for a simple Azure Store Front application. If you didn't create the Azure Store Front app image, return to [Tutorial 1 - Prepare an application for AKS][aks-tutorial-prepare-app]. This tutorial creates billable Azure resources, including a resource group and an Azure Container Registry. To complete these steps, you need permissions to create resource groups and Azure Container Registry resources in your subscription, such as **Contributor** or **Owner**. ### [Azure CLI](#tab/azure-cli) This tutorial requires Azure CLI version 2.0.53 or later. To find the version, run the `az --version` command. If you need to install or upgrade, see [Install Azure CLI][azure-cli-install]. ### [Azure PowerShell](#tab/azure-powershell) This tutorial requires Azure PowerShell version 5.9.0 or later. To find the version, run the `Get-InstalledModule -Name Az` command. If you need to install or upgrade, see [Install Azure PowerShell][azure-powershell-install]. --- ## Create an Azure Container Registry Before creating an ACR instance, you need a resource group. An Azure resource group is a logical container into which you deploy and manage Azure resources. ### [Azure CLI](#tab/azure-cli) 1. Create variables for the resource group name, location, and registry name. You can use these values or create your own. The registry name variable's value stored in `ACRNAME` must be unique within Azure and contain 5-50 lowercase alphanumeric characters. ```azurecli-interactive export RESOURCE_GROUP=myResourceGroup export LOCATION=westus2 export RANDOM_STRING=$(printf '%05d%05d' "$RANDOM" "$RANDOM") export ACRNAME="myregistry${RANDOM_STRING}" ``` The registry name variable's value stored in `ACRNAME` must be unique within Azure and contain 5-50 lowercase alphanumeric characters. The `ACRNAME` value is concatenated with the `RANDOM_STRING` variable that stores a random 10-digit string to ensure the registry name is unique. The variable `RESOURCE_GROUP` with the value _myResourceGroup_ for the resource group and `LOCATION` with the value _westus2_. You can use these values or create your own. 1. Create a resource group using the [`az group create`][az-group-create] command. ```azurecli-interactive az group create --name $RESOURCE_GROUP --location $LOCATION ``` 1. Create an ACR instance by using the [`New-AzContainerRegistry`][new-azcontainerregistry] cmdlet and provide your own unique registry name. The _Basic_ SKU is a cost-optimized entry point for development purposes that provides a balance of storage and throughput. ```azurecli-interactive az group show --name $RESOURCE_GROUP --query name --output tsv ``` 1. Create an ACR instance using the [`az acr create`][az-acr-create] command and provide your own unique registry name. The _Basic_ SKU is a cost-optimized entry point for development purposes that provides a balance of storage and throughput. ```azurecli-interactive az acr create \ --resource-group $RESOURCE_GROUP \ --location $LOCATION \ --name $ACRNAME \ --sku Basic ``` Verify that the registry provisioning state is `Succeeded` before continuing: ```azurecli-interactive az acr show --name $ACRNAME --resource-group $RESOURCE_GROUP --query provisioningState --output tsv ``` ### [Azure PowerShell](#tab/azure-powershell) 1. Create variables for the resource group name, location, and registry name. You can use these values or create your own. The registry name variable's value stored in `ACRNAME` must be unique within Azure and contain 5-50 lowercase alphanumeric characters. ```azurepowershell-interactive $RESOURCE_GROUP="myResourceGroup" $LOCATION="westus2" $randobj=New-Object System.Random $RAND=$randobj.Next() $ACRNAME="myregistry$RAND" ``` The registry name variable's value stored in `ACRNAME` must be unique within Azure and contain 5-50 lowercase alphanumeric characters. The `ACRNAME` value is concatenated with the `RAND` variable that stores a random 10-digit string to ensure the registry name is unique. The variable `RESOURCE_GROUP` with the value _myResourceGroup_ for the resource group and `LOCATION` with the value _westus2_. You can use these values or create your own. 1. Create a resource group using the [`New-AzResourceGroup`][new-azresourcegroup] cmdlet. ```azurepowershell-interactive New-AzResourceGroup -Name $RESOURCE_GROUP -Location $LOCATION ``` Verify that the resource group was created before continuing: ```azurepowershell-interactive Get-AzResourceGroup -Name $RESOURCE_GROUP | Select-Object -ExpandProperty ResourceGroupName ``` 1. Create an ACR instance using the [`New-AzContainerRegistry`][new-azcontainerregistry] cmdlet and provide your own unique registry name. The _Basic_ SKU is a cost-optimized entry point for development purposes that provides a balance of storage and throughput. ```azurepowershell-interactive New-AzContainerRegistry -ResourceGroupName $RESOURCE_GROUP -Name $ACRNAME -Location $LOCATION -Sku Basic ``` Verify that the registry provisioning state is `Succeeded` before continuing: ```azurepowershell-interactive Get-AzContainerRegistry -ResourceGroupName $RESOURCE_GROUP -Name $ACRNAME | Select-Object -ExpandProperty ProvisioningState ``` --- ## Build and push container images to registry Build and push the images to your ACR using the Azure CLI [`az acr build`][az-acr-build] command. The `az acr build` commands use images in the repository you cloned in the previous article [prepare an app for AKS](tutorial-kubernetes-prepare-app.md). Make sure you switch to that directory or the `build` commands fail. For example, if you created directory _demorepo_ and cloned the repository, the repository's root directory is _aks-store-demo_, so switch to the _demorepo/aks-store-demo_ directory. Before running the build commands, verify that your current directory contains the expected service folders: ```azurecli-interactive ls ./src/order-service ./src/store-front ``` There isn't an equivalent Azure PowerShell cmdlet that builds or pushes container images to the registry. You need to use the steps for Azure CLI, but with the `ACRNAME` variable set to the value you created in PowerShell. In PowerShell you can get the value with the command `$ACRNAME`. In the following example, we don't build the `product-service` image. This image can take a long time to build, and there's a container image already available in the GitHub Container Registry (GHCR). You can use the [`az acr import`][az-acr-import] command to import the image from the GHCR to your ACR instance. We also don't build the `rabbitmq` image. This image is available from the Docker Hub public repository and doesn't need to be built or pushed to your ACR instance. ```azurecli-interactive az acr import \ --name $ACRNAME \ --source ghcr.io/azure-samples/aks-store-demo/product-service:latest \ --image aks-store-demo/product-service:1.0 az acr build \ --registry $ACRNAME \ --image aks-store-demo/order-service:1.0 ./src/order-service/ az acr build \ --registry $ACRNAME \ --image aks-store-demo/store-front:1.0 ./src/store-front/ ``` If you get an authorization error, run `az login`, confirm the active subscription with `az account show`, and then rerun the failed command. ## List images in registry ### [Azure CLI](#tab/azure-cli) View the images in your ACR instance using the [`az acr repository list`][az-acr-repository-list] command. ```azurecli-interactive az acr repository list --name $ACRNAME --output table ``` The following example output lists the available images in your registry: ```output Result ---------------- aks-store-demo/product-service aks-store-demo/order-service aks-store-demo/store-front ``` ### [Azure PowerShell](#tab/azure-powershell) View the images in your ACR instance using the [`Get-AzContainerRegistryRepository`][get-azcontainerregistryrepository] cmdlet. ```azurepowershell-interactive Get-AzContainerRegistryRepository -RegistryName $ACRNAME ``` The following example output lists the available images in your registry: ```output aks-store-demo/productservice aks-store-demo/orderservice aks-store-demo/storefront ``` --- ## Next steps In this tutorial, you created an ACR and pushed images to it to use in an AKS cluster. You learned how to: > [!div class="checklist"] > > - Create an ACR instance. > - Use [ACR Tasks][acr-tasks] to build and push container images to ACR. > - View images in your registry. In the next tutorial, you learn how to deploy a Kubernetes cluster in Azure. > [!div class="nextstepaction"] > [Deploy Kubernetes cluster][aks-tutorial-deploy-cluster] <!-- LINKS - internal --> [az-acr-create]: /cli/azure/acr#az-acr-create [az-acr-repository-list]: /cli/azure/acr/repository#az-acr-repository-list [az-group-create]: /cli/azure/group#az-group-create [azure-cli-install]: /cli/azure/install-azure-cli [aks-tutorial-deploy-cluster]: ./tutorial-kubernetes-deploy-cluster.md [aks-tutorial-prepare-app]: ./tutorial-kubernetes-prepare-app.md [azure-powershell-install]: /powershell/azure/install-az-ps [new-azresourcegroup]: /powershell/module/az.resources/new-azresourcegroup [new-azcontainerregistry]: /powershell/module/az.containerregistry/new-azcontainerregistry [get-azcontainerregistryrepository]: /powershell/module/az.containerregistry/get-azcontainerregistryrepository [acr-tasks]: /azure/container-registry/container-registry-tasks-overview [az-acr-build]: /cli/azure/acr#az-acr-build [az-acr-import]: /cli/azure/acr#az-acr-import