The Kubernetes Current Blog

Getting started with Azure Kubernetes Service (AKS)

Azure Kubernetes service (AKS) maintains your hosted Kubernetes environment, making it quick and easy to deploy and manage containerized applications without having a proficiency in container orchestration. It also eliminates the burden of ongoing Kubernetes operations and maintenance by provisioning, upgrading, and scaling resources on demand, without taking your applications offline. As a hosted Kubernetes service, Azure handles critical tasks like health monitoring and maintenance for you. The Kubernetes masters are managed by Azure. You only manage and maintain the agent nodes. In this guide we will be creating AKS clusters in the Azure portal with Azure CLI.


This guide is designed to help you get started with Azure Kubernetes Service (AKS).We will be using Azure CLI to setup the AKS cluster and host a multi-container application. This guide will walk through the steps to:

  • Prepare application for AKS
  • Deploy and use Azure Container Registry
  • Deploy an AKS cluster
  • Deploy application in AKS cluster
  • Scale applications in AKS
  • Upgrade AKS cluster
  • Continuous Deployment with Jenkins

Prepare an application for AKS

In this section, we will clone an application source from GitHub, create a container image from the application code and launch container application in a local Docker environment.


Before we launch Kubernetes clusters we launch some docker containers from a code available on Github. This requires the following :

  • A local Docker development environment running Linux containers.
  • It is assumed that you have a basic understanding of core Docker concepts such as containers, container images and docker commands.

Clone the application code

The sample application used in this guide is a basic voting app. The application consists of a front-end web component and a back-end Redis instance. The web component is packaged into a custom container image. The Redis instance uses an unmodified image from Docker Hub.

Use git to clone the sample application to your development environment:

Prep app for AKS- Clone app code

Inside the directory is the application source code, a pre-created Docker compose file, and a Kubernetes manifest file. These files are used throughout the tutorial set.

Create container images

Docker Compose can be used to automate building container images and the deployment of multi-container applications.Use the sample docker-compose.yaml file to create the container image, download the Redis image, and start the application:

Prep app for AKS- Create Container Images 1

When completed, use the docker images command to see the created images. Three images have been downloaded or created. The azure-vote-front image contains the front-end application and uses the nginx-flask image as a base. The redis image is used to start a Redis instance. Run the docker ps command to see the running containers:

Prep app for AKS- Create Container Images 2

Test the application locally

To see the running application, enter https://localhost:8080 in a local web browser. The sample application loads, as shown in the following example:

Prep app for AKS- Test the app locally

Clean up resources

Now that the application’s functionality has been validated, the running containers can be stopped and removed. We won’t be removing the images.

Prep app for AKS- Clean up resources

Deploy and use Azure Container Registry

Azure Container Registry (ACR) is a private registry for container images. A private container registry lets you securely build and deploy your applications and custom code. In this tutorial, part two of seven, you deploy an ACR instance and push a container image to it.

Create an Azure Container Registry

To create an Azure Container Registry, you first need a resource group. An Azure resource group is a logical container into which Azure resources are deployed and managed.

Create a resource group with the az group create command. In the following example, a resource group named myResourceGroup is created in the eastus region. You can also use the Azure cloud shell also.

Deploy and use- create azure container registry1

Create an Azure Container Registry instance with the az acr create command and provide your own registry name. The registry name must be unique within Azure, and contain 5-50 alphanumeric characters.

Deploy and use- create azure container registry2

Login to container registry

To use the ACR instance, you must first log in. Use the az acr login command and provide the unique name given to the container registry in the previous step.

Deploy and use- Login to container registry

Tag a container image

To see a list of your current local images, use the docker images command:

Deploy and use- Tag container image1

To use the azure-vote-front container image with ACR, the image needs to be tagged with the login server address of your registry. This tag is used for routing when pushing container images to an image registry.

To get the login server address, use the az acr list command and query for the loginServer as follows:

Deploy and use- Tag container image2

Deploy and use- Tag container image3

Now, tag your local azure-vote-front image with the acrloginServer address of the container registry. To indicate the image version, add :v1 to the end of the image name and to verify the tags are applied, run docker images again. An image is tagged with the ACR instance address and a version number.

Deploy and use- Tag container image4

