diff --git a/docs/skills/k0s-sysext-ops.md b/docs/skills/k0s-sysext-ops.md index 7b806f80..07b744b8 100644 --- a/docs/skills/k0s-sysext-ops.md +++ b/docs/skills/k0s-sysext-ops.md @@ -33,8 +33,9 @@ systemd-sysext merge # 3. Seed declarative manifest stacks into /var/lib/k0s/manifests/ systemd-tmpfiles --create /usr/lib/tmpfiles.d/k0s-manifests.conf -# 4. Start the controller service +# 4. Start the controller and agent services systemctl enable --now k0scontroller.service +systemctl enable --now kc-agent.service ``` ## Verifying Manifest Reconciliation diff --git a/docs/skills/k0s-sysext.md b/docs/skills/k0s-sysext.md index 1e38f94c..8442ec9b 100644 --- a/docs/skills/k0s-sysext.md +++ b/docs/skills/k0s-sysext.md @@ -44,7 +44,8 @@ Design choices: `systemd-tmpfiles`. k0s's internal manifest deployer automatically reconciles them. - **Helm and autopilot disabled.** `--disable-components=helm,autopilot` ensures zero runtime Helm dependencies and prevents single-node controlnode timeout loops. - **Flatcar sysext pattern.** The extension uses `ID=_any` in its release metadata so it merges on any host image. -- **First-boot background activation.** `k0s-first-boot.service` copies `/var/lib/k0s/k0s.raw` to `/run/extensions/k0s.raw`, merges the sysext, seeds declarative manifest stacks via `systemd-tmpfiles`, and enables `k0scontroller.service` on boot without holding up system startup. +- **First-boot background activation.** `k0s-first-boot.service` copies `/var/lib/k0s/k0s.raw` to `/run/extensions/k0s.raw`, merges the sysext, seeds declarative manifest stacks via `systemd-tmpfiles`, and enables `k0scontroller.service` and `kc-agent.service` on boot without holding up system startup. +- **Local cluster auto-onboarding.** `kc-agent.service` automatically connects KubeStellar Console to the local k0s cluster using `/var/lib/k0s/pki/admin.conf` on first boot. - **OTA delivery.** A k0s component `systemd-sysupdate` transfer file (`70-k0s.transfer`) is installed in the base OS so hosts can pull new k0s sysext releases from GitHub Releases without updating the root or UKI. @@ -54,9 +55,12 @@ Design choices: | Path | Purpose | |------|---------| | `include/k0s.yml` | **Single source of truth for the k0s version axis** (`%{k0s-upstream-tag}`, `%{k0s-version}`). | +| `include/kc-agent.yml` | Single source of truth for the `kc-agent` version axis. | | `elements/k0s/k0s-bin.bst` | Pins the upstream `k0s` binary SHA256; the release URL is derived from `include/k0s.yml`. | +| `elements/k0s/kc-agent-bin.bst` | Pins the upstream `kc-agent` binary SHA256; release URL derived from `include/kc-agent.yml`. | | `elements/oci/k0s-sysext.bst` | Builds the EROFS sysext image (`k0s-.raw`). | | `files/k0s/sysext/k0scontroller.service` | systemd unit for the k0s single-node controller/worker. Not enabled by default. | +| `files/k0s/sysext/kc-agent.service` | systemd unit for `kc-agent` connecting console to `/var/lib/k0s/pki/admin.conf`. | | `files/k0s/sysext/extension-release.k0s` | Static sysext identity (`ID=_any`); `VERSION_ID=`/`ARCHITECTURE=` are appended at build time. | | `files/k0s/sysext/k0s-manifests.conf` | tmpfiles rule that copies declarative stacks to `/var/lib/k0s/manifests/`. | | `files/k0s/manifests/argocd/` | Raw YAML manifests for Argo CD. | diff --git a/elements/k0s/kc-agent-bin.bst b/elements/k0s/kc-agent-bin.bst new file mode 100644 index 00000000..d727a016 --- /dev/null +++ b/elements/k0s/kc-agent-bin.bst @@ -0,0 +1,32 @@ +kind: manual +description: | + Import the upstream kc-agent release binary. + + kc-agent connects the KubeStellar Console browser session to the local + k0s cluster via WebSocket, reading /var/lib/k0s/pki/admin.conf. + +(@): include/kc-agent.yml + +build-depends: + # Base runtime providing /bin/sh and install in the sandbox. + - base/base-stack.bst + +variables: + # Do not try to strip the pre-built upstream binary. + strip-binaries: "" + +sources: + - kind: tar + url: github:kubestellar/console/releases/download/v%{kc-agent-version}/kc-agent_%{kc-agent-version}_linux_amd64.tar.gz + ref: 052b80bd0700f1c7e22ed5d6ad7547a45d6441d6a2cd40609fed1e69bf592df2 + +config: + install-commands: + - | + if [ "%{arch}" != "x86_64" ]; then + echo "ERROR: elements/k0s/kc-agent-bin.bst pins the upstream kc-agent amd64 binary;" >&2 + echo " arch=%{arch} has no pinned source. Add an arch-conditional" >&2 + echo " source before building kc-agent for %{arch}." >&2 + exit 1 + fi + - install -D -m 0755 kc-agent "%{install-root}/usr/bin/kc-agent" diff --git a/elements/oci/k0s-sysext.bst b/elements/oci/k0s-sysext.bst index dc5bcdbc..61e5d80f 100644 --- a/elements/oci/k0s-sysext.bst +++ b/elements/oci/k0s-sysext.bst @@ -19,6 +19,9 @@ build-depends: - filename: k0s/k0s-bin.bst config: location: / + - filename: k0s/kc-agent-bin.bst + config: + location: / sources: - kind: local @@ -65,8 +68,13 @@ config: cp -a /usr/bin/k0s sysext/usr/bin/k0s chmod 0755 sysext/usr/bin/k0s - # Stage systemd service + # Stage kc-agent binary + cp -a /usr/bin/kc-agent sysext/usr/bin/kc-agent + chmod 0755 sysext/usr/bin/kc-agent + + # Stage systemd services cp -a sysext-src/k0scontroller.service sysext/usr/lib/systemd/system/ + cp -a sysext-src/kc-agent.service sysext/usr/lib/systemd/system/ # Stage extension release metadata cp -a sysext-src/extension-release.k0s sysext/usr/lib/extension-release.d/ diff --git a/files/k0s/sysext/kc-agent.service b/files/k0s/sysext/kc-agent.service new file mode 100644 index 00000000..cef7fb5b --- /dev/null +++ b/files/k0s/sysext/kc-agent.service @@ -0,0 +1,23 @@ +[Unit] +Description=kc-agent - KubeStellar Console local cluster agent +Documentation=https://github.com/kubestellar/console +ConditionFileIsExecutable=/usr/bin/kc-agent +After=network-online.target k0scontroller.service +Wants=network-online.target + +[Service] +Type=simple +Environment=KAGENTI_CONTROLLER_URL=none +StateDirectory=kc-agent +WorkingDirectory=/var/lib/kc-agent +ExecStart=/usr/bin/kc-agent -kubeconfig /var/lib/k0s/pki/admin.conf -allowed-origins http://localhost:8080,http://127.0.0.1:8080 +Restart=always +RestartSec=5s + +Delegate=yes +KillMode=process +LimitNOFILE=1048576 +LimitNPROC=infinity + +[Install] +WantedBy=multi-user.target diff --git a/files/os/justfile b/files/os/justfile index cd6bb90a..6f09d0b4 100644 --- a/files/os/justfile +++ b/files/os/justfile @@ -31,6 +31,7 @@ k8s ROLE="controller" TOKEN="": if [ "{{ROLE}}" = "controller" ] || [ "{{ROLE}}" = "server" ]; then echo "==> Enabling and starting k0s controller service..." systemctl enable --now k0scontroller.service + systemctl enable --now kc-agent.service else echo "ERROR: Invalid role '{{ROLE}}'. Supported: controller" >&2 exit 1 diff --git a/files/os/systemd/system/k0s-first-boot.service b/files/os/systemd/system/k0s-first-boot.service index 6e61f470..790525fd 100644 --- a/files/os/systemd/system/k0s-first-boot.service +++ b/files/os/systemd/system/k0s-first-boot.service @@ -18,5 +18,6 @@ ExecStart=/usr/bin/systemd-tmpfiles --create /usr/lib/tmpfiles.d/k0s-manifests.c ExecStart=/usr/share/k0s/kubeflex/generate-postgres-secret.sh ExecStart=/usr/bin/systemctl daemon-reload ExecStart=/usr/bin/systemctl enable --now k0scontroller.service +ExecStart=/usr/bin/systemctl enable --now kc-agent.service [Install] WantedBy=multi-user.target diff --git a/include/kc-agent.yml b/include/kc-agent.yml new file mode 100644 index 00000000..43dcda8f --- /dev/null +++ b/include/kc-agent.yml @@ -0,0 +1,3 @@ +# Single source of truth for the kc-agent version axis. +variables: + kc-agent-version: "0.3.41" diff --git a/tests/unit/os-justfile_test.bats b/tests/unit/os-justfile_test.bats index a40d906b..69393a69 100644 --- a/tests/unit/os-justfile_test.bats +++ b/tests/unit/os-justfile_test.bats @@ -165,6 +165,7 @@ calls() { [ "$status" -eq 0 ] run calls [[ "$output" == *"systemctl enable --now k0scontroller.service"* ]] + [[ "$output" == *"systemctl enable --now kc-agent.service"* ]] } @test "the server alias role enables k0scontroller.service" { @@ -172,6 +173,7 @@ calls() { [ "$status" -eq 0 ] run calls [[ "$output" == *"systemctl enable --now k0scontroller.service"* ]] + [[ "$output" == *"systemctl enable --now kc-agent.service"* ]] } @test "an unknown role exits 1 and names the supported roles" { @@ -186,6 +188,7 @@ calls() { [ "$status" -eq 1 ] run calls [[ "$output" != *"k0scontroller.service"* ]] + [[ "$output" != *"kc-agent.service"* ]] } @test "the role comparison is case sensitive" { diff --git a/tests/unit/test_k0s_first_boot.py b/tests/unit/test_k0s_first_boot.py index a185a611..13680bb7 100644 --- a/tests/unit/test_k0s_first_boot.py +++ b/tests/unit/test_k0s_first_boot.py @@ -101,6 +101,10 @@ def test_k0s_first_boot_retries_until_controller_starts() -> None: "ExecStart=/usr/bin/systemctl enable --now k0scontroller.service" in service ) + assert ( + "ExecStart=/usr/bin/systemctl enable --now kc-agent.service" + in service + ) assert ( "ExecStartPost=/usr/bin/touch /var/lib/k0s/.first-boot-complete" not in service diff --git a/tests/unit/test_k0s_manifests.py b/tests/unit/test_k0s_manifests.py index 149ca421..bcc24f9e 100644 --- a/tests/unit/test_k0s_manifests.py +++ b/tests/unit/test_k0s_manifests.py @@ -17,6 +17,24 @@ def test_k0s_service_unit(): assert "--single" in text +def test_kc_agent_service_unit(): + unit = ROOT / "files" / "k0s" / "sysext" / "kc-agent.service" + assert unit.is_file(), "kc-agent.service missing" + text = unit.read_text() + assert "ConditionFileIsExecutable=/usr/bin/kc-agent" in text + assert "-kubeconfig /var/lib/k0s/pki/admin.conf" in text + assert "-allowed-origins http://localhost:8080,http://127.0.0.1:8080" in text + assert "Environment=KAGENTI_CONTROLLER_URL=none" in text + assert "After=network-online.target k0scontroller.service" in text + + +def test_kc_agent_sysext_packaging(): + sysext = (ROOT / "elements" / "oci" / "k0s-sysext.bst").read_text() + assert "filename: k0s/kc-agent-bin.bst" in sysext + assert "cp -a /usr/bin/kc-agent sysext/usr/bin/kc-agent" in sysext + assert "cp -a sysext-src/kc-agent.service sysext/usr/lib/systemd/system/" in sysext + + def test_k0s_manifests_conf(): conf = ROOT / "files" / "k0s" / "sysext" / "k0s-manifests.conf" assert conf.is_file(), "k0s-manifests.conf missing" diff --git a/tests/unit/test_k0s_version.py b/tests/unit/test_k0s_version.py index ddf83633..805cf3d1 100644 --- a/tests/unit/test_k0s_version.py +++ b/tests/unit/test_k0s_version.py @@ -25,6 +25,23 @@ def test_k0s_bin_element(): assert "ca1e9e68107335846e8296777fce2ccd654284e6265b4b5d32c34ead872af98f" in content +def test_kc_agent_version_ssot(): + kc_yml = ROOT / "include" / "kc-agent.yml" + assert kc_yml.is_file(), "include/kc-agent.yml missing" + data = yaml.safe_load(kc_yml.read_text()) + vars_ = data.get("variables", {}) + assert vars_.get("kc-agent-version") == "0.3.41" + + +def test_kc_agent_bin_element(): + bin_bst = ROOT / "elements" / "k0s" / "kc-agent-bin.bst" + assert bin_bst.is_file(), "elements/k0s/kc-agent-bin.bst missing" + content = bin_bst.read_text() + assert "base/base-stack.bst" in content + assert "github:kubestellar/console/releases/download/" in content + assert "052b80bd0700f1c7e22ed5d6ad7547a45d6441d6a2cd40609fed1e69bf592df2" in content + + def test_k0s_version_checker_reads_the_component_transfer(): checker = ROOT / ".github" / "scripts" / "check-k0s-version.py" spec = importlib.util.spec_from_file_location("check_k0s_version", checker) diff --git a/tests/unit/test_kc_agent_onboarding.py b/tests/unit/test_kc_agent_onboarding.py new file mode 100644 index 00000000..6dca2d5f --- /dev/null +++ b/tests/unit/test_kc_agent_onboarding.py @@ -0,0 +1,61 @@ +"""Contracts for automatic first-boot kc-agent and local k0s onboarding.""" + +from pathlib import Path +import yaml + +ROOT = Path(__file__).resolve().parents[2] +KC_SERVICE = ROOT / "files" / "k0s" / "sysext" / "kc-agent.service" +FIRST_BOOT_SERVICE = ( + ROOT / "files" / "os" / "systemd" / "system" / "k0s-first-boot.service" +) +JUSTFILE_SYS = ROOT / "files" / "os" / "justfile" +KC_INCLUDE = ROOT / "include" / "kc-agent.yml" +KC_BIN = ROOT / "elements" / "k0s" / "kc-agent-bin.bst" +SYSEXT = ROOT / "elements" / "oci" / "k0s-sysext.bst" + + +def test_kc_agent_version_and_element() -> None: + assert KC_INCLUDE.is_file(), "include/kc-agent.yml missing" + data = yaml.safe_load(KC_INCLUDE.read_text(encoding="utf-8")) + version = data.get("variables", {}).get("kc-agent-version") + assert version, "kc-agent-version variable missing" + + assert KC_BIN.is_file(), "elements/k0s/kc-agent-bin.bst missing" + content = KC_BIN.read_text(encoding="utf-8") + assert "(@): include/kc-agent.yml" in content + assert "github:kubestellar/console/releases/download/v%{kc-agent-version}" in content + assert "install -D -m 0755 kc-agent" in content + + +def test_kc_agent_service_contract() -> None: + assert KC_SERVICE.is_file(), "kc-agent.service missing" + text = KC_SERVICE.read_text(encoding="utf-8") + assert "ConditionFileIsExecutable=/usr/bin/kc-agent" in text + assert "-kubeconfig /var/lib/k0s/pki/admin.conf" in text + assert "-allowed-origins http://localhost:8080,http://127.0.0.1:8080" in text + assert "Environment=KAGENTI_CONTROLLER_URL=none" in text + assert "After=network-online.target k0scontroller.service" in text + assert "Wants=network-online.target" in text + assert "Restart=always" in text + assert "StateDirectory=kc-agent" in text + + +def test_sysext_packages_kc_agent_binary_and_service() -> None: + sysext = SYSEXT.read_text(encoding="utf-8") + assert "filename: k0s/kc-agent-bin.bst" in sysext + assert "cp -a /usr/bin/kc-agent sysext/usr/bin/kc-agent" in sysext + assert "chmod 0755 sysext/usr/bin/kc-agent" in sysext + assert "cp -a sysext-src/kc-agent.service sysext/usr/lib/systemd/system/" in sysext + + +def test_first_boot_activates_kc_agent() -> None: + service = FIRST_BOOT_SERVICE.read_text(encoding="utf-8") + lines = [line.strip() for line in service.splitlines() if line.startswith("ExecStart")] + assert "ExecStart=/usr/bin/systemctl enable --now k0scontroller.service" in lines + assert "ExecStart=/usr/bin/systemctl enable --now kc-agent.service" in lines + + +def test_system_justfile_enables_kc_agent() -> None: + justfile = JUSTFILE_SYS.read_text(encoding="utf-8") + assert "systemctl enable --now k0scontroller.service" in justfile + assert "systemctl enable --now kc-agent.service" in justfile