Skip to content

feat(k0s): auto-onboard local k0s cluster into kc-agent and console on first boot - #203

Closed
mrbobbytables wants to merge 1 commit into
projectbluefin:mainfrom
mrbobbytables:feat/k0s-auto-onboard
Closed

mrbobbytables wants to merge 1 commit into
projectbluefin:mainfrom
mrbobbytables:feat/k0s-auto-onboard

Conversation

@mrbobbytables

Copy link
Copy Markdown
Contributor

Closes #197

Summary

On first boot, KubeStellar Console defaulted to an unpopulated setup / onboarding screen with demo widgets because kc-agent (listening on 127.0.0.1:8585) had no active cluster connection.

This change packages kc-agent and an automatic kc-agent.service inside the k0s systemd-sysext. When the k0s sysext is merged on first boot, kc-agent.service starts and monitors /var/lib/k0s/pki/admin.conf, pre-registering the local single-node k0s cluster and streaming real metrics, namespaces, and pods to the console over WebSocket without requiring manual operator intervention.

Details

  • Version tracking: Added include/kc-agent.yml as the single source of truth for the kc-agent version (0.3.41).
  • Binary & sysext packaging: Added elements/k0s/kc-agent-bin.bst to import the upstream release tarball and updated elements/oci/k0s-sysext.bst to stage /usr/bin/kc-agent and /usr/lib/systemd/system/kc-agent.service.
  • Systemd unit: Added files/k0s/sysext/kc-agent.service configured with -kubeconfig /var/lib/k0s/pki/admin.conf, allowed origins for localhost / 127.0.0.1:8080, and Environment=KAGENTI_CONTROLLER_URL=none.
  • First-boot enablement: Updated files/os/systemd/system/k0s-first-boot.service and files/os/justfile to enable and start kc-agent.service alongside k0scontroller.service.
  • Tests: Added contract unit tests in tests/unit/test_kc_agent_onboarding.py, extended test_k0s_first_boot.py, test_k0s_manifests.py, test_k0s_version.py, and os-justfile_test.bats.
  • Documentation: Updated docs/skills/k0s-sysext.md and docs/skills/k0s-sysext-ops.md.

— hive: backend=copilot model=gemini-3.8-flash

🐝 Hive Agent: contributor | SHA: 0a8164e

…n first boot

Provide an automatic systemd service running kc-agent pointing to
/var/lib/k0s/pki/admin.conf when the k0s sysext is enabled.

When KubeStellar Console launches on first boot, kc-agent now connects
directly to the local single-node k0s cluster and streams real node
metrics, namespaces, and pods into the browser session over WebSocket,
preventing the console from defaulting to demo/onboarding cards.

- Define include/kc-agent.yml as the single source of truth for the
  kc-agent release version.
- Add elements/k0s/kc-agent-bin.bst and package kc-agent and kc-agent.service
  into elements/oci/k0s-sysext.bst.
- Add files/k0s/sysext/kc-agent.service pointing to /var/lib/k0s/pki/admin.conf
  with allowed origins for localhost/127.0.0.1:8080 and KAGENTI_CONTROLLER_URL="none".
- Update files/os/systemd/system/k0s-first-boot.service and files/os/justfile to
  enable and start kc-agent.service alongside k0scontroller.service.
- Add comprehensive unit tests in tests/unit/test_kc_agent_onboarding.py,
  test_k0s_first_boot.py, test_k0s_manifests.py, test_k0s_version.py, and
  tests/unit/os-justfile_test.bats.
- Update documentation in docs/skills/k0s-sysext.md and k0s-sysext-ops.md.

Closes projectbluefin#197

Assisted-by: Gemini 3.8 Flash via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: mrbobbytables <mrbobbytables@users.noreply.github.com>
@castrojo

Copy link
Copy Markdown
Contributor

Closing as superseded by #210.

The k0s sysext is gone: `elements/k0s/`, `elements/oci/k0s-sysext.bst`, `files/k0s/` and `k0s-first-boot.service` are all deleted, so every path this PR touches no longer exists.

The design decision also went the other way. #210 keeps `kc-agent` as a host-side tool installed from the Homebrew tap, not a binary packaged inside the node sysext — the sysext carries only `kubeadm`, `kubelet`, `kubectl` and the CNI plugins (AGENTS.md hard rule 4). The onboarding prompt lives in the kiosk gate (`files/cluster/manifests/kiosk/assets/kiosk-gate.js`), which tells the operator how to start `kc-agent` and polls its health before opening the console.

The real problem you were solving — console shows nothing useful on first boot — is fixed in #210 by deploying actual ControlPlane instances (`files/cluster/manifests/controlplanes/controlplanes.yaml`) and dropping `DEV_MODE` from the console deployment. Thanks for the dig into the first-boot gap.

@castrojo castrojo closed this Sep 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(k0s): auto-onboard local k0s cluster into kc-agent and console on first boot

2 participants