Push images to registry

With your image built and tagged, push the azure-vote-front image to your ACR instance. Use docker push and provide your own acrLoginServer address for the image name as follows:

Deploy and use- Push Images to registry

It may take a few minutes to complete the image push to ACR.

List images in registry

To return a list of images that have been pushed to your ACR instance, use the az acr repository list command. The following example output lists the azure-vote-front image as available in the registry:

Deploy and use- List images in registry1

To see the tags for a specific image, use the az acr repository show-tags command as follows:

Deploy and use- List images in registry2

You now have a container image that is stored in a private Azure Container Registry instance. This image will be deployed from ACR to Kubernetes cluster in the next steps.

Deploy an AKS cluster

Kubernetes provides a distributed platform for containerized applications. With AKS, you can quickly create a production ready Kubernetes cluster. In this section, we will create a Kubernetes cluster.

Create a Kubernetes cluster

Create an AKS cluster using az aks create. The following example creates a cluster named myAKSCluster in the resource group named myResourceGroup.  It creates two nodes and copies the public key to the nodes.

Deploy AKS Cluster- Create Kubernetes Cluster

Install the Kubernetes CLI

To connect to the Kubernetes cluster from your local computer, you use kubectl, the Kubernetes command-line client. You can also install it locally using the az aks install-cli command:

Deploy AKS Cluster- Install KubeCTL

Connect to cluster using kubectl 

To configure kubectl to connect to your Kubernetes cluster, use the az aks get-credentials command. The following example gets credentials for the AKS cluster named myAKSCluster in the myResourceGroup:

Deploy AKS Cluster- Connect to Cluster using KubeCTL1

To verify the connection to your cluster, run the kubectl get nodes command:

Deploy AKS Cluster- Connect to Cluster using KubeCTL2

The output will show two nodes which we have initiated while creating the cluster.

Run applications in AKS

Kubernetes provides a distributed platform for containerized applications. You build and deploy your own applications and services into a Kubernetes cluster, and let the cluster manage the availability and connectivity. In this section, we will deploy our application in kubernetes (K8s) cluster from the azure-voting-app image which we uploaded in the azure container registry.

Update the manifest file

To deploy the application, you must update the image name in the Kubernetes manifest file to include the ACR login server name.

The sample manifest file from the git repo cloned in the first tutorial uses the login server name of microsoft. Make sure that you’re in the cloned azure-voting-app-redis directory, then open the manifest file with a text editor, such as vi:

Run Apps in AKS- Update manifest file1

Replace microsoft with your ACR login server name. The image name is found on line 51 of the manifest file. The following example shows the default image name:

Run Apps in AKS- Update manifest file2

Save and close the file. In vi, use :wq.


Deploy the application

To deploy your application, use the kubectl apply command. This command parses the manifest file and creates the defined Kubernetes objects. Specify the sample manifest file, as shown in the following example:

Run Apps in AKS- Deploy the App

Test the application

When the application runs, a Kubernetes service exposes the application front end to the internet. This process can take a few minutes to complete.

Run Apps in AKS- Test the App1

To monitor progress, use the kubectl get service command with the –watch argument. When the EXTERNAL-IP address changes from pending to an actual public IP address, use CTRL-C to stop the kubectl watch process. The following example output shows a valid public IP address assigned to the service:

Run Apps in AKS- Test the App2

To see the application in action, open a web browser to the external IP address of your service:

Run Apps in AKS- Test the App3


Scale application in AKS

In this section, we will scale application the application horizontally and vertically according to different parameters.

Manually scale the pods

When the Azure Vote front-end and Redis instance were deployed, a single replica was created. To see the number and state of pods in your cluster run the following command.

Scale App in AKS- Manually Scale the Pod1

The output shows one front-end pod and one back-end pod. To manually change the number of pods in the azure-vote-front deployment, use the kubectl scale command. The following example increases the number of front-end pods to 5.

Scale App in AKS- Manually Scale the Pod2

Run kubectl get pods again to verify that AKS creates the additional pods. After a minute or so, the additional pods are available in your cluster:

Scale App in AKS- Manually Scale the Pod3

Autoscale pods

