Skip to main content
← back to extensions

K0s Multinode

@randybias/k0s-multinodev2026.10.17.1beta· 9d agoBEHAVIORSWORKFLOWSACCEPTED WARNINGS
01README

Plan and operate a multi-node k0s cluster over SSH in the k0sctl style: short-lived join tokens, ordered controller and worker joins, drain and detach before reset, and safe rolling upgrades. Per-node work is delegated to @randybias/k0s-cluster, and this model needs no kubeconfig.

02Behaviors1
@randybias/k0s-multinodev2026.10.17.1k0s_multinode.ts
fn plan()
READ-ONLY. Return the ordered step list for creating, adding to, or upgrading the cluster, enforcing the ordering invariants; the same inputs give the same list. Tokens are never minted here.
fn plan_remove()
READ-ONLY. Return the drain -> detach -> reset step list for removing one node, refusing a detach that would lose etcd quorum without confirm.
fn mint_join_token()
On a controller, mint a short-lived join token, write it to a caller-named vault key and return only its ID, role and expiry. Refuses to proceed without a vault service, so the token never falls back into the output.
fn invalidate_join_token()
Invalidate a join token by ID and overwrite its vault key with a non-secret tombstone. Idempotent: an unknown or already-expired ID is a no-op on the cluster side.
fn wait_joined()
READ-ONLY. Poll a controller until the named node is Ready (worker) or is an etcd member with a ControlNode (controller).
fn drain_node()
Cordon and drain a node, honoring PodDisruptionBudgets (never --disable-eviction). Idempotent. A budget block is a typed error and the node stays cordoned.
fn uncordon_node()
Uncordon a node, returning it to service. Idempotent.
fn detach_node()
DESTRUCTIVE. Remove a drained node from the cluster: for a controller an etcd leave plus ControlNode delete, for a worker a Node delete. Refuses an undrained node or a controller removal that would lose etcd quorum unless confirm is the node name. Does not touch the host.
fn get()
READ-ONLY. Report nodes (role, Ready, cordoned, kubelet and k0s version), etcd members and outstanding join tokens; refreshes the stored status record. No token value is returned.
fn sync()
READ-ONLY. Reconcile the recorded membership with the live cluster and flag drift (unknown nodes, lost nodes or members, role changes); refreshes the stored status record.

Resources

plan(infinite)— Ordered step list for one cluster operation
status(infinite)— Last observed cluster membership
tokens(infinite)— Outstanding join tokens; IDs, roles and expiry only
03Workflows2
@randybias/k0s-multinode-create-cluster6f1a2b34-5c6d-4e7f-8a90-1234567890ab

Create a multi-node k0s cluster: install the first controller, then join each extra controller and worker with a short-lived token minted into a vault key and invalidated as soon as the node has joined. Per-node work is delegated to k0s-cluster; the cluster-scope work (tokens, membership, ordering) is k0s-multinode. Every mint is paired with an invalidate that runs on success or failure.

planRecord the ordered step list and refuse a bad topology before touching a host
1.plan— Plan create; refuses an even controller count or a missing HA endpoint
bootstrapInstall the first controller and wait for it to be Ready before any token is minted
1.install-first-controller— Install k0s on the first controller with the shared k0s.yaml
2.wait-first-controller— Wait for the first controller to be Ready and an etcd member
join-controllersJoin the extra controllers and controller_workers one at a time. swamp forEach has no early stop, so a later controller in the same job still runs after one fails; the workers job is gated on this whole job.
1.join-controller-${{ self.node.name }}— Mint, install, wait and invalidate for this controller
join-workersJoin the workers one at a time, only after every controller join succeeded
1.join-worker-${{ self.node.name }}— Mint, install, wait and invalidate for this worker
verifyRead back the membership
1.get— Record nodes, etcd members and outstanding tokens
2.check— Every desired node must be present and Ready
@randybias/k0s-multinode-join-node7a2c4d5e-6f70-4a1b-9c2d-3e4f5a6b7c8d

Join one node to an existing k0s cluster: mint a short-lived token into a vault key, install k0s on the node with that token, wait for it to join, and invalidate the token whichever way the install ends. Called once per node by the cluster workflows, sequentially.

joinMint, install with the token, wait, and always invalidate
1.mint— Mint this node's role token into its vault key
2.install— Install k0s on the node with the minted token
3.wait— Wait for this node to join
4.invalidate— Invalidate the token after the wait (success or failure)
5.invalidate-failed— Invalidate the token when the install failed (wait would be skipped)
04Stats
A
93 / 100
Downloads
2
Archive size
50.0 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License1/2partial

    no SPDX license declared

  • Verified public repository2/2earned
Repository
https://github.com/randybias/swamp-extensions

06Platforms
07Labels
#k0s#kubernetes#multinode#ha#etcd#join-token#orchestration