[Backport release-1.31] Overhaul docs templating

.github/workflows/publish-docs.yml

@@ -15,14 +15,38 @@ jobs:
   build:
     name: Deploy docs
     runs-on: ubuntu-24.04
+
+    permissions:
+      contents: write
+
     steps:
       - name: Checkout k0s
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Prepare build environment
-        run: .github/workflows/prepare-build-env.sh
+        env:
+          PYTHONPATH: ${{ github.workspace }}/docs/mkdocs_modules
+        run: |
+          .github/workflows/prepare-build-env.sh
+
+          if [ "$GITHUB_REF" = refs/heads/main ]; then
+            kubernetesVersion="$(./vars.sh kubernetes_version)"
+            k0sVersion="v$kubernetesVersion+head"
+          elif [ "$GITHUB_REF_TYPE" = tag ]; then
+            k0sVersion="$GITHUB_REF_NAME"
+          fi
+
+          [ -n "${k0sVersion-}" ] || {
+            echo Failed to determine k0s version! 1>&2
+            exit 1
+          }
+
+          cat <<EOF | tee "$GITHUB_ENV"
+          PYTHONPATH=$PYTHONPATH
+          K0S_VERSION=$k0sVersion
+          EOF
 
       - name: Set up Python ${{ env.PYTHON_VERSION }}
         uses: actions/setup-python@v5
@@ -56,9 +80,8 @@ jobs:
       # This deploys the current docs into gh-pages/head on merges to main
       # The old "main" gets deleted if it exists, head is more descriptive
       - name: mike deploy head
-        if: contains(github.ref, 'refs/heads/main')
-        run: |
-          KUBERNETES_VERSION="$(./vars.sh kubernetes_version)" mike deploy --push head
+        if: github.ref == 'refs/heads/main'
+        run: mike deploy --push head
 
       # If a release has been published, deploy it as a new version
       - name: mike deploy new version
@@ -67,10 +90,7 @@ jobs:
           github.event.action == 'published' &&
           !github.event.release.draft &&
           !github.event.release.prerelease
-        env:
-          VERSION: ${{ github.event.release.tag_name }}
-        run: |
-          KUBERNETES_VERSION="$(./vars.sh kubernetes_version)" mike deploy --push "$VERSION"
+        run: mike deploy --push "$K0S_VERSION"
 
       - name: Update mike version aliases
         if: github.repository == 'k0sproject/k0s'

Makefile

@@ -295,7 +295,8 @@ docs-serve-dev: DOCS_DEV_PORT ?= 8000
 docs-serve-dev:
 	$(MAKE) -C docs .docker-image.serve-dev.stamp
 	docker run --rm \
-	  -e KUBERNETES_VERSION='$(kubernetes_version)' \
+	  -e PYTHONPATH=/k0s/docs/mkdocs_modules \
+	  -e K0S_VERSION=$(VERSION) \
 	  -v "$(CURDIR):/k0s:ro" \
 	  -p '$(DOCS_DEV_PORT):8000' \
 	  k0sdocs.docker-image.serve-dev

docs/.gitignore

@@ -1,6 +1,7 @@
 # Keep in sync with the plugins.exclude section in mkdocs.yml as MkDocs will
 # copy over everything despite hidden files.
 