Kubernetes supports horizontal pod autoscaling to adjust the number of pods in a deployment depending on CPU utilization or other select metrics. The Metrics Server is used to provide resource utilization to Kubernetes, and is automatically deployed in AKS clusters versions 1.10 and higher.

To use the autoscaler, all containers in your pods and your pods must have CPU requests and limits defined. In the azure-vote-front deployment, the front-end container already requests 0.25 CPU, with a limit of 0.5 CPU. These resource requests and limits are defined as shown in the following example snippet:

Scale App in AKS- Autoscale1

The following example uses the kubectl autoscale command to autoscale the number of pods in the azure-vote-front deployment. If average CPU utilization across all pods exceeds 50% of their requested usage, the autoscaler increases the pods up to a maximum of 10 instances. A minimum of 3 instances is then defined for the deployment:

Scale App in AKS- Autoscale2

To see the status of the autoscaler, use the kubectl get hpa command as follows:

Scale App in AKS- Autoscale3

After a few minutes, with minimal load on the Azure Vote app, the number of pod replicas decreases automatically to three. You can use kubectl get pods again to see the unneeded pods being removed.


Manually scale AKS nodes

The following example increases the number of nodes to three in the Kubernetes cluster named myAKSCluster.

Scale App in AKS- Manually scale AKS Nodes

Update an application in AKS

In this section, we will update the code , run docker compose to update the application with new updated code.

Update an application

Let’s make a change to the sample application, then update the version already deployed to your AKS cluster. Make sure that you’re in the cloned azure-voting-app-redis directory. The sample application source code can then be found inside the azure-vote directory. Open the config_file.cfg file with an editor, such as vi:

Update Application in AKS- Update App1

Change the values for VOTE1VALUE and VOTE2VALUE:

Update Application in AKS- Update App2

Save and close the file. In vi, use :wq.

Update the container image

To re-create the front-end image and test the updated application, use docker-compose. The –build argument is used to instruct Docker Compose to re-create the application image:

Update Application in AKS- Update Container Image

Test the application locally

To verify that the updated container image shows your changes, open a local web browser to https://localhost:8080.

Update Application in AKS- Test the app locally


Deploy from GitHub to Azure Kubernetes Service (AKS) with Jenkins

Before you integrate Jenkins and AKS for automated deployments, first manually prepare and deploy the Azure vote application to your AKS cluster. Then we need to tag the image and upload it to Azure container registry.

Deploy Jenkins to an Azure VM

To quickly deploy Jenkins , you can use the following script to deploy an Azure virtual machine, configure network access, and complete a basic installation of Jenkins. For authentication between Jenkins and the AKS cluster, the script copies your Kubernetes configuration file from your development system to the Jenkins system.

Run the following commands to download and run the script.

Deploy Jenkins to an Azure VM1

It takes a few minutes to create the VM and deploy the required components for Docker and Jenkins. When the script has completed, it outputs an address for the Jenkins server and a key to unlock the dashboard, as shown in the following example output:

Deploy Jenkins to an Azure VM2

Create a Jenkins environment variable

A Jenkins environment variable is used to hold the ACR login server name. This variable is referenced during the Jenkins build job. To create this environment variable, complete the following steps:

On the left-hand side of the Jenkins portal, select Manage Jenkins > Configure System

Under Global Properties, select Environment variables. Add a variable with the name ACR_LOGINSERVER and the value of your ACR login server.

Create a Jenkins environment variables

Create a Jenkins credential for ACR

To allow Jenkins to build and then push updated container images to ACR, you need to specify credentials for ACR. This authentication can use Azure Active Directory service principals. In the pre-requisites, you configured the service principal for your AKS cluster with Reader permissions to your ACR registry. These permissions allow the AKS cluster to pull images from the ACR registry. During the CI/CD process, Jenkins builds new container images based on application updates, and needs to then push those images to the ACR registry. For separation of roles and permissions, now configure a service principal for Jenkins with Contributor permissions to your ACR registry.

First, create a service principal using the az ad sp create-for-rbac command:

Create Jenkins credential for ACR1

Make a note of the appID and password shown in your output. These values are used in following steps to configure the credential resource in Jenkins.

Get the resource ID of your ACR registry using the az acr show command, and store it as a variable. Provide your resource group name and ACR name:

