docs: migrate 12-factor tutorials to Canonical Kubernetes

.github/workflows/spread-docs.yaml

@@ -38,7 +38,7 @@ jobs:
           path: ${{ steps.charmcraft.outputs.snap }}
 
   spread-select:
-    runs-on: [spread-installed]
+    runs-on: spread-enabled
     outputs:
       systems: ${{ steps.select.outputs.systems }}
     steps:

docs/.custom_wordlist.txt

@@ -10,6 +10,7 @@ Autotools
 backend
 backends
 backported
+balancer('s)?
 Bazel
 boolean
 bugfix(es)?

docs/howto/code/custom-action-clearsession/task.yaml

@@ -85,7 +85,7 @@ execute: |
     django-app-image=localhost:32000/django-hello-world:0.1
 
   # Deploy + integrate with postgres
-  juju deploy postgresql-k8s --trust --channel 14/edge
+  juju deploy postgresql-k8s --trust --channel 16/stable
   juju integrate django-hello-world postgresql-k8s
 
   # Check that django-hello-world and postgres are active idle

docs/howto/manage-web-app-charms/integrate-web-app-charm.rst

@@ -194,24 +194,11 @@ COS relies on the Traefik ingress to expose, for example, Grafana.
 Traefik requires a load balancer to be enabled with an IP range. Provide the
 IP range and enable the load balancer with:
 
-.. tab-set::
-
-    .. tab-item:: MicroK8s
-        :sync: microk8s
-
-        .. code-block:: bash
-
-            IPADDR=$(ip -4 -j route get 2.2.2.2 | jq -r '.[] | .prefsrc')
-            microk8s enable metallb:$IPADDR-$IPADDR
-
-    .. tab-item:: Canonical K8s
-        :sync: canonical-k8s
-
-        .. code-block:: bash
+.. code-block:: bash
 
-            IPADDR=$(ip -4 -j route get 2.2.2.2 | jq -r '.[] | .prefsrc')
-            sudo k8s set load-balancer.l2-mode=true load-balancer.cidrs=$IPADDR-$IPADDR
-            sudo k8s enable load-balancer
+    IPADDR=$(ip -4 -j route get 2.2.2.2 | jq -r '.[] | .prefsrc')
+    sudo k8s set load-balancer.l2-mode=true load-balancer.cidrs=$IPADDR-$IPADDR
+    sudo k8s enable load-balancer
 
 
 Deploy and integrate observability to the 12-factor app with:

docs/release-notes/charmcraft-4.5.rst

@@ -114,6 +114,17 @@ Minor init profile improvements
 - Charms created with the 12-factor framework profiles targeting Ubuntu 26.04 now default
   to ``charm-user: non-root``.
 
+Documentation improvements
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Charmcraft 4.5 includes the following documentation changes:
+
+- The 12-factor app :ref:`tutorials <tutorial>` now use Canonical Kubernetes
+  instead of MicroK8s, including a local OCI registry and load-balancer-backed
+  ingress.
+
+
+
 
 Feature deprecations
 --------------------

docs/reuse/tutorial/registry.yaml

@@ -0,0 +1,44 @@
+apiVersion: v1
+kind: List
+items:
+  - apiVersion: v1
+    kind: Namespace
+    metadata:
+      name: container-registry
+  - apiVersion: apps/v1
+    kind: Deployment
+    metadata:
+      name: registry
+      namespace: container-registry
+    spec:
+      replicas: 1
+      selector:
+        matchLabels:
+          app: registry
+      template:
+        metadata:
+          labels:
+            app: registry
+        spec:
+          containers:
+            - name: registry
+              image: registry:2.8.3
+              ports:
+                - containerPort: 5000
+              readinessProbe:
+                httpGet:
+                  path: /v2/
+                  port: 5000
+  - apiVersion: v1
+    kind: Service
+    metadata:
+      name: registry
+      namespace: container-registry
+    spec:
+      type: NodePort
+      selector:
+        app: registry
+      ports:
+        - port: 5000
+          targetPort: 5000
+          nodePort: 32000

docs/reuse/tutorial/setup_edge.rst

@@ -4,7 +4,7 @@ from the 26.04 blueprint:
 
 .. code-block:: text
 
-    multipass launch --cpus 4 --disk 50G --memory 4G --name charm-dev 26.04
+    multipass launch --cpus 4 --disk 50G --memory 8G --name charm-dev 26.04
 
 Once the VM is up, open a shell into it:
 
@@ -35,8 +35,8 @@ In order to create the charm, you'll need to install Charmcraft:
 
     sudo snap install charmcraft --channel latest/edge --classic
 
-Install LXD, MicroK8s, and Juju
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Install LXD and Canonical Kubernetes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 LXD will be required for building the rock.
 Make sure it is installed:
@@ -53,48 +53,80 @@ Initialize LXD:
 
     lxd init --auto
 
-MicroK8s is required to deploy the |12FactorApp| application on Kubernetes.
-Let's install MicroK8s using the ``1.34-strict/stable`` channel, add the current
-user to the group, and activate the changes:
+Canonical Kubernetes is required to deploy the |12FactorApp| application on
+Kubernetes. Let's install Canonical Kubernetes using the
+``1.34-classic/stable`` channel and bootstrap the cluster:
 
 .. code-block:: text
 
-    sudo snap install microk8s --channel 1.34-strict/stable
-    sudo adduser $USER snap_microk8s
-    newgrp snap_microk8s
+    sudo snap install k8s --classic --channel 1.34-classic/stable
+    sudo k8s bootstrap
 
-Several MicroK8s addons are required for deployment. We need
-``hostpath-storage`` so Juju can provide storage volumes,
-``registry`` to host the OCI image for our app, and ``ingress``
-so that we can expose and access the app.
+Canonical Kubernetes needs local storage so Juju can provide storage volumes,
+and ingress so that we can expose and access the app.
 
-Enable the necessary MicroK8s addons:
+Enable the necessary features:
 
 .. code-block:: bash
 
-    sudo microk8s enable hostpath-storage
-    sudo microk8s enable registry
-    sudo microk8s enable ingress
+    sudo k8s enable local-storage
+    sudo k8s enable ingress
 
-Check the status of MicroK8s:
+Canonical Kubernetes exposes ingress through a load-balancer service. Enable
+the built-in load balancer, wait for the MetalLB controller (which hosts the
+load balancer's validating webhook) to roll out, then point its address pool
+at the VM's own IP so the ingress is assigned a reachable address:
 
 .. code-block:: bash
 
-   sudo microk8s status --wait-ready
+    sudo k8s enable load-balancer
+    sudo k8s kubectl rollout status deployment/metallb-controller \
+      -n metallb-system --timeout=5m
+    INGRESS_IP=$(ip -4 route get 2.2.2.2 | grep -oP 'src \K[0-9.]+')
+    sudo k8s set load-balancer.l2-mode=true load-balancer.cidrs="$INGRESS_IP/32"
 
-If successful, the terminal will output ``microk8s is running``
-along with a list of enabled and disabled add-ons.
+Check the status of Canonical Kubernetes:
+
+.. code-block:: bash
+
+   sudo k8s status --wait-ready
+
+If successful, the terminal will output ``status: ready``
+along with a list of enabled and disabled features.
+
+Set up a local registry
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Canonical Kubernetes pulls application images from an OCI registry. Deploy a
+small registry inside the cluster, exposed on the node at ``localhost:32000``:
+
+.. code-block:: bash
+
+    curl --fail --location --output registry.yaml \
+      https://raw.githubusercontent.com/canonical/charmcraft/main/docs/reuse/tutorial/registry.yaml
+    sudo k8s kubectl apply -f registry.yaml
+
+Wait for the registry to become available:
+
+.. code-block:: bash
+
+    sudo k8s kubectl rollout status deployment/registry \
+      -n container-registry --timeout=5m
+
+Install Juju
+~~~~~~~~~~~~
 
 Juju is required to deploy the |12FactorApp| application.
 We'll install Juju using the ``3.6/stable`` channel. Since the snap is
 sandboxed, we'll also manually create a directory to contain
-its files. Once Juju is ready, we initialize it by bootstrapping a
-development controller:
+its files. Canonical Kubernetes isn't automatically registered as a Juju
+cloud, so let's add it before bootstrapping a development controller:
 
 .. code-block:: text
 
     sudo snap install juju --channel 3.6/stable
     mkdir -p ~/.local/share
-    juju bootstrap microk8s dev-controller
+    sudo k8s config | juju add-k8s k8s-cloud --client
+    juju bootstrap k8s-cloud dev-controller
 
 It could take a few minutes to download the images.

docs/reuse/tutorial/setup_stable.rst

@@ -4,7 +4,7 @@ from the 24.04 blueprint:
 
 .. code-block:: text
 
-    multipass launch --cpus 4 --disk 50G --memory 4G --name charm-dev 24.04
+    multipass launch --cpus 4 --disk 50G --memory 8G --name charm-dev 24.04
 
 Once the VM is up, open a shell into it:
 
@@ -30,8 +30,8 @@ In order to create the charm, you'll need to install Charmcraft:
 
     sudo snap install charmcraft --channel latest/stable --classic
 
-Install LXD, MicroK8s, and Juju
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Install LXD and Canonical Kubernetes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 LXD will be required for building the rock.
 Make sure it is installed:
@@ -48,49 +48,81 @@ Initialize LXD:
 
     lxd init --auto
 
-MicroK8s is required to deploy the |12FactorApp| application on Kubernetes.
-Let's install MicroK8s using the ``1.34-strict/stable`` channel, add the current
-user to the group, and activate the changes:
+Canonical Kubernetes is required to deploy the |12FactorApp| application on
+Kubernetes. Let's install Canonical Kubernetes using the
+``1.34-classic/stable`` channel and bootstrap the cluster:
 
 .. code-block:: text
 
-    sudo snap install microk8s --channel 1.34-strict/stable
-    sudo adduser $USER snap_microk8s
-    newgrp snap_microk8s
+    sudo snap install k8s --classic --channel 1.34-classic/stable
+    sudo k8s bootstrap
 
 
-Several MicroK8s addons are required for deployment. We need
-``hostpath-storage`` so Juju can provide storage volumes,
-``registry`` to host the OCI image for our app, and ``ingress``
-so that we can expose and access the app.
+Canonical Kubernetes needs local storage so Juju can provide storage volumes,
+and ingress so that we can expose and access the app.
 
-Enable the necessary MicroK8s addons:
+Enable the necessary features:
 
 .. code-block:: bash
 
-    sudo microk8s enable hostpath-storage
-    sudo microk8s enable registry
-    sudo microk8s enable ingress
+    sudo k8s enable local-storage
+    sudo k8s enable ingress
 
-Check the status of MicroK8s:
+Canonical Kubernetes exposes ingress through a load-balancer service. Enable
+the built-in load balancer, wait for the MetalLB controller (which hosts the
+load balancer's validating webhook) to roll out, then point its address pool
+at the VM's own IP so the ingress is assigned a reachable address:
 
 .. code-block:: bash
 
-   sudo microk8s status --wait-ready
+    sudo k8s enable load-balancer
+    sudo k8s kubectl rollout status deployment/metallb-controller \
+      -n metallb-system --timeout=5m
+    INGRESS_IP=$(ip -4 route get 2.2.2.2 | grep -oP 'src \K[0-9.]+')
+    sudo k8s set load-balancer.l2-mode=true load-balancer.cidrs="$INGRESS_IP/32"
 
-If successful, the terminal will output ``microk8s is running``
-along with a list of enabled and disabled add-ons.
+Check the status of Canonical Kubernetes:
+
+.. code-block:: bash
+
+   sudo k8s status --wait-ready
+
+If successful, the terminal will output ``status: ready``
+along with a list of enabled and disabled features.
+
+Set up a local registry
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Canonical Kubernetes pulls application images from an OCI registry. Deploy a
+small registry inside the cluster, exposed on the node at ``localhost:32000``:
+
+.. code-block:: bash
+
+    curl --fail --location --output registry.yaml \
+      https://raw.githubusercontent.com/canonical/charmcraft/main/docs/reuse/tutorial/registry.yaml
+    sudo k8s kubectl apply -f registry.yaml
+
+Wait for the registry to become available:
+
+.. code-block:: bash
+
+    sudo k8s kubectl rollout status deployment/registry \
+      -n container-registry --timeout=5m
+
+Install Juju
+~~~~~~~~~~~~
 
 Juju is required to deploy the |12FactorApp| application.
 We'll install Juju using the ``3.6/stable`` channel. Since the snap is
 sandboxed, we'll also manually create a directory to contain
-its files. Once Juju is ready, we initialize it by bootstrapping a
-development controller:
+its files. Canonical Kubernetes isn't automatically registered as a Juju
+cloud, so let's add it before bootstrapping a development controller:
 
 .. code-block:: text
 
     sudo snap install juju --channel 3.6/stable
     mkdir -p ~/.local/share
-    juju bootstrap microk8s dev-controller
+    sudo k8s config | juju add-k8s k8s-cloud --client
+    juju bootstrap k8s-cloud dev-controller
 
 It could take a few minutes to download the images.