MicroK8s

In Juju, MicroK8s 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.

Requirements

Services that must be enabled:

• dns

• hostpath-storage

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

For a localhost MicroK8s cloud, if you would like to be able to skip juju add-k8s, install MicroK8s from the strictly confined snap.

See more: MicroK8s | Strict MicroK8s

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

See also: Unit, Juju | Manage units

As for all Kubernetes clouds, the following constraints apply to pod resources and placement.

The following constraints apply to pod resources and placement behavior:

• cpu-power. CPU resource request/limit for pods.

• mem. Memory resource request/limit for pods.

• tags. Used for pod affinity, anti-affinity, and node affinity rules.

Constraints like arch, cores, instance-type, root-disk, zones, and others are not supported on Kubernetes clouds. Kubernetes manages node resources and pod scheduling.

Placement directives are not supported on Kubernetes clouds. Pod placement is controlled by Kubernetes scheduling, node selectors, and affinity rules (configured via constraints).

As for all Kubernetes clouds, application pods follow these deployment patterns.

See also: Unit, Juju | Manage units

When deploying an application to a Kubernetes model, Juju creates:

• Deployment, StatefulSet, or DaemonSet: Depending on the charm specification and application type. StatefulSets are used for applications requiring stable network identities and persistent storage. Deployments are used for stateless applications. DaemonSets run one pod per node.

• Pod: One or more pods containing the application’s charm containers. Each pod typically includes an init container (juju-init) and a main container (juju-operator).

• Service: A Kubernetes Service to expose the application within the cluster or externally.

• ConfigMap: Configuration data for the application.

• Secret: Sensitive data like credentials.

• PersistentVolume and PersistentVolumeClaim: If the charm requires storage, one PV/PVC per unit is created based on the configured storage class.

Kubernetes application pods in Juju follow these patterns:

Sidecar charms (current pattern):

• Init container (charm-init): Prepares the pod environment before the main container starts.

• Charm container (charm): Runs the charm logic alongside the workload.

• Workload containers: Defined by the charm (e.g., database, web server).

Operator charms (older pattern):

• Init container (juju-init): Prepares the pod environment before the main container starts.

• Operator container (juju-operator): Runs the charm logic and manages the application lifecycle.

• Workload containers: Defined by the charm.

Storage

See also: Storage, Juju | Manage storage; Storage provider

Storage providers

As for all Kubernetes clouds, in addition to the generic storage providers, this cloud also has access to the following cloud-specific storage provider:

kubernetes

See also: Persistent storage and Kubernetes

The kubernetes storage provider provisions storage using Kubernetes PersistentVolumeClaims (PVCs). The underlying storage is provided by the cluster’s configured storage classes.

Configuration options:

• storage-class: The storage class for the Kubernetes cluster to use. It can be any storage class defined in your cluster, for example: microk8s-hostpath, gp2, standard, etc.

• storage-provisioner: The Kubernetes storage provisioner. For example: kubernetes.io/no-provisioner, kubernetes.io/aws-ebs, kubernetes.io/gce-pd, microk8s.io/hostpath, etc.

• parameters.type: Extra parameters passed to the storage provisioner. For example: gp2, pd-standard, etc.