Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/skills/k0s-sysext-ops.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion docs/skills/k0s-sysext.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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-<k0s-version>.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. |
Expand Down
32 changes: 32 additions & 0 deletions elements/k0s/kc-agent-bin.bst
Original file line number Diff line number Diff line change
@@ -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"
10 changes: 9 additions & 1 deletion elements/oci/k0s-sysext.bst
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ build-depends:
- filename: k0s/k0s-bin.bst
config:
location: /
- filename: k0s/kc-agent-bin.bst
config:
location: /

sources:
- kind: local
Expand Down Expand Up @@ -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/
Expand Down
23 changes: 23 additions & 0 deletions files/k0s/sysext/kc-agent.service
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions files/os/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions files/os/systemd/system/k0s-first-boot.service
Original file line number Diff line number Diff line change
Expand Up @@ -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
3 changes: 3 additions & 0 deletions include/kc-agent.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Single source of truth for the kc-agent version axis.
variables:
kc-agent-version: "0.3.41"
3 changes: 3 additions & 0 deletions tests/unit/os-justfile_test.bats
Original file line number Diff line number Diff line change
Expand Up @@ -165,13 +165,15 @@ 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" {
run_k8s server
[ "$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" {
Expand All @@ -186,6 +188,7 @@ calls() {
[ "$status" -eq 1 ]
run calls
[[ "$output" != *"k0scontroller.service"* ]]
[[ "$output" != *"kc-agent.service"* ]]
}

@test "the role comparison is case sensitive" {
Expand Down
4 changes: 4 additions & 0 deletions tests/unit/test_k0s_first_boot.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 18 additions & 0 deletions tests/unit/test_k0s_manifests.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
17 changes: 17 additions & 0 deletions tests/unit/test_k0s_version.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
61 changes: 61 additions & 0 deletions tests/unit/test_kc_agent_onboarding.py
Original file line number Diff line number Diff line change
@@ -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
Loading