docs(cos-lite): add details to prerequisites, link strict-install docs#348
Merged
Conversation
mmkay
approved these changes
May 15, 2026
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue
Following the cos-lite tutorial from a fresh Ubuntu environment (e.g. a default Multipass VM) fails at two points:
juju bootstrap microk8serrors out withjuju "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.metallbstep depends onjq, which is not preinstalled on Ubuntu.IPADDRends up empty andmicrok8s 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:
snap_microk8sgroup membership step into a{dropdown}so the prereqs stay short while the command remains accessible.jqup front (needed by themetallbstep); clarify it's installed on the machine running the Juju client.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-supportand 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 withsnap_. The classic MicroK8s snap uses the unprefixedmicrok8sgroup, and users following the upstreamgetting-startedpage often add themselves there by mistake.snap_microk8sis currently only documented on the Juju "local testing and development" page; an upstream issue againstinstall-strictto 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):
snap_microk8sdropdown to add your user to the group, thensudo apt-get install -y jq.juju bootstrap microk8ssucceeds without the strict-confinement error.IPADDRis non-empty andmicrok8s enable metallb:$IPADDR-$IPADDRsucceeds.juju deploy cos-lite --trustand wait forjuju statusto show all unitsactive/idle.juju run traefik/0 show-proxied-endpointsand 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:
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