Documentation
¶
Overview ¶
Package k3s handles K3s installation, cluster join, and lifecycle management on remote Lima VMs.
Index ¶
- func LBRangeCIDR(ipRange string) string
- type Manager
- func (m *Manager) AdvertiseNodeRoutes(ctx context.Context, podCIDR string, extraRoutes []string) error
- func (m *Manager) CreateSnapshot(ctx context.Context) (string, error)
- func (m *Manager) DeleteNode(ctx context.Context, nodeName string) error
- func (m *Manager) DeployMetalLB(ctx context.Context, ipRange string, l2Hostnames []string) error
- func (m *Manager) DownloadSnapshot(ctx context.Context, remotePath, localPath string) error
- func (m *Manager) DrainNode(ctx context.Context, nodeName string) error
- func (m *Manager) EnsureClusterDefaults(ctx context.Context) error
- func (m *Manager) GetKubeconfig(ctx context.Context, serverIP string) (string, error)
- func (m *Manager) GetNodeStatus(ctx context.Context) (string, error)
- func (m *Manager) GetToken(ctx context.Context) (string, error)
- func (m *Manager) GetVersion(ctx context.Context) (string, error)
- func (m *Manager) InitCluster(ctx context.Context, nodeIP, pool, k3sVersion string, tlsSANs []string, ...) error
- func (m *Manager) InstallTailscale(ctx context.Context, authKey string) (string, error)
- func (m *Manager) IsInstalled(ctx context.Context) (bool, error)
- func (m *Manager) IsNodeReady(ctx context.Context, nodeName string) (bool, error)
- func (m *Manager) JoinAgent(ctx context.Context, nodeIP, serverURL, token, pool, k3sVersion string, ...) error
- func (m *Manager) JoinServer(ctx context.Context, nodeIP, serverURL, token, pool, k3sVersion string, ...) error
- func (m *Manager) ReadNodePodCIDR(ctx context.Context, nodeName string) (string, error)
- func (m *Manager) ReinstallAgent(ctx context.Context, nodeIP, serverURL, token, version, pool string) error
- func (m *Manager) ReinstallJoinServer(ctx context.Context, nodeIP, serverURL, token, version, pool string) error
- func (m *Manager) ReinstallServer(ctx context.Context, nodeIP, version string, tlsSANs []string, pool string) error
- func (m *Manager) RestoreSnapshot(ctx context.Context, snapshotPath string) error
- func (m *Manager) StartService(ctx context.Context) error
- func (m *Manager) StopService(ctx context.Context) error
- func (m *Manager) UncordonNode(ctx context.Context, nodeName string) error
- func (m *Manager) Uninstall(ctx context.Context, role string) error
- func (m *Manager) UploadSnapshot(ctx context.Context, localPath, remotePath string) error
- func (m *Manager) WaitForReady(ctx context.Context, timeout time.Duration) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LBRangeCIDR ¶ added in v0.66.0
LBRangeCIDR derives the /24 subnet carrying a MetalLB IP range so the LB IPs can be advertised as a single tailnet subnet route. It accepts the range in any of the forms MetalLB allows: an explicit CIDR ("10.44.86.0/24"), a dashed range with full endpoints ("10.44.86.210-10.44.86.215") or a bare-suffix endpoint ("10.44.86.210-215"), or a single IP ("10.44.86.210"). The host octet is always zeroed to a /24. An empty input yields an empty string.
Types ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager handles K3s operations on a node, running privileged commands via exec. The K3s install/join recipe is identical for a Lima VM or a bare host; only how the command is delivered differs.
func NewManager ¶
NewManager creates a new K3s manager for the given remote host (Lima VM).
func NewManagerWithExec ¶ added in v0.62.0
NewManagerWithExec creates a Manager that runs commands via the injected exec (e.g. ssh-sudo directly on a native Linux host). runner is used only for its Host label in log lines.
func NewManagerWithVM ¶
NewManagerWithVM creates a new K3s manager that runs commands inside a Lima VM.
func (*Manager) AdvertiseNodeRoutes ¶ added in v0.66.0
func (m *Manager) AdvertiseNodeRoutes(ctx context.Context, podCIDR string, extraRoutes []string) error
AdvertiseNodeRoutes runs the tailscale route-advertisement on the node itself (the Manager's exec is bound to that node). podCIDR is the node's pod CIDR; extraRoutes carries any additional subnet routes (the LB range on stable nodes).
func (*Manager) CreateSnapshot ¶
CreateSnapshot creates an etcd snapshot and returns the full path to the resulting snapshot file on the remote VM.
func (*Manager) DeleteNode ¶
DeleteNode removes a node from the cluster.
func (*Manager) DeployMetalLB ¶ added in v0.43.1
DeployMetalLB installs MetalLB and configures the IPAddressPool and L2Advertisement. When l2Hostnames is non-empty, the L2Advertisement is pinned to those nodes via spec.nodeSelectors (one matchLabels per hostname), so the speaker VIP stays on stable nodes instead of flapping onto high-latency Macs. An empty list emits the L2Advertisement with no nodeSelector (default MetalLB behaviour — advertise from all nodes).
func (*Manager) DownloadSnapshot ¶
DownloadSnapshot copies a snapshot from the remote VM to the local machine.
func (*Manager) EnsureClusterDefaults ¶ added in v0.65.0
EnsureClusterDefaults bakes the homelab resilience defaults into a running cluster so they are reproducible and re-asserted on every `cluster init` / `cluster apply`, instead of living as one-off live edits:
- CoreDNS → 2 replicas + required hostname anti-affinity (see corednsHAPatch).
- Exactly one default StorageClass: k3s marks its bundled local-path as default, but Longhorn (installed by the Pulumi dev-local stack) is the real default. Two defaults is invalid, so local-path is un-defaulted here.
It is idempotent and safe to re-run: the CoreDNS patch is a no-op once applied, and the StorageClass step is guarded so it does nothing if local-path is absent (it never deletes local-path — workloads may still request it explicitly).
Note on durability: a plain k3s restart preserves these (k3s only re-applies a bundled addon when its on-disk manifest changes), but a k3s *version upgrade* re-extracts the bundled manifests and can reset them — re-running this (which a `cluster apply` does) re-converges.
func (*Manager) GetKubeconfig ¶
GetKubeconfig retrieves and patches the kubeconfig for external access.
func (*Manager) GetNodeStatus ¶
GetNodeStatus returns the output of kubectl get nodes.
func (*Manager) GetVersion ¶
GetVersion returns the installed K3s version string.
func (*Manager) InitCluster ¶
func (m *Manager) InitCluster(ctx context.Context, nodeIP, pool, k3sVersion string, tlsSANs []string, disableServiceLB, useTailscale, useDocker, useCilium bool) error
InitCluster bootstraps the first control plane node with --cluster-init.
func (*Manager) InstallTailscale ¶ added in v0.43.1
InstallTailscale installs Tailscale, brings it up with the provided auth key, and returns the Tailscale IP.
func (*Manager) IsInstalled ¶
IsInstalled checks whether K3s is installed inside the VM.
func (*Manager) IsNodeReady ¶ added in v0.66.0
IsNodeReady reports whether the named node's Ready condition is True, queried via the control-plane node's kubectl. Used to poll a node back to health after an Apply VM restart instead of sleeping a fixed interval.
func (*Manager) JoinAgent ¶
func (m *Manager) JoinAgent(ctx context.Context, nodeIP, serverURL, token, pool, k3sVersion string, useTailscale, useDocker, useCilium bool) error
JoinAgent joins a worker node to the cluster.
func (*Manager) JoinServer ¶
func (m *Manager) JoinServer(ctx context.Context, nodeIP, serverURL, token, pool, k3sVersion string, tlsSANs []string, disableServiceLB, useTailscale, useDocker, useCilium bool) error
JoinServer joins a server node to an existing HA cluster.
func (*Manager) ReadNodePodCIDR ¶ added in v0.66.0
ReadNodePodCIDR reads a node's assigned pod CIDR from the cluster via kubectl jsonpath. It must run on a control-plane node that has kubectl (the Manager's exec), and the node must already have joined so its podCIDR is assigned.
func (*Manager) ReinstallAgent ¶
func (m *Manager) ReinstallAgent(ctx context.Context, nodeIP, serverURL, token, version, pool string) error
ReinstallAgent reinstalls K3s on an agent node.
func (*Manager) ReinstallJoinServer ¶
func (m *Manager) ReinstallJoinServer(ctx context.Context, nodeIP, serverURL, token, version, pool string) error
ReinstallJoinServer reinstalls K3s on a server node that joins an existing cluster.
func (*Manager) ReinstallServer ¶
func (m *Manager) ReinstallServer(ctx context.Context, nodeIP, version string, tlsSANs []string, pool string) error
ReinstallServer reinstalls K3s server (init node) with a new version.
func (*Manager) RestoreSnapshot ¶
RestoreSnapshot restores etcd from a snapshot file on the remote VM.
func (*Manager) StartService ¶
StartService starts the K3s systemd service.
func (*Manager) StopService ¶
StopService stops the K3s systemd service.
func (*Manager) UncordonNode ¶
UncordonNode marks a node as schedulable after draining.
func (*Manager) UploadSnapshot ¶
UploadSnapshot copies a snapshot from the local machine to the remote VM.
Source Files