[Backport release-1.32] 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

@@ -306,7 +306,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.1
+    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.1
+ 9:        version: {{{ k0s_version }}}
 10:        platforms:
 11:          linux-amd64:
-12:            url: https://github.com/k0sproject/k0s/releases/download/v{{{ extra.k8s_version }}}+k0s.1/k0s-airgap-bundle-v{{{ extra.k8s_version }}}+k0s.1-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.1
+19:        version: {{{ k0s_version }}}
 20:        platforms:
 21:          linux-amd64:
-22:            url: https://github.com/k0sproject/k0s/releases/download/v{{{ extra.k8s_version }}}+k0s.1/k0s-v{{{ extra.k8s_version }}}+k0s.1-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.1
+        version: {{{ k0s_version }}}
         platforms:
           linux-amd64:
-            url: https://github.com/k0sproject/k0s/releases/download/v{{{ extra.k8s_version }}}+k0s.1/k0s-v{{{ extra.k8s_version }}}+k0s.1-amd64
+            url: https://github.com/k0sproject/k0s/releases/download/{{{ k0s_version }}}/k0s-{{{ k0s_version }}}-amd64
             sha256: '0000000000000000000000000000000000000000000000000000000000000000'
         targets:
           controllers:

docs/compose.yaml

@@ -1,6 +1,6 @@
 services:
   k0s-controller:
-    image: docker.io/k0sproject/k0s:v{{{extra.k8s_version}}}-k0s.1
+    image: docker.io/k0sproject/k0s:{{{ k0s_docker_version }}}
     container_name: k0s-controller
     hostname: k0s-controller
     network_mode: bridge # other modes are unsupported
@@ -13,10 +13,10 @@ services:
     tmpfs:
       - /run # this is where k0s stores runtime data
     cap_add:
-     - sys_admin
-     - net_admin
-     - sys_ptrace
-     - sys_resource
+      - sys_admin
+      - net_admin
+      - sys_ptrace
+      - sys_resource
     device_cgroup_rules:
       - c 1:11 r # required by kubelets OOM watcher
     configs:

docs/configuration.md

@@ -488,8 +488,8 @@ Nodes under the `images` key all have the same basic structure:
 spec:
   images:
     coredns:
-      image: quay.io/k0sproject/coredns
-      version: 1.12.2
+      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`.
@@ -514,23 +514,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

@@ -207,7 +207,7 @@ spec:
     k0sBinaryPath: /opt/k0s
     uploadBinary: true
   k0s:
-    version: v{{{ extra.k8s_version }}}+k0s.1
+    version: {{{ k0s_version }}}
     config:
       spec:
         network:
@@ -331,7 +331,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.1  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"
 ```
@@ -349,9 +349,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
 ```
 
 Only one controller has the VIP:
@@ -392,9 +392,9 @@ 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
 ```
 
 ## Troubleshooting

docs/install.md

@@ -70,7 +70,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.1
+    Version: {{{ k0s_version }}}
     Process ID: 436
     Role: controller
     Workloads: true
@@ -86,7 +86,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

@@ -13,13 +13,12 @@ registry. For simplicity, the examples given here use Docker Hub (GitHub
 requires separate authentication, which is not covered here). The image names
 are as follows:
 
-- `docker.io/k0sproject/k0s:v{{{extra.k8s_version}}}-k0s.1`
-- `ghcr.io/k0sproject/k0s:v{{{extra.k8s_version}}}-k0s.1`
+- `docker.io/k0sproject/k0s:{{{ k0s_docker_version }}}`
+- `ghcr.io/k0sproject/k0s:{{{ k0s_docker_version }}}`
 
 **Note:** Due to Docker's tag validation scheme, `-` is used as the k0s version
-separator instead of the usual `+`. For example, k0s version
-`v{{{extra.k8s_version}}}+k0s.1` is tagged as
-`docker.io/k0sproject/k0s:v{{{extra.k8s_version}}}-k0s.1`.
+separator instead of the usual `+`. For example, k0s version `{{{ k0s_version
+}}}` is tagged as `docker.io/k0sproject/k0s:{{{ k0s_docker_version }}}`.
 
 ## Start k0s
 
@@ -35,7 +34,7 @@ docker run -d --name k0s-controller --hostname k0s-controller \
   --tmpfs /run `# this is where k0s stores runtime data` \
   --privileged `# this is the easiest way to enable container-in-container workloads` \
   -p 6443:6443 `# publish the Kubernetes API server port` \
-  docker.io/k0sproject/k0s:v{{{extra.k8s_version}}}-k0s.1
+  docker.io/k0sproject/k0s:{{{ k0s_docker_version }}}
 ```
 
 Explanation of command line arguments:
@@ -54,7 +53,7 @@ Explanation of command line arguments:
   privileges.
 - `-p 6443:6443` exposes the container's Kubernetes API server port 6443 to the
   host, allowing you to interact with the cluster externally.
-- `docker.io/k0sproject/k0s:v{{{ extra.k8s_version }}}-k0s.1` is the name of the
+- `docker.io/k0sproject/k0s:{{{ k0s_docker_version }}}` is the name of the
   k0s image to run.
 
 By default, the k0s image starts a k0s controller with worker components enabled
@@ -74,7 +73,7 @@ docker run -d --name k0s-controller --hostname k0s-controller \
   --tmpfs /run `# this is where k0s stores runtime data` \
   --tmpfs /tmp `# allow writing temporary files` \
   -p 6443:6443 `# publish the Kubernetes API server port` \
-  docker.io/k0sproject/k0s:v{{{extra.k8s_version}}}-k0s.1 \
+  docker.io/k0sproject/k0s:{{{ k0s_docker_version }}} \
   k0s controller
 ```
 
@@ -100,7 +99,7 @@ application containers to separate workers.
      -v /var/lib/k0s -v /var/log/pods `# this is where k0s stores its data` \
      --tmpfs /run `# this is where k0s stores runtime data` \
      --privileged `# this is the easiest way to enable container-in-container workloads` \
-     docker.io/k0sproject/k0s:v{{{extra.k8s_version}}}-k0s.1 \
+     docker.io/k0sproject/k0s:{{{ k0s_docker_version }}} \
      k0s worker $token
    ```
 
@@ -129,7 +128,7 @@ application containers to separate workers.
      --cap-add net_admin \
      --cap-add sys_ptrace \
      --cap-add sys_resource \
-     docker.io/k0sproject/k0s:v{{{extra.k8s_version}}}-k0s.1 \
+     docker.io/k0sproject/k0s:{{{ k0s_docker_version }}} \
      k0s worker "$token"
    ```