Quickstart: Develop on Azure Kubernetes Service (AKS) with Helm

Helm is an open-source packaging tool that helps you install and manage the lifecycle of Kubernetes applications. Similar to Linux package managers like APT and Yum, Helm manages Kubernetes charts, which are packages of pre-configured Kubernetes resources.

In this quickstart, you use Helm to package and run an application on AKS. For information on installing an existing application using Helm, see Install existing applications with Helm in AKS.

Prerequisites

Create an Azure Container Registry

You need to store your container images in an Azure Container Registry (ACR) to run your application in your AKS cluster using Helm. Your registry name must be unique within Azure and contain 5-50 alphanumeric characters. Only lowercase characters are allowed. The Basic SKU is a cost-optimized entry point for development purposes that provides a balance of storage and throughput.

  1. Create an Azure resource group using the az group create command. The following example creates a resource group named myResourceGroup in the eastus location.

    az group create --name myResourceGroup --location chinaeast2
    
  2. Create an Azure Container Registry with a unique name by calling the az acr create command. The following example creates an ACR named myhelmacr with the Basic SKU.

    az acr create --resource-group myResourceGroup --name myhelmacr --sku Basic
    

    Your output should look similar to the following condensed example output. Take note of your loginServer value for your ACR to use in a later step.

    {
      "adminUserEnabled": false,
      "creationDate": "2023-12-26T22:36:23.998425+00:00",
      "id": "/subscriptions/<ID>/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/myhelmacr",
      "location": "eastus",
      "loginServer": "myhelmacr.azurecr.cn",
      "name": "myhelmacr",
      "networkRuleSet": null,
      "provisioningState": "Succeeded",
      "resourceGroup": "myResourceGroup",
      "sku": {
        "name": "Basic",
        "tier": "Basic"
      },
      "status": null,
      "storageAccount": null,
      "tags": {},
      "type": "Microsoft.ContainerRegistry/registries"
    }
    

Create an AKS cluster

Your new AKS cluster needs access to your ACR to pull the container images and run them.

  • Create an AKS cluster using the az aks create command with the --attach-acr parameter to grant the cluster access to your ACR. The following example creates an AKS cluster named myAKSCluster and grants it access to the myhelmacr ACR. Make sure you replace myhelmacr with the name of your ACR.

      az aks create --resource-group myResourceGroup --name myAKSCluster --location chinaeast2 --attach-acr myhelmacr --generate-ssh-keys
    

Connect to your AKS cluster

To connect a Kubernetes cluster locally, you use the Kubernetes command-line client, kubectl.

  1. Install kubectl locally using the az aks install-cli command.

    az aks install-cli
    
  2. Configure kubectl to connect to your Kubernetes cluster using the az aks get-credentials command. The following command gets credentials for the AKS cluster named myAKSCluster in myResourceGroup.

    az aks get-credentials --resource-group myResourceGroup --name myAKSCluster
    

Download the sample application

This quickstart uses the Azure Vote application.

  1. Clone the application from GitHub using the git clone command.

    git clone https://github.com/Azure-Samples/azure-voting-app-redis.git
    
  2. Navigate to the azure-vote directory using the cd command.

    cd azure-voting-app-redis/azure-vote/
    

Build and push the sample application to ACR

  • Build and push the image to your ACR using the az acr build command. The following example builds an image named azure-vote-front:v1 and pushes it to the myhelmacr ACR. Make sure you replace myhelmacr with the name of your ACR.

    az acr build --image azure-vote-front:v1 --registry myhelmacr --file Dockerfile .
    

Note

You can also import Helm charts into your ACR. For more information, see Push and pull Helm charts to an Azure container registry.

Create your Helm chart

  1. Generate your Helm chart using the helm create command.

    helm create azure-vote-front
    
  2. Update azure-vote-front/Chart.yaml to add a dependency for the redis chart from the https://charts.bitnami.com/bitnami chart repository and update appVersion to v1, as shown in the following example:

    Note

    The container image versions shown in this guide have been tested to work with this example but may not be the latest version available.

    apiVersion: v2
    name: azure-vote-front
    description: A Helm chart for Kubernetes
    
    dependencies:
      - name: redis
        version: 17.3.17
        repository: https://charts.bitnami.com/bitnami
    
    ...
    # This is the version number of the application being deployed. This version number should be
    # incremented each time you make changes to the application.
    appVersion: v1
    
  3. Update your Helm chart dependencies using the helm dependency update command.

    helm dependency update azure-vote-front
    
  4. Update azure-vote-front/values.yaml with the following changes.

    • Add a redis section to set the image details, container port, and deployment name.
    • Add a backendName for connecting the frontend portion to the redis deployment.
    • Change image.repository to <loginServer>/azure-vote-front.
    • Change image.tag to v1.
    • Change service.type to LoadBalancer.

    For example:

    replicaCount: 1
    backendName: azure-vote-backend-master
    redis:
      image:
        registry: mcr.azk8s.cn
        repository: oss/bitnami/redis
        tag: 6.0.8
      fullnameOverride: azure-vote-backend
      auth:
        enabled: false
    
    image:
      repository: myhelmacr.azurecr.cn/azure-vote-front
      pullPolicy: IfNotPresent
      tag: "v1"
    ...
    service:
      type: LoadBalancer
      port: 80
    ...
    
  5. Add an env section to azure-vote-front/templates/deployment.yaml to pass the name of the redis deployment.

    ...
          containers:
            - name: {{ .Chart.Name }}
              securityContext:
                {{- toYaml .Values.securityContext | nindent 12 }}
              image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
              imagePullPolicy: {{ .Values.image.pullPolicy }}
              env:
              - name: REDIS
                value: {{ .Values.backendName }}
    ...
    

Run your Helm chart

  1. Install your application using your Helm chart using the helm install command.

    helm install azure-vote-front azure-vote-front/
    
  2. It takes a few minutes for the service to return a public IP address. Monitor progress using the kubectl get service command with the --watch argument.

    kubectl get service azure-vote-front --watch
    

    When the service is ready, the EXTERNAL-IP value changes from <pending> to an IP address. Press CTRL+C to stop the kubectl watch process.

      NAME               TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)        AGE
      azure-vote-front   LoadBalancer   10.0.18.228   <pending>       80:32021/TCP   6s
      ...
      azure-vote-front   LoadBalancer   10.0.18.228   52.188.140.81   80:32021/TCP   2m6s
    
  3. Navigate to your application's load balancer in a browser using the <EXTERNAL-IP> to see the sample application.

Delete the cluster

  • Remove your resource group, AKS cluster, Azure container registry, container images stored in the ACR, and all related resources using the az group delete command with the --yes parameter to confirm deletion and the --no-wait parameter to return to the command prompt without waiting for the operation to complete.

    az group delete --name myResourceGroup --yes --no-wait
    

Note

If you created your AKS cluster with a system-assigned managed identity (the default identity option in this quickstart), the identity is managed by the platform and doesn't require removal.

If you created your AKS cluster with a service principal, the service principal isn't removed when you delete the cluster. To remove the service principal, see AKS service principal considerations and deletion.

Next steps

For more information about using Helm, see the Helm documentation.