Repository navigation
Conversation
Replace MicroK8s with Canonical Kubernetes throughout the 12-factor app
tutorials so they use CK8s exclusively, following up on the how-to guide
migration.
- Rework the shared tutorial setup (setup_stable.rst, setup_edge.rst) to
install and bootstrap Canonical Kubernetes (k8s snap), enable
local-storage and ingress, and register the cluster as a Juju cloud with
'juju add-k8s' before bootstrapping.
- Replace the MicroK8s registry push (rockcraft.skopeo copy to
localhost:32000) with a direct containerd image import ('ctr images
import') and reference the image without the registry prefix in the six
framework tutorials and their task.yaml tests.
- Update prose and 'juju status' sample output accordingly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove the MicroK8s options from the manage-web-app-charms how-to guides so they use Canonical Kubernetes exclusively, matching the tutorial migration. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
The six executable task suites still provision MicroK8s, so their CK8s commands cannot run until the test environment is updated.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Migrates the 12-factor tutorials from MicroK8s to Canonical Kubernetes.
Changes:
- Updates shared CK8s setup and Juju registration.
- Replaces registry pushes with containerd image imports.
- Refreshes tutorial instructions and sample output.
File summaries
| File | Summary |
|---|---|
docs/tutorial/kubernetes-charm-spring-boot.rst |
Updates Spring Boot tutorial for CK8s. |
docs/tutorial/kubernetes-charm-go.rst |
Updates Go tutorial for CK8s. |
docs/tutorial/kubernetes-charm-flask.rst |
Updates Flask tutorial for CK8s. |
docs/tutorial/kubernetes-charm-fastapi.rst |
Updates FastAPI tutorial for CK8s. |
docs/tutorial/kubernetes-charm-express.rst |
Updates Express tutorial for CK8s. |
docs/tutorial/kubernetes-charm-django.rst |
Updates Django tutorial for CK8s. |
docs/tutorial/code/spring-boot/task.yaml |
Uses CK8s containerd image import; requires CK8s test-suite provisioning. |
docs/tutorial/code/go/task.yaml |
Uses CK8s containerd image import; requires CK8s test-suite provisioning. |
docs/tutorial/code/flask/task.yaml |
Uses CK8s containerd image import; requires CK8s test-suite provisioning. |
docs/tutorial/code/fastapi/task.yaml |
Uses CK8s containerd image import; requires CK8s test-suite provisioning. |
docs/tutorial/code/expressjs/task.yaml |
Uses CK8s containerd image import; requires CK8s test-suite provisioning. |
docs/tutorial/code/django/task.yaml |
Uses CK8s containerd image import; requires CK8s test-suite provisioning. |
docs/reuse/tutorial/setup_stable.rst |
Defines stable CK8s setup and Juju registration. |
docs/reuse/tutorial/setup_edge.rst |
Defines edge CK8s setup and Juju registration. |
Review details
- Files reviewed: 16/16 changed files
- Comments generated: 6
- Review effort level: Lite
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The tutorial task.yaml files now import images with the k8s snap's containerd (`ctr`) and deploy to a `k8s-cloud` Juju cloud, but the shared docsuite only provisioned MicroK8s. Give docs/tutorial/code/ a dedicated suite that installs the k8s snap, configures the docker.io containerd mirror, bootstraps Canonical Kubernetes, enables local-storage, ingress and the load balancer, and registers k8s-cloud with Juju. The how-to code suite stays on MicroK8s. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Addressed in 49c61e3: the six tutorial task suites no longer inherit the MicroK8s
The how-to code suite ( Note: these suites are |
alithethird
left a comment
There was a problem hiding this comment.
Left some nitpicks, overall looking good.
Address PR review feedback: avoid driving containerd directly (`ctr images import`) in the 12-factor tutorials. Instead deploy a small local OCI registry at localhost:5000 and push rocks to it with `rockcraft.skopeo copy`, mirroring the previous MicroK8s registry flow. - setup_stable.rst / setup_edge.rst: add a "Set up a local registry" section (distribution registry binary as a systemd service + containerd hosts.d config for localhost:5000). - tutorial task.yaml (6 frameworks): push rocks via skopeo and reference images as localhost:5000/<app>:<ver>. - tutorial .rst (6 frameworks): update prose/bullets to the registry and skopeo workflow. - spread.yaml tutorial suite: deploy the registry + hosts.d config in place of the docker.io pull-through mirror block. - Trim heading underlines in the setup files (review nitpick). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…s-ck8s-isd-4330 # Conflicts: # docs/howto/manage-web-app-charms/use-web-app-charm.rst
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Resolve the registry/containerd mismatch, CK8s ingress access setup, and removed MicroK8s guidance.
Review effort: Lite
Findings: 7
Open (8)
Import rocks into containerd instead of pushing to localhost · New Import rocks into containerd instead of pushing to localhost · New Import rocks into containerd instead of pushing to localhost · New Import rocks into containerd instead of pushing to localhost · New Import rocks into containerd instead of pushing to localhost · New Import rocks into containerd instead of pushing to localhost · New Align spread tests with direct containerd image imports · New Restore MicroK8s and Canonical K8s tabs · New
Resolved since last review (6)
This executable tutorial task inherits thedocsuitesetup fromspread.yaml:235-271, which… This executable tutorial task inherits thedocsuitesetup fromspread.yaml:235-271, which… This executable tutorial task inherits thedocsuitesetup fromspread.yaml:235-271, which… This executable tutorial task inherits thedocsuitesetup fromspread.yaml:235-271, which… This executable tutorial task inherits thedocsuitesetup fromspread.yaml:235-271, which… This executable tutorial task inherits thedocsuitesetup fromspread.yaml:235-271, which…
d1f2138 to
9817acc
Compare
There was a problem hiding this comment.
🟡 Changes recommended
The stable and edge setup instructions omit the load-balancer provisioning and loopback DNAT commands required by the documented ingress checks.
2 open findings
8 resolved since last review
Align spread tests with direct containerd image imports Import rocks into containerd instead of pushing to localhost Import rocks into containerd instead of pushing to localhost Import rocks into containerd instead of pushing to localhost Import rocks into containerd instead of pushing to localhost Import rocks into containerd instead of pushing to localhost Import rocks into containerd instead of pushing to localhost Restore MicroK8s and Canonical K8s tabs
🧠 Review effort: Lite
The Canonical Kubernetes ingress is fronted by a LoadBalancer service rather than binding the node's host ports like the MicroK8s add-on, so the documented `curl ... 127.0.0.1` requests could not reach the app. Enable the built-in load balancer with an L2 address pool set to the VM's own IP in the tutorial setup, and resolve the ingress host to that address (`$INGRESS_IP`) instead of the loopback address. Align the spread tutorial suite with the documented commands and drop the test-only loopback DNAT workaround. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com> Signed-off-by: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com>
Remove a stray trailing double-backtick from a `curl` command in the Spring Boot tutorial so the rendered code block can be copied verbatim. Add a release note for the 12-factor tutorial migration to Canonical Kubernetes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Erin Conley <erin.conley@canonical.com> Signed-off-by: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com>
Co-authored-by: Erin Conley <erin.conley@canonical.com> Signed-off-by: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com>
Co-authored-by: Erin Conley <erin.conley@canonical.com> Signed-off-by: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com>
Co-authored-by: Erin Conley <erin.conley@canonical.com> Signed-off-by: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com>
Increase the Multipass VM memory from 4 GB to 8 GB in the shared setup
pages and the per-framework prerequisites to avoid pack errors and I/O
timeouts during the build steps. Add "balancer('s)?" to the custom
wordlist so the load-balancer prose passes the documentation linter.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Django 6.1 requires PostgreSQL 15 or later, but the tutorial deployed postgresql-k8s from the 14/edge channel (PostgreSQL 14), so the charm's startup migration failed with "PostgreSQL 15 or later is required". Deploy postgresql-k8s from 16/stable to match the Django requirement, consistent with the upstream 12-factor Django tutorial. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The registry setup inlined the full Kubernetes manifest as a heredoc, which made the shared setup pages long and hard to read. Move the manifest into docs/reuse/tutorial/registry.yaml and download it with curl in the tutorial, mirroring the upstream 26.04 tutorials. Add a readiness probe so the registry rollout wait reflects actual readiness. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
erinecon
left a comment
There was a problem hiding this comment.
I was able to successfully complete the Django tutorial 🎉
For the other tutorials with a dedicated section to integrate with a database -- I'm consistently seeing a lack of response from the visitors endpoint.
Avoids the ca-certificates.crt staging conflict (canonical/rockcraft#1261) that occurs with the ubuntu@24.04 base. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…tstrap Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The cilium ingress class treats the ImplementationSpecific path / as an exact match, so endpoints other than / returned an empty 404. Use the /.* pattern and give the ingress more time to come up. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
17f29b3 to
05cf1ed
Compare
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com>
… 16 in clearsession Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
I've successfully tested the Flask and Go tutorials 🎉
Since the FastAPI tutorial is using the experimental 26.04 base (due to canonical/rockcraft#1261 preventing the rock from being packed with the "stable" base), I want to hold off on my approval until I've tested locally (or if the Spread test succeeds). TBD in a couple of hours
erinecon
left a comment
There was a problem hiding this comment.
Spread tests are all passing 🎉
Co-authored-by: Alex Lowe <alex.lowe@canonical.com> Signed-off-by: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com>
|
The only things the most recent commit could change have succeeded, so I'm bypassing the requirements and merging so I can cherry-pick this onto the hotfix branch. |
Follow-up to the how-to guide migration (#2743), addressing review feedback that the 12-factor **tutorials** still required MicroK8s. This migrates the tutorials to use Canonical Kubernetes (CK8s) **exclusively** — no MicroK8s alternative. ## Changes **Shared tutorial setup** (`docs/reuse/tutorial/setup_stable.rst`, `setup_edge.rst`) - Install and bootstrap Canonical Kubernetes (`sudo snap install k8s --classic`, `sudo k8s bootstrap`). - Enable `local-storage` (replaces MicroK8s' `hostpath-storage`) and `ingress`. - Enable the built-in `load-balancer` with an L2 address pool set to the VM's own IP. Unlike the MicroK8s ingress add-on, the CK8s ingress is fronted by a `LoadBalancer` service, so a load balancer is required for the ingress to be assigned a reachable address. The tutorial `curl` commands resolve the ingress host to that address (`$INGRESS_IP`) instead of the loopback address. - Register the cluster as a Juju cloud (`sudo k8s config | juju add-k8s ...`), since CK8s isn't autodetected like MicroK8s. - Set up a small local OCI registry on `localhost:5000`. CK8s has no bundled `registry` addon, so the tutorials run the static `distribution` registry as a systemd service and point containerd at it through `/etc/containerd/hosts.d/localhost:5000/hosts.toml`. **Six framework tutorials and their `task.yaml` tests** (Django, Express, FastAPI, Flask, Go, Spring Boot) - Push the rock to the local registry with `rockcraft.skopeo copy` to `localhost:5000`, per reviewer request to use a registry rather than driving containerd directly in a tutorial. - Reference the charm resource image with the `localhost:5000/` prefix. - Update prose and `juju status` sample output for CK8s. **How-to** (`docs/howto/manage-web-app-charms/integrate-web-app-charm.rst`) - Make the load-balancer step Canonical K8s-only, consistent with migrating the 12-factor docs off MicroK8s. **Spread** (`spread.yaml`) - The `docs/tutorial/code/` suite deploys the same local registry and containerd `hosts.d` config so the executable tutorial tests exercise the documented registry workflow on CK8s. - Enable the load balancer and curl the ingress address directly, matching the documented commands (removing the earlier test-only loopback DNAT workaround). ## Validation - Docs build passes with `sphinx-build --fail-on-warning`. -⚠️ The `task.yaml` files are executable spread integration tests. They require a full Multipass + CK8s setup and a self-hosted docs runner, so their end-to-end execution on CK8s — particularly ingress via `nginx-ingress-integrator` — should be validated in CI.



Follow-up to the how-to guide migration (#2743), addressing review feedback that the 12-factor tutorials still required MicroK8s. This migrates the tutorials to use Canonical Kubernetes (CK8s) exclusively — no MicroK8s alternative.
Changes
Shared tutorial setup (
docs/reuse/tutorial/setup_stable.rst,setup_edge.rst)sudo snap install k8s --classic,sudo k8s bootstrap).local-storage(replaces MicroK8s'hostpath-storage) andingress.load-balancerwith an L2 address pool set to the VM's own IP. Unlike the MicroK8s ingress add-on, the CK8s ingress is fronted by aLoadBalancerservice, so a load balancer is required for the ingress to be assigned a reachable address. The tutorialcurlcommands resolve the ingress host to that address ($INGRESS_IP) instead of the loopback address.sudo k8s config | juju add-k8s ...), since CK8s isn't autodetected like MicroK8s.localhost:5000. CK8s has no bundledregistryaddon, so the tutorials run the staticdistributionregistry as a systemd service and point containerd at it through/etc/containerd/hosts.d/localhost:5000/hosts.toml.Six framework tutorials and their
task.yamltests (Django, Express, FastAPI, Flask, Go, Spring Boot)rockcraft.skopeo copytolocalhost:5000, per reviewer request to use a registry rather than driving containerd directly in a tutorial.localhost:5000/prefix.juju statussample output for CK8s.How-to (
docs/howto/manage-web-app-charms/integrate-web-app-charm.rst)Spread (
spread.yaml)docs/tutorial/code/suite deploys the same local registry and containerdhosts.dconfig so the executable tutorial tests exercise the documented registry workflow on CK8s.Validation
sphinx-build --fail-on-warning.task.yamlfiles are executable spread integration tests. They require a full Multipass + CK8s setup and a self-hosted docs runner, so their end-to-end execution on CK8s — particularly ingress vianginx-ingress-integrator— should be validated in CI.make lint && make test.