Create Jenkins credential for ACR2

Now create a role assignment to assign the service principal Contributor rights to the ACR registry. In the following example, provide your own appId shown in the output a previous command to create the service principal:

Create Jenkins credential for ACR3

Create a Jenkins Project

  • From the home page of your Jenkins portal, select New item on the left-hand side:
  • Enter azure-vote as job name. Choose Freestyle project, then select OK
  • Under the General section, select GitHub project and enter your forked repo URL, such as<your-github-account>/azure-voting-app-redis
  • Under the Source code management section, select Git, enter your forked repo .git URL, such as<your-github-account>/azure-voting-app-redis.git
  • Under the Build Triggers section, select GitHub hook trigger for GITscm polling
  • Under Build Environment, select Use secret texts or files
  • Under Bindings, select Add > Username and password (separated)
  • Enter ACR_ID for the Username Variable, and ACR_PASSWORD for the Password Variable

Create Jenkins Project 1

  • Create a Jenkins free style job and add this in the build configuration with execute shell.

Create Jenkins Project- Build

  • Once completed, click Save.


Test the Jenkins Project

Before you automate the job based on GitHub commits, first manually test the Jenkins build. This manual build validates that the job has been correctly configured, the proper Kubernetes authentication file is in place, and that the authentication with ACR works.

On the left-hand menu of the project, select Build Now.

Test the Jenkins Project 1

The first build takes a minute or two as the Docker image layers are pulled down to the Jenkins server. Subsequent builds can use the cached image layers to improve the build times.

During the build process, the GitHub repository is cloned to the Jenkins build server. A new container image is built and pushed to the ACR registry. Finally, the Azure vote application running on the AKS cluster is updated to use the new image. Because no changes have been made to the application code, the application is not changed if you view the sample app in a web browser.

Once the build job is complete, click on build #1 under build history. Select Console Output and view the output from the build process. The final line should indicate a successful build.

Create a GITHUB webhook

With a successful manual build complete, now integrate GitHub into the Jenkins build. A webhook can be used to run the Jenkins build job each time a code commit is made in GitHub. To create the GitHub webhook, complete the following steps:

Browse to your forked GitHub repository in a web browser.

Select Settings, then select Webhooks on the left-hand side.

Choose to Add webhook. For the Payload URL, enter https://<publicIp:8080>/github-webhook/, where <publicIp> is the IP address of the Jenkins server. Make sure to include the trailing /. Leave the other defaults for content type and to trigger on push events.

Select Add webhook.

Create GitHub WebHook


Test the CI/CD Pipeline

Now you can test the whole CI/CD pipeline. When you push a code commit to GitHub, the following steps happen:

The GitHub webhook reaches out to Jenkins.

Jenkins starts the build job and pulls the latest code commit from GitHub.

A Docker build is started using the updated code, and the new container image is tagged with the latest build number.

This new container image is pushed to Azure Container Registry.

Your application deployed to Azure Kubernetes Service updates with the latest container image from the Azure Container Registry registry.

On your development machine, open up the cloned application with a code editor. Under the /azure-vote/azure-vote directory, open the file named config_file.cfg. Update the vote values in this file to something other than cats and dogs, as shown in the following example:

Test CI CD Pipeline1

When updated, save the file, commit the changes, and push these to your fork of the GitHub repository. The GitHub webhook triggers a new build job in Jenkins. In the Jenkins web dashboard, monitor the build process. It takes a few seconds to pull the latest code, create and push the updated image, and deploy the updated application in AKS.

Test CI CD Pipeline2

This will trigger the Jenkins Pipeline.

Test CI CD Pipeline3

Once the build is complete, refresh your web browser of the sample Azure vote application. Your changes are displayed, as shown in the following example:

Test CI CD Pipeline4


In this guide you have seen how easily we build an AKS cluster on Azure environment. AKS offers a platform for managing your containers across a variety of operating environments, significantly reducing the time necessary to build, deploy, and scale them. As an open source next-generation virtualization tool, Azure Kubernetes service provides you with all the functionality you need to optimize containerization usage with your existing IT resources.



AKS , Azure Kubernetes Service , Cluster Management , Containers , Getting Started Guides , Kubernetes

Trusted by leading companies