Skip to content

docs(cos-lite): add details to prerequisites, link strict-install docs#348

Merged
mmkay merged 2 commits into
mainfrom
cos-lite-microk8s-doc-fixes-for-main
May 15, 2026
Merged

docs(cos-lite): add details to prerequisites, link strict-install docs#348
mmkay merged 2 commits into
mainfrom
cos-lite-microk8s-doc-fixes-for-main

Conversation

@iamsharduld
Copy link
Copy Markdown
Contributor

Issue

Following the cos-lite tutorial from a fresh Ubuntu environment (e.g. a default Multipass VM) fails at two points:

  1. juju bootstrap microk8s errors out with juju "3.6.x" can only work with strictly confined microk8s. The tutorial previously deferred to a "Typical setup using snaps" link that, in practice, leads users to install MicroK8s with --classic, which Juju 3.x cannot read the kubeconfig of.
  2. The metallb step depends on jq, which is not preinstalled on Ubuntu. IPADDR ends up empty and microk8s enable metallb:- fails with an unclear error.

Solution

Rewrite the Prerequisites section as a short bullet list of assumed state, with setup deferred to authoritative external docs:

The rest of the tutorial (Introduction, Configure MicroK8s, bundle deployment, overlays, Terraform, dashboards) is unchanged.

Context

Why strict MicroK8s. Snap confinement is the underlying reason for the bootstrap failure. Strict snaps run in a sandboxed view of the filesystem and can only see paths granted via snap interfaces; classic snaps are unconfined. Juju 3.x ships strict, so it can only resolve a MicroK8s kubeconfig when MicroK8s is also strict and the relevant interfaces (kubernetes-support and credential content-sharing) are wired between them. There is no generic strict↔classic bridge, which is why the failure surfaces as a missing-file error rather than a permissions error.

Why snap_microk8s. The group name follows the Canonical convention of prefixing system groups created by strict snaps with snap_. The classic MicroK8s snap uses the unprefixed microk8s group, and users following the upstream getting-started page often add themselves there by mistake. snap_microk8s is currently only documented on the Juju "local testing and development" page; an upstream issue against install-strict to document it there will be filed as a follow-up.

References

Testing Instructions

On a fresh Ubuntu environment (Multipass VM with 4 CPU / 8 GB RAM / 40 GB disk recommended):

  1. Follow the updated Prerequisites: install Juju and a strictly confined MicroK8s per the linked guides, expand the snap_microk8s dropdown to add your user to the group, then sudo apt-get install -y jq.
  2. Confirm juju bootstrap microk8s succeeds without the strict-confinement error.
  3. Run through Configure MicroK8s; confirm IPADDR is non-empty and microk8s enable metallb:$IPADDR-$IPADDR succeeds.
  4. Run juju deploy cos-lite --trust and wait for juju status to show all units active/idle.
  5. Run juju run traefik/0 show-proxied-endpoints and confirm proxied URLs are returned.

Upgrade Notes

Users with an existing classic MicroK8s installation must reinstall from a strict channel before the tutorial will work with Juju 3.x:

sudo snap remove microk8s
sudo snap install microk8s --channel=<k8s-version>-strict/stable
sudo usermod -a -G snap_microk8s $USER
newgrp snap_microk8s

Any existing Juju controllers bootstrapped against the classic MicroK8s will need to be re-bootstrapped against the new strict installation. Workloads deployed under the old controller are not migrated automatically.

Checklist

  • I have added or updated relevant documentation.
  • PR title makes an appropriate release note and follows conventional commits syntax.
  • Merge target is the correct branch, and relevant tandem backport PRs opened.

@iamsharduld iamsharduld requested a review from sed-i May 15, 2026 10:39
@iamsharduld iamsharduld requested a review from a team as a code owner May 15, 2026 10:39
@mmkay mmkay merged commit cd9231c into main May 15, 2026
5 checks passed
@mmkay mmkay deleted the cos-lite-microk8s-doc-fixes-for-main branch May 15, 2026 11:42
@mmkay mmkay restored the cos-lite-microk8s-doc-fixes-for-main branch May 15, 2026 11:42
MichaelThamm pushed a commit that referenced this pull request May 20, 2026
#348)

* docs(cos-lite): add details to prerequisites, link strict-install docs

* added snap_microk8s to custom_wordlist.txt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants