How to use Microsoft AKS with Juju

This guide will ensure that you’re ready to deploy and manage Kubernetes workloads on Azure Kubernetes Service (AKS) with Juju. Juju provides built-in support for AKS. Once you’ve registered your cluster in Juju, you’ll be able to deploy workloads from Charmhub straight away.



Using Juju to drive Kubernetes workloads on AKS requires installing some prerequisite software:

  • Juju client
  • Azure CLI
  • Kubernetes client

Install the Juju client

You will need to install the Juju client. If you’re on Linux, we recommend using snap:

sudo snap install juju --classic

We also provide other installation methods as described on our detailed installation documentation.

Install the Azure CLI

The Azure CLI is a cross-platform command-line utility for interacting with Azure. For installation instructions, please visit the Azure CLI web pages.

Install the Kubernetes client

kubectl is the command-line client for directly interacting with a Kubernetes cluster. The Azure CLI provides a sub-command that will install kubectl for you:

az aks install-cli

If you encounter any issues with this, visit the Kubernetes documentation for manual kubectl installation instructions.

Provision a Kubernetes cluster on Azure

This guide will assume that your Azure account has sufficient access to an Azure Subscription to allow the creation of Resource Groups and Azure Kubernetes Service clusters.

I don't have an Azure Account/Subscription!

If you do not have an Azure account, you can create one free of charge, complete with trial credit as described on the Azure website.

If you do have an account, but it is not associated with a subscription, you may need to create a new subscription. Consult the Azure Docs on programmatic subscription creation for details.

Azure resources can be created from the Azure CLI, Azure Portal or using Azure Powershell. This guide will focus on the creation of a cluster using the Azure CLI. For information on how deploy using the Azure Portal see the Azure Documentation or go directly to the portal to create your cluster.

Please refer to the Azure documentation for authoritative information on how to manage services and accounts with Azure.

Log into Azure using the Azure CLI

To log in from the command-line, execute:

az login

This will open a browser window (or provide an authentication link) that will allow you to authenticate with Microsoft Azure. Once logged in, confirm you have access to a subscription by running:

az account list -o table
(Optional) Managing multiple subscriptions

If you have access to multiple subscriptions, you can identify the one that is currently active by running:

az account show -o table

It is important to check that it is the one you want, or else you may incur charges against the wrong subscription. The default can be changed easily:

az account set -s <subscription>

Create the Kubernetes cluster with the Azure CLI

Now that we’ve created a Resource Group in the correct region, we can provision a new Azure Kubernetes Service cluster.

Create a resource group

A “Resource Group” is a link between services and a geographic region for billing and authentication purposes. To create a Resource Group for your project, provide a region and a human-readable name to the az group create command.

az group create -l <region> -n <resource-group>
Help selecting an Azure Region

Each Azure region has different capabilities. In particular, different Kubernetes versions are supported within each region. To get the list of regions, execute:

juju regions azure

The Azure CLI can inspect regions and enumerate supported Kubernetes versions.

az aks get-versions -l <region> -o table

Provision the AKS cluster with the Azure CLI

The az aks create command provisions a cluster. The command below will create a cluster in the specified Resource Group, generating a new SSH keypair for the underlying nodes:

az aks create -g <resource-group> -n <k8s-cluster-name> --generate-ssh-keys

az aks create is highly configurable. To learn more about the available options, consult az aks create --help.

Access the cluster

The Azure CLI is able to configure kubectl on your behalf to access your new AKS cluster:

az aks get-credentials -g <resource-group> -n <k8s-cluster-name>

Verify that you have access by enumerating the nodes in the cluster:

kubectl get nodes

Connect Juju to your Kubernetes cluster

There are three distinct stages to configuring your AKS cluster for management with Juju:

  • Register the cluster as a Kubernetes cloud

  • Deploy a Juju controller to the cluster

  • Create a model to house our applications

Register the cluster as a Kubernetes cloud

In Juju’s vocabulary, a cloud is a space that can host deployed workloads. To register a Kubernetes cluster with Juju, execute the juju add-k8s command. The <cloud> argument is your specified name for the cloud, and will be used by Juju to refer to the cluster.

juju add-k8s --aks --resource-group <resource-group> --cluster-name <k8s-cluster> <cloud>

Create a controller

Juju, as an active agent system, requires a controller to get started. Controllers are created with the juju bootstrap command that takes as arguments a cloud’s name and, optionally, also our intended name for the controller.

juju bootstrap <cloud>
(Optional) Specify a controller name

You can specify the name of your Juju controller if you wish:

juju bootstrap <cloud> <controller-name>

If you do not, Juju will generate the name using the name of the cloud.

Create a model

A model is a workspace for inter-related applications. They correspond (roughly) to a Kubernetes namespace. To create one, use juju add-model with a name of your choice:

juju add-model <model-name>

Deploy workloads

You’re now able to deploy workloads into your model. Workloads are provided by charms (and sets of charms called bundles). You can find a list of Kubernetes charms on Charmhub!

Clean up

The following instructions allow you to undo everything we just did!

The following commands are destructive, and will destroy all running workloads that were deployed with Juju, then remove the Resource Group and AKS cluster. Ensure there is nothing in the Resource Group you need before proceeding!

Remove the Juju controller and any workloads deployed:

juju kill-controller -y -t0 <controller>

Delete the Azure Resource Group (and therefore the cluster)

az group delete -g <resource-group>

All of the stuff related on how to create a kubernetes cluster, could be just a link to azure documentation, similarly what we do in the GKE documentation; i.e. we can leave in the installation of the cli tools and then directly start with “Set up Juju within the cluster” chapter.

It seems command

juju add-k8s --aks --resource-group <resource-group> --cluster-name <k8s-cluster> <cloud>

Is much more verbose than the analogues for gke - juju add-k8s --gke. Although command itself could be partly removed in the future and made to be automatic (since Thomas is working on it).

Also have a different output then expected -

This operation can be applied to both a copy on this client and to the one on a controller.
Do you want to add k8s cloud aks to:
    1. client only (--client)
    2. controller "for-juju" only (--controller for-juju)
    3. both (--client --controller for-juju)
Enter your choice, or type Q|q to quit: 

It would also be cool to add links (at least) on how all of these things we just created - cloud, k8s, credentials and etc; could be removed

Thanks, I think that’s probably the best way to go too. I’ll look into doing this systematically for all the cloud-specific posts. Then we could cover explicitly just the part about connecting to Juju.

This produces an error:

ERROR   No recommended storage configuration is defined on this cluster.
        Run add-k8s again with --storage=<name> and Juju will use the
        specified storage class or create a storage-class using the recommended
        "Azure Disk" provisioner.

@tmihoc we need to add details on creating storage or letting juju do it for you. Letting juju do it for you is easy, add --storage=<name of new storage> to the bootstrap line. Not sure how to create storage in azure for the other case.