Microsoft AKS

In Juju, Microsoft AKS is a Kubernetes cloud and works as described below.

Note

This reference assumes basic familiarity with Juju. If you are new to Juju, start with the Tutorial, then use this page together with the generic materials it links to.

Concepts

If you are familiar with Kubernetes, the following maps Kubernetes concepts to their Juju equivalents:

Kubernetes

Juju

namespace

model

node

machine (on Kubernetes clouds, not managed by Juju)

pod

unit

container

process in a unit

service

application

The cloud

See also: Cloud, Juju | Manage clouds, Juju | Add a Kubernetes cloud, Terraform Provider for Juju | Manage clouds

As for all Kubernetes clouds, the cloud is registered in Juju via a cloud definition, stored in clouds.yaml on the client and following this schema.

Tip

If using the Juju CLI, you can skip writing this file manually – juju add-k8s can read kubeconfig and create the cloud definition for you.

clouds:
  <cloud-name>:                    # User-defined name for the cluster
    type: kubernetes               # Always 'kubernetes' for Kubernetes clouds
    auth-types:                    # Authentication types
      - clientcertificate          # or: oauth2, userpass (legacy compatibility only: certificate, oauth2withcert)
    endpoint: <endpoint>           # Kubernetes API server URL
    host-cloud-region: <cloud>/<region>  # Optional: host cloud for the cluster (e.g., ec2/us-west-2)
    regions:                       # Optional: define regions
      <region-name>:
        endpoint: <endpoint>       # Region-specific endpoint (if different)
    config:                        # Optional: model config defaults
      operator-storage: <class>    # Storage class for operator storage
      workload-storage: <class>    # Storage class for workload storage
    ca-certificates:               # Optional: cluster CA certificates
      - <base64-cert>              # Base64-encoded x.509 certificates

Adding the cloud

When adding this cloud to Juju using the juju CLI client, starting with Juju 3.0 you must run the add-k8s command with the ‘raw’ client because the juju client snap is strictly confined but the AKS cloud CLI snap is not.

See more: Add a Kubernetes cloud

Credentials

See also: Credential, Juju | Manage credentials, Terraform Provider for Juju | Manage credentials

As for all Kubernetes clouds, credentials are stored in credentials.yaml on the client and follow this schema.

Tip

If using the Juju CLI, you can skip writing this file manually – juju add-k8s can read kubeconfig and create the matching credential entry for the selected context.

credentials:
  <cloud-name>:
    <credential-name>:
      auth-type: <auth-type>          # clientcertificate | oauth2 | userpass
      <auth-attributes>               # fill using one of the mappings below

Authentication types

As for all Kubernetes clouds, the supported authentication types are:

clientcertificate

Kubernetes client certificate and key.

  • ClientCertificateData: The Kubernetes certificate data (required).

  • ClientKeyData: The Kubernetes certificate key (required).

  • rbac-id: The unique ID key name of the RBAC resources (optional).

oauth2

OAuth2 token authentication.

  • Token: The Kubernetes token (required).

  • rbac-id: The unique ID key name of the RBAC resources (optional).

userpass

Username and password authentication.

  • username: The username to authenticate with (required).

  • password: The password for the specified username (required).

certificate (legacy)

Kubernetes service account token with certificate.

  • ClientCertificateData: The Kubernetes certificate data (required).

  • Token: The Kubernetes service account bearer token (required).

  • rbac-id: The unique ID key name of the RBAC resources (optional).

oauth2withcert (legacy)

OAuth2 token with certificate.

  • ClientCertificateData: The Kubernetes certificate data (required).

  • ClientKeyData: The Kubernetes private key data (required).

  • Token: The Kubernetes token (required).

Controllers

See also: Controller, Juju | Manage controllers, Terraform Provider for Juju | Manage controllers

As for all Kubernetes clouds, bootstrapping a controller creates the following resources in the cluster.

When bootstrapping a controller on a Kubernetes cloud, Juju creates a namespace for the controller and deploys the controller as a StatefulSet with associated resources. The controller manages the Juju state database (MongoDB) and API server within Kubernetes pods.

Resources created at bootstrap:

  • Namespace: A dedicated namespace for the controller (named controller-<controller-name>).

  • Service: A Kubernetes Service to expose the controller API (type depends on the cloud: LoadBalancer for public clouds, ClusterIP for localhost clouds).

  • ServiceAccount: A service account for the controller with cluster-admin privileges.

  • ClusterRoleBinding: Binds the controller service account to the cluster-admin ClusterRole.

  • StatefulSet: A StatefulSet with the controller pod containing two containers: mongodb (Juju’s state database) and api-server (Juju API server).

  • Secrets: Multiple secrets for TLS certificates (server.pem), shared secrets, and optionally docker registry credentials for private image registries.

  • ConfigMaps: Configuration maps for bootstrap parameters and agent configuration.

  • PersistentVolume and PersistentVolumeClaim: Storage for the controller’s operator-storage (MongoDB data and API server state).

  • Proxy resources (if using ClusterIP Service): Additional ConfigMap, Role, RoleBinding, and ServiceAccount for cluster IP proxy access.

As for all Kubernetes clouds, the controller service type depends on the host platform.

When bootstrapping a controller, Juju creates a Kubernetes Service to expose the controller API. The Service type depends on the host cloud platform where the Kubernetes cluster is running:

  • LoadBalancer: For managed Kubernetes on public clouds.

    • Amazon EKS (on EC2)

    • Google GKE (on GCE)

    • Microsoft AKS (on Azure)

    • Charmed Kubernetes on OpenStack

    • Charmed Kubernetes on MAAS (experimental)

  • ClusterIP: For localhost and development environments.

    • MicroK8s

    • Kubernetes on LXD

    • Other/unrecognized host clouds (default)

Note

LoadBalancer creates a cloud load balancer with a public IP, while ClusterIP uses internal cluster networking with optional proxy access.

Models

As for all Kubernetes clouds, the following cloud-specific model configuration keys are supported:

Storage

  • operator-storage: The storage class used to provision operator storage. Type: string. Default: "" (uses cluster default storage class). Immutable.

  • workload-storage: The preferred storage class used to provision workload storage. Type: string. Default: "" (uses cluster default storage class).

See more: <cloud-specific key>

Pods


(aks-cloud-adding)=
### Adding the cloud

When adding this cloud to Juju using the {ref}`juju CLI client <juju-client>`, starting with Juju 3.0 you must run the `add-k8s` command with the 'raw' client because the `juju` client snap is strictly confined but the AKS cloud CLI snap is not.

```{ibnote}
See more: {ref}`add-a-kubernetes-cloud`