+__pycache__/
 /*.etag
 /.docker-image.*
 /k0s

docs/Dockerfile.serve-dev

@@ -5,7 +5,7 @@ FROM python:${PYTHON_IMAGE_VERSION} as builder
 # Prepare Python virtual env
 ENV PYTHONUNBUFFERED 1
 RUN \
-  apk add --no-cache python3 \
+  apk add --no-cache make python3 \
   && python3 -m venv /mkdocs/venv
 
 # Copy requirements.txt

docs/Makefile

@@ -18,7 +18,7 @@ TARGET_VERSION ?= latest
 # gives: "Error: The 'docs_dir' should not be the parent directory of the config file."
 # even if docs_dir is "."
 docs: .require-mkdocs cli
-	cd .. && KUBERNETES_VERSION=$(kubernetes_version) mkdocs build --strict
+	cd .. && PYTHONPATH=$(CURDIR)/mkdocs_modules K0S_VERSION=$$('$(k0s_binary_path)/$(k0s_binary)' version) mkdocs build --strict
 
 .PHONY: .require-mkdocs
 .require-mkdocs:
@@ -41,9 +41,9 @@ endif
 
 .PHONY: k0s k0s.exe
 ifeq ($(TARGET_VERSION),local)
-cli: k0s_binary_path := $(abspath ..)
+docs cli: k0s_binary_path := $(abspath ..)
 else
-cli: k0s_binary_path := $(abspath .)
+docs cli: k0s_binary_path := $(abspath .)
 k0s k0s.exe::
 	[ ! -f '$@.etag' ] || { if [ ! -f '$@' ] || [ '$@.etag' -ot '$@' ]; then rm -- '$@.etag'; fi }
 	touch -- '$@.etag'
@@ -62,10 +62,10 @@ endif
 .PHONY: cli
 ifeq ($(detected_OS),windows)
 cli: k0s.exe
-cli: k0s_binary = k0s.exe
+docs cli: k0s_binary = k0s.exe
 else
 cli: k0s
-cli: k0s_binary = k0s
+docs cli: k0s_binary = k0s
 endif
 cli:
 	rm -rf cli

docs/airgap-install.md

@@ -15,7 +15,7 @@ In order to create your own image bundle, you need:
   the [containerd Getting Started Guide] for more information.
 
 [Quick Start Guide]: install.md
-[containerd Getting Started Guide]: https://github.com/containerd/containerd/blob/v1.7.27/docs/getting-started.md
+[containerd Getting Started Guide]: https://github.com/containerd/containerd/blob/v{{{ build_var('containerd_version') }}}/docs/getting-started.md
 
 ## 1. Create your own image bundle (optional)
 
@@ -71,7 +71,7 @@ metadata:
   name: k0s-cluster
 spec:
   k0s:
-    version: {{{ extra.k8s_version }}}+k0s.0
+    version: {{{ k0s_version }}}
   hosts:
     - role: controller
       ssh:

docs/autopilot-multicommand.md

@@ -62,20 +62,20 @@ processed by **autopilot**.
  6:  spec:
  7:    commands:
  8:    - airgapupdate:
- 9:        version: v{{{ extra.k8s_version }}}+k0s.0
+ 9:        version: {{{ k0s_version }}}
 10:        platforms:
 11:          linux-amd64:
-12:            url: https://github.com/k0sproject/k0s/releases/download/v{{{ extra.k8s_version }}}+k0s.0/k0s-airgap-bundle-v{{{ extra.k8s_version }}}+k0s.0-amd64
+12:            url: https://github.com/k0sproject/k0s/releases/download/{{{ k0s_version }}}/k0s-airgap-bundle-{{{ k0s_version }}}-amd64
 13:        workers:
 14:          discovery:
 15:            static:
 16:              nodes:
 17:              - worker0
 18:    - k0supdate:
-19:        version: v{{{ extra.k8s_version }}}+k0s.0
+19:        version: {{{ k0s_version }}}
 20:        platforms:
 21:          linux-amd64:
-22:            url: https://github.com/k0sproject/k0s/releases/download/v{{{ extra.k8s_version }}}+k0s.0/k0s-v{{{ extra.k8s_version }}}+k0s.0-amd64
+22:            url: https://github.com/k0sproject/k0s/releases/download/{{{ k0s_version }}}/k0s-{{{ k0s_version }}}-amd64
 23:        targets:
 24:          controllers:
 25:            discovery:

docs/autopilot.md

@@ -103,10 +103,10 @@ spec:
 
   commands:
     - k0supdate:
-        version: v{{{ extra.k8s_version }}}+k0s.0
+        version: {{{ k0s_version }}}
         platforms:
           linux-amd64:
-            url: https://github.com/k0sproject/k0s/releases/download/v{{{ extra.k8s_version }}}+k0s.0/k0s-v{{{ extra.k8s_version }}}+k0s.0-amd64
+            url: https://github.com/k0sproject/k0s/releases/download/{{{ k0s_version }}}/k0s-{{{ k0s_version }}}-amd64
             sha256: '0000000000000000000000000000000000000000000000000000000000000000'
         targets:
           controllers:

docs/configuration.md

@@ -484,8 +484,8 @@ Nodes under the `images` key all have the same basic structure:
 spec:
   images:
     coredns:
-      image: quay.io/coredns/coredns
-      version: v1.7.0
+      image: {{{ src_var('CoreDNSImage') }}}
+      version: {{{ src_var('CoreDNSImageVersion') }}}
 ```
 
 If you want the list of default images and their versions to be included, use `k0s config create --include-images`.
@@ -510,23 +510,26 @@ If `spec.images.default_pull_policy` is set and not empty, it will be used as a
 
 #### Image example
 
+{% set cali_ver = src_var('CalicoComponentImagesVersion') -%}
+{% set metrics_ver = src_var('MetricsImageVersion') -%}
+
 ```yaml
 images:
-  repository: "my.own.repo"
+  repository: airgap-repo.local
   calico:
     kubecontrollers:
-      image: quay.io/k0sproject/calico-kube-controllers
-      version: v3.27.3-0
+      image: repo.acme.corp/k0sproject/calico-kube-controllers
+      version: {{{ cali_ver }}}
   metricsserver:
-    image: registry.k8s.io/metrics-server/metrics-server
-    version: v0.7.2
+    image: repo.acme.corp/k0sproject/metrics-server
+    version: {{{ metrics_ver }}}
 ```
 
 In the runtime the image names are calculated as
-`my.own.repo/k0sproject/calico-kube-controllers:v3.27.3-0` and
-`my.own.repo/metrics-server/metrics-server:v0.7.2`. This only affects the the
-images pull location, and thus omitting an image specification here will not
-disable component deployment.
+`airgap-repo.local/k0sproject/calico-kube-controllers:{{{ cali_ver }}}` and
+`airgap-repo.local/k0sproject/metrics-server:{{{ metrics_ver }}}`. This only
+affects the the images pull location, and thus omitting an image specification
+here will not disable component deployment.
 
 ### `spec.extensions.helm`
 

docs/cplb.md

@@ -153,7 +153,7 @@ spec:
     k0sBinaryPath: /opt/k0s
     uploadBinary: true
   k0s:
-    version: v{{{ extra.k8s_version }}}+k0s.0
+    version: {{{ k0s_version }}}
     config:
       spec:
         api:
@@ -279,7 +279,7 @@ level=info msg="[ssh] worker-1.k0s.lab:22: waiting for node to become ready"
 level=info msg="==> Running phase: Release exclusive host lock"
 level=info msg="==> Running phase: Disconnect from hosts"
 level=info msg="==> Finished in 2m20s"
-level=info msg="k0s cluster version v{{{ extra.k8s_version }}}+k0s.0  is now installed"
+level=info msg="k0s cluster version {{{ k0s_version }}} is now installed"
 level=info msg="Tip: To access the cluster you can now fetch the admin kubeconfig using:"
 level=info msg="     k0sctl kubeconfig"
 ```
@@ -297,9 +297,9 @@ All three worker nodes are ready:
 ```console
 $ kubectl get nodes
 NAME                   STATUS   ROLES           AGE     VERSION
-worker-0.k0s.lab       Ready    <none>          8m51s   v{{{ extra.k8s_version }}}+k0s
-worker-1.k0s.lab       Ready    <none>          8m51s   v{{{ extra.k8s_version }}}+k0s
-worker-2.k0s.lab       Ready    <none>          8m51s   v{{{ extra.k8s_version }}}+k0s
+worker-0.k0s.lab       Ready    <none>          8m51s   {{{ k8s_version }}}+k0s
+worker-1.k0s.lab       Ready    <none>          8m51s   {{{ k8s_version }}}+k0s
+worker-2.k0s.lab       Ready    <none>          8m51s   {{{ k8s_version }}}+k0s
 ```
 
 Each controller node has a dummy interface with the VIP and /32 netmask,
@@ -355,7 +355,7 @@ And the cluster will be working normally:
 ```console
 $ kubectl get nodes
 NAME                   STATUS   ROLES           AGE     VERSION
-worker-0.k0s.lab       Ready    <none>          8m51s   v{{{ extra.k8s_version }}}+k0s
-worker-1.k0s.lab       Ready    <none>          8m51s   v{{{ extra.k8s_version }}}+k0s
-worker-2.k0s.lab       Ready    <none>          8m51s   v{{{ extra.k8s_version }}}+k0s
+worker-0.k0s.lab       Ready    <none>          8m51s   {{{ k8s_version }}}+k0s
+worker-1.k0s.lab       Ready    <none>          8m51s   {{{ k8s_version }}}+k0s
+worker-2.k0s.lab       Ready    <none>          8m51s   {{{ k8s_version }}}+k0s
 ```

docs/install.md

@@ -63,7 +63,7 @@ Though the Quick Start material is written for Debian/Ubuntu, you can use it for
 
     ```shell
     $ sudo k0s status
-    Version: v{{{ extra.k8s_version }}}+k0s.0
+    Version: {{{ k0s_version }}}
     Process ID: 436
     Role: controller
     Workloads: true
@@ -79,7 +79,7 @@ Though the Quick Start material is written for Debian/Ubuntu, you can use it for
     ```shell
     $ sudo k0s kubectl get nodes
     NAME   STATUS   ROLES    AGE    VERSION
-    k0s    Ready    <none>   4m6s   v{{{ extra.k8s_version }}}+k0s
+    k0s    Ready    <none>   4m6s   {{{ k8s_version }}}+k0s
     ```
 
 ## Uninstall k0s

docs/k0s-in-docker.md

@@ -10,10 +10,12 @@ You will require a [Docker environment](https://docs.docker.com/get-docker/) run
 
 The k0s containers are published both on Docker Hub and GitHub. For reasons of simplicity, the examples given here use Docker Hub (GitHub requires a separate authentication that is not covered). Alternative links include:
 
-- docker.io/k0sproject/k0s:v{{{ extra.k8s_version }}}-k0s.0
-- ghcr.io/k0sproject/k0s:v{{{ extra.k8s_version }}}-k0s.0
+- docker.io/k0sproject/k0s:{{{ k0s_docker_version }}}
+- ghcr.io/k0sproject/k0s:{{{ k0s_docker_version }}}
 
-**Note:** Due to Docker Hub tag validation scheme, we have to use `-` as the k0s version separator instead of the usual `+`. So for example k0s version `v{{{ extra.k8s_version }}}+k0s.0` is tagged as `docker.io/k0sproject/k0s:v{{{ extra.k8s_version }}}-k0s.0`.
+**Note:** Due to Docker's tag validation scheme, `-` is used as the k0s version
+separator instead of the usual `+`. For example, k0s version `{{{ k0s_version
+}}}` is tagged as `docker.io/k0sproject/k0s:{{{ k0s_docker_version }}}`.
 
 ## Start k0s
 
@@ -22,7 +24,7 @@ The k0s containers are published both on Docker Hub and GitHub. For reasons of s
 You can run your own k0s in Docker:
 
 ```sh
-docker run -d --name k0s --hostname k0s --privileged -v /var/lib/k0s -p 6443:6443 --cgroupns=host docker.io/k0sproject/k0s:v{{{ extra.k8s_version }}}-k0s.0 -- k0s controller --enable-worker
+docker run -d --name k0s --hostname k0s --privileged -v /var/lib/k0s -p 6443:6443 --cgroupns=host docker.io/k0sproject/k0s:{{{ k0s_docker_version }}} -- k0s controller --enable-worker
 ```
 
 **Note:** This command starts k0s with a worker. You may disable the worker by running it without the flag `--enable-worker`
@@ -42,7 +44,7 @@ For each required worker:
 2. Run the container to create and join the new worker:
 
     ```sh
-    docker run -d --name k0s-worker1 --hostname k0s-worker1 --privileged -v /var/lib/k0s --cgroupns=host  docker.io/k0sproject/k0s:v{{{ extra.k8s_version }}}-k0s.0 k0s worker $token
+    docker run -d --name k0s-worker1 --hostname k0s-worker1 --privileged -v /var/lib/k0s --cgroupns=host  docker.io/k0sproject/k0s:{{{ k0s_docker_version }}} k0s worker $token
     ```
 
 ### 3. Access your cluster
@@ -64,7 +66,7 @@ version: "3.9"
 services:
   k0s:
     container_name: k0s
-    image: docker.io/k0sproject/k0s:v{{{ extra.k8s_version }}}-k0s.0
+    image: docker.io/k0sproject/k0s:{{{ k0s_docker_version }}}
     command: k0s controller --config=/etc/k0s/config.yaml --enable-worker
     hostname: k0s
     privileged: true

docs/k0s-multi-node.md

@@ -22,15 +22,15 @@ curl --proto '=https' --tlsv1.2 -sSf https://get.k0s.sh | sudo sh
 
 The download script accepts the following environment variables:
 
-| Variable                    | Purpose                                                              |
-|:----------------------------|:---------------------------------------------------------------------|
-| `K0S_VERSION=v{{{ extra.k8s_version }}}+k0s.0` | Select the version of k0s to be installed         |
-| `DEBUG=true`                                   | Output commands and their arguments at execution. |
+| Variable                          | Purpose                                           |
+|:----------------------------------|:--------------------------------------------------|
+| `K0S_VERSION={{{ k0s_version }}}` | Select the version of k0s to be installed         |
+| `DEBUG=true`                      | Output commands and their arguments at execution. |
 
 **Note**: If you require environment variables and use sudo, you can do:
 
 ```shell
-curl --proto '=https' --tlsv1.2 -sSf https://get.k0s.sh | sudo K0S_VERSION=v{{{ extra.k8s_version }}}+k0s.0 sh
+curl --proto '=https' --tlsv1.2 -sSf https://get.k0s.sh | sudo K0S_VERSION={{{ k0s_version }}} sh
 ```
 
 ### 2. Bootstrap a controller node
@@ -126,7 +126,7 @@ To get general information about your k0s instance's status:
 ```
 
 ```shell
-Version: v{{{ extra.k8s_version }}}+k0s.0
+Version: {{{ k0s_version }}}
 Process ID: 2769
 Parent Process ID: 1
 Role: controller
@@ -144,7 +144,7 @@ sudo k0s kubectl get nodes
 
 ```shell
 NAME   STATUS   ROLES    AGE    VERSION
-k0s    Ready    <none>   4m6s   v{{{ extra.k8s_version }}}+k0s
+k0s    Ready    <none>   4m6s   {{{ k8s_version }}}+k0s
 ```
 
 You can also access your cluster easily with [Lens](https://k8slens.dev/), simply by copying the kubeconfig and pasting it to Lens:

docs/k0sctl-install.md

@@ -85,8 +85,8 @@ INFO [ssh] 10.0.0.1:22: discovered 10.12.18.133 as private address
 INFO ==> Running phase: Validate hosts
 INFO ==> Running phase: Gather k0s facts
 INFO ==> Running phase: Download K0s on the hosts
-INFO [ssh] 10.0.0.2:22: downloading k0s 0.11.0
-INFO [ssh] 10.0.0.1:22: downloading k0s 0.11.0
+INFO [ssh] 10.0.0.2:22: downloading k0s {{{ k0s_version }}}
+INFO [ssh] 10.0.0.1:22: downloading k0s {{{ k0s_version }}}
 INFO ==> Running phase: Configure K0s
 WARN [ssh] 10.0.0.1:22: generating default configuration
 INFO [ssh] 10.0.0.1:22: validating configuration
@@ -103,7 +103,7 @@ INFO [ssh] 10.0.0.2:22: starting service
 INFO [ssh] 10.0.0.2:22: waiting for node to become ready
 INFO ==> Running phase: Disconnect from hosts
 INFO ==> Finished in 2m2s
-INFO k0s cluster version 0.11.0 is now installed
+INFO k0s cluster version {{{ k0s_version }}} is now installed
 INFO Tip: To access the cluster you can now fetch the admin kubeconfig using:
 INFO      k0sctl kubeconfig
 ```