k3s-io/k3s

K3s is a lightweight, fully-featured Kubernetes distribution designed for edge, IoT, and resource-constrained environments. It provides a unified binary that manages the entire control plane and node agent lifecycle, including containerd, CNI, and etcd. The system supports advanced operational capabilities such as rootless execution, dual-stack networking, and automated certificate and secrets encryption management. It also includes robust tooling for cluster diagnostics, snapshotting, and integration with external networks like Tailscale.

46 changes.

This period focused on restructuring the K3s CLI into a multi-call binary and consolidating agent startup logic into platform-specific modules. The work involved removing legacy agent components, introducing rootless execution support, and updating dependencies to Kubernetes v1.36.3.

47 changes.

This period focused on modernizing the codebase by introducing pluggable interfaces for managed clusters, etcd, and node configuration, while centralizing control-plane dependencies and proxy logic. Significant effort was also dedicated to expanding test coverage, adding integration and end-to-end tests for features like secrets encryption, certificate rotation, and dual-stack networking.

52 changes.

This period focused on significantly expanding test coverage across Docker, E2E, and integration environments, while introducing new features for token management, VPN integration, and certificate monitoring. The codebase also saw architectural improvements, including centralized metrics, HTTPS handling, and structured logging, alongside a shift to Go-based test suites.

6 changes.

This period focused on introducing local and remote etcd store abstractions to improve resilience during bootstrap and node restarts. The team also expanded test coverage by adding integration tests for the Nix snapshotter, large-scale cluster stability, and SELinux configuration across multiple Linux distributions.

The cgroups package now includes a new Linux implementation (cgroups\_linux.go) that validates cgroup availability for both cgroup v1 and v2, checking for required controllers like cpu, memory, and cpuset, and detects the cgroup mode to determine kubelet and runtime roots. A Windows stub (cgroups\_windows.go) is also added, providing empty implementations for Validate and CheckCgroups to support Windows builds. This change introduces new logic for cgroup validation and detection on Linux while providing a no-op implementation for Windows.

pkg/cgroups · high confidence

The package/rpm directory now contains the necessary files to build and install k3s via RPM. This includes a new install.sh script that handles the installation of the k3s binary, systemd service files, and configuration, along with a k3s.spec file that defines the RPM package structure, dependencies, and post-installation steps to enable the k3s services. Additionally, a repo-setup.sh script is provided to configure the Rancher YUM repository for package management.

package/rpm · high confidence

Users can now configure Tailscale as the VPN provider, including setting a custom control server URL and passing extra CLI flags to the Tailscale binary. The system will detect if Tailscale is already running and skip redundant startup commands, while also providing a generic interface for retrieving VPN status and advertised routes.

pkg/vpn · high confidence

Users can now authenticate using HTTP Basic Authentication by providing a CSV file of usernames and passwords, or by sending a Basic Auth header. The new \pkg/authenticator\ module wires together basic auth, client certificate authentication, and password file-based authentication, allowing the server to validate credentials from multiple sources simultaneously.

pkg/authenticator/basicauth · high confidence

The certmonitor package now includes a new controller that periodically checks the expiration status of node and CA certificates. It registers a Prometheus metric to track remaining certificate lifetime and emits Kubernetes events: a warning event if certificates are expiring within the configured warning period, and a one-time OK event on startup if all certificates are healthy. This provides users with proactive alerts about certificate expiration and automatic rotation triggers.

pkg/certmonitor · high confidence

A new utility in pkg/util/services now maps each internal service (such as api-server, controller-manager, scheduler, and supervisor) to its corresponding certificate and key file paths. This provides a centralized, reliable way to identify which certificate files belong to which component, supporting operations like certificate rotation and expiry checking. Unit tests verify the correct file paths for server and agent services.

pkg/util/services · high confidence

Users can now run 'k3s certificate check' to inspect the status of all certificates, with output in text, table, JSON, or YAML formats, and 'k3s certificate rotate-ca' to update CA certificates in the datastore. The check command reports expiration dates, remaining time, and warnings for certificates nearing expiry.

pkg/cli/cert · high confidence

The agent now supports cri-dockerd as a container runtime backend when the --docker flag is used. This adds platform-specific configuration (Linux and Windows stubs), a main runner that launches the cri-dockerd process with dynamic arguments (e.g., CNI dirs, pause image, dual-stack support), and a build-tag-gated no-op for builds where cri-dockerd is disabled. Users can now run K3s with Docker via the cri-dockerd shim, with logging and configuration options exposed via the agent config and environment variables.

pkg/agent/cridockerd · high confidence

Added new scripts in contrib/util to support cluster diagnostics and certificate lifecycle management. The diagnostics.sh script collects system, application, and Kubernetes logs, encrypts them with AES-256-CBC, and uploads them to a Google Cloud Storage bucket for secure analysis. Additionally, generate-custom-ca-certs.sh and rotate-default-ca-certs.sh provide tools for bootstrapping and rotating Certificate Authority certificates, while fetch-diags.sh handles the secure retrieval and decryption of uploaded diagnostic archives.

contrib/util · high confidence

Users can now manage etcd snapshots directly from the command line. The new \etcd-snapshot\ subcommands allow users to save new snapshots, delete existing ones, and list available snapshots. The implementation supports both local storage and S3-compatible backends, with configurable timeouts, compression, and retention policies. The CLI communicates with the server's \/db/snapshot\ endpoint, handling authentication via token and providing clear error messages when operations fail or when snapshots are not found.

pkg/cli/etcdsnapshot · high confidence

A new Go file pkg/util/metrics/metrics.go is introduced, defining a helper function ObserveWithStatus that records a Prometheus histogram observation with a 'success' or 'error' status label based on an error argument. This enables tracking etcd snapshot durations and outcomes via Prometheus metrics.

pkg/util/metrics · medium confidence

The \pkg/flock\ package has been added, providing file locking capabilities. For Unix-based systems (Linux, macOS, FreeBSD, OpenBSD, NetBSD, and DragonFly), the \flock\_unix.go\ file implements \Acquire\, \AcquireShared\, and \Release\ functions using \golang.org/x/sys/unix\. For non-Unix systems, \flock\_other.go\ provides stub implementations that return no-op results. Additionally, \flock\_unix\_test.go\ includes unit tests for the Unix-specific locking behavior.

pkg/flock · high confidence

The k3s CLI now includes a new 'token' subcommand with support for creating, deleting, generating, listing, and rotating bootstrap tokens. This allows users to manage authentication tokens directly via the command line, including rotating the server token and generating new bootstrap tokens for node registration.

pkg/cli/token · high confidence

A new \pkg/ctr\ package was added to provide a \ctr\ command-line interface that automatically configures the containerd socket path to \/run/k3s/containerd/containerd.sock\ and sets the default namespace to \k8s.io\. This allows users to interact with the k3s-managed containerd instance using the standard \ctr\ tooling without manual configuration.

pkg/ctr · high confidence

The \pkg/authenticator/passwordfile\ package now provides a \PasswordAuthenticator\ that reads user credentials from a CSV file. The authenticator parses each line for password, username, and optional groups, storing the password as a hash for secure verification. This enables users to authenticate against a local password file, with the system logging a warning if duplicate usernames are found.

pkg/authenticator/passwordfile · high confidence

The repository now includes formal project governance and community structure documentation. A new GOVERNANCE.md file defines the project's values, maintainer roles, and voting procedures. A comprehensive CONTRIBUTING.md guide outlines the development workflow, code conventions, and AI usage policies. Additionally, a MAINTAINERS.md file lists the current project maintainers, and an ADOPTERS.md file catalogs organizations using K3s. These additions provide clear guidelines for community participation and project management.

(repo-wide) · high confidence

A new controller in the rootlessports package now manages port forwarding for services in rootless mode. On Linux, it registers a handler that monitors Kubernetes services and configures the rootlesskit port manager to bind host ports to child namespace ports for TCP and UDP protocols. On Windows, the controller is a stub that panics, indicating that rootless port mapping is not supported on that platform.

pkg/rootlessports · high confidence

The package pkg/authenticator/hash now provides a new scrypt-based hashing implementation. This includes a Hasher interface, an SCrypt struct with configurable parameters (N, R, P, KeyLen, SaltLen), and methods to create and verify hashes. A fuzz test has been added to verify the robustness of the VerifyHash function against malformed or invalid inputs.

pkg/authenticator/hash · high confidence

Users can now generate shell completion scripts for Bash and Zsh using the new \k3s completion\ command. Running the command with the \-i\ flag will automatically append the necessary completion configuration to the user's \.bashrc\ or \.zshrc\ files, enabling tab-completion for k3s commands in those shells.

pkg/cli/completion · high confidence

A new \pkg/signals\ package has been introduced to manage process signals for graceful shutdown. It registers handlers for SIGTERM and SIGINT (or OS-specific equivalents like \os.Interrupt\ on Windows), returning a context that is cancelled when a shutdown signal is received. If a second signal is received, the application terminates immediately. This provides a standardized way for the application to handle shutdown requests.

pkg/signals · high confidence

A new logger utility has been added to the codebase, providing a bridge between the logr and logrus libraries. This introduces a LogrusSink implementation that maps logr verbosity levels to logrus log levels and supports structured logging with key-value pairs. The change also includes a helper function to inject a logger into the Go context, enabling consistent logging across the application.

pkg/util/logger · high confidence

The k3s CLI now includes a new 'token' subcommand, implemented in the pkg/kubeadm package. This adds the ability to manage bootstrap tokens for node authentication and cluster joining, mirroring functionality from the upstream kubeadm tooling. The implementation includes new types for BootstrapToken and BootstrapTokenString, along with utility functions to convert between token objects and Kubernetes Secrets, allowing users to generate, inspect, and manage bootstrap tokens directly via the k3s CLI.

pkg/kubeadm · high confidence

Users can now access the crictl command-line tool through the K3s CLI. This change introduces a new 'crictl' subcommand that wraps the external sigs.k8s.io/cri-tools/crictl package, allowing users to interact with container runtimes directly from the K3s interface.

pkg/cli/crictl · high confidence

A new \dataverify\ package has been introduced to validate the integrity of a data directory. It provides functions to verify SHA-256 checksums against a \.sha256sums\ file and validates symbolic links against a \.links\ file, logging errors for any mismatches.

pkg/dataverify · high confidence

The contrib/gotests\_templates directory now includes a new set of Go template files (call, function, header, inline, inputs, message, and results) that define the structure for automatically generating unit tests for Go functions and methods. These templates provide a scaffold for test cases, including setup/teardown hooks, argument struct generation, and assertion logic, allowing users to generate test files with pre-filled test cases.

_contrib/gotests\templates · high confidence

The agent now automatically loads essential kernel modules (such as nf\_conntrack, br\_netfilter, and iptable\_nat) and configures corresponding sysctls (including net/ipv4/conf/all/forwarding and bridge-nf-call-iptables) to ensure proper network functionality. This setup is conditional: IPv6 modules and sysctls are only applied when IPv6 is enabled, and bridge filter sysctls are only set when the bridge filter flag is true, allowing administrators to manage these settings manually if needed. A Windows-specific stub is also provided.

pkg/agent/syssetup · high confidence

The airgap workflow now uses a new script (generate-list.sh) to automatically extract the current set of required container images from the k3s binary, producing an updated image-list.txt. Additionally, a volume-test.yaml is added to verify local-path-provisioner functionality in airgap environments.

scripts/airgap · high confidence

Three new shell scripts have been added to the updatecli/scripts directory to automate the process of bumping Kubernetes staging dependencies. The 'bump-staging-deps.sh' script updates go.mod entries to the latest available -k3sN tags, 'check-staging-tags-ready.sh' validates that required tags exist before proceeding, and 'run-go-mod-update.sh' executes the Go module updates. These scripts enable the Updatecli automation to keep the project's internal Kubernetes staging dependencies in sync with upstream releases.

updatecli/scripts · high confidence

The bootstrap package now provides functions to serialize control runtime bootstrap data to and from disk as JSON. Specifically, \ReadFromDisk\ reads certificate and key files from disk into a JSON structure, while \WriteToDiskFromStorage\ writes the contents of a reader to the paths derived from the bootstrap configuration, including file permissions and timestamps. A helper function \ObjToMap\ is also added to convert objects to a map representation. Tests are added to verify the \ObjToMap\ function handles valid and invalid inputs correctly.

pkg/bootstrap · high confidence

The \k3s secrets-encrypt\ CLI commands (enable, disable, status, prepare, rotate) are now implemented in \pkg/cli/secretsencrypt/secrets\_encrypt.go\. This change introduces the command-line interface for managing secrets encryption, allowing users to enable or disable encryption, check the current status, and perform rotation or preparation steps via the CLI.

pkg/cli/secretsencrypt · high confidence

The control-plane daemon's dependency and certificate path management has been consolidated into a new \deps\ package. This change introduces a centralized \CreateRuntimeCertFiles\ function that defines all certificate, key, and kubeconfig file paths for the control plane, alongside a \GenServerDeps\ function to handle certificate generation and legacy cleanup. The refactoring also adds unit tests for the \addSANs\ helper function, ensuring consistent handling of Subject Alternative Names in certificates.

pkg/daemons/control/deps · high confidence

Added new CRI (Container Runtime Interface) helper functions to the agent. The \Connection\ function establishes a gRPC connection to a CRI socket, automatically prepending the correct platform-specific prefix (Unix for Linux, npipe for Windows) and verifying the runtime is responsive. The \WaitForService\ function provides a retry loop to wait for the CRI service to become available, improving startup reliability.

pkg/agent/cri · high confidence

The \pkg/configfilearg\ package now provides a standalone, framework-agnostic parser for K3s configuration files. This new \Parser\ and its \DefaultParser\ handle reading the primary config file and \.d\ drop-in directories, supporting value appending for slice flags and filtering invalid flags per command. The \MustFindString\ helper allows safe retrieval of config values while respecting override flags like \--help\ or \--version\. Comprehensive unit tests verify parsing logic, drop-in file handling, and environment variable overrides.

pkg/configfilearg · high confidence

Added a new \types.go\ file in \pkg/etcd/snapshot\ that defines the internal \File\ and \S3Config\ structs used to represent etcd snapshots and their S3 configuration. This change introduces the data structures and conversion logic (\FromETCDSnapshotFile\, \ToETCDSnapshotFile\) that map between the internal snapshot representation and the external \ETCDSnapshotFile\ API objects, enabling the snapshot subsystem to handle both local and S3-based storage backends.

pkg/etcd/snapshot · high confidence

The k3s cloud provider has been implemented in the \pkg/cloudprovider\ package, providing the \cloudprovider.Interface\ for managing node status and service load balancers. This includes the \InstancesV2\ implementation for node metadata (internal/external IPs, DNS, hostname, and topology labels) and the \LoadBalancer\ interface for managing the \svclb\ DaemonSet. The implementation supports dual-stack IP families, respects the \ExternalTrafficPolicy\ for local traffic routing, and allows configuration of the load balancer image, namespace, and pod priority class. Tests have been added for the instance metadata and load balancer filtering logic.

pkg/cloudprovider · high confidence

Added new \store\ package providing \ReadWriteCloser\ and \ReadCloser\ interfaces for interacting with etcd data. The implementation includes a \RemoteStore\ wrapper around the etcd client for remote operations, and a \TemporaryStore\ that creates a local copy of the etcd database files for safe, isolated access. These changes support improved resilience during datastore bootstrap and control-plane node restarts by enabling local data access without a running etcd server.

pkg/etcd/store · high confidence

The agent's load balancer has been refactored to persist its configuration to disk, allowing it to remember the list of backend servers across restarts. The implementation now supports HTTP and SOCKS5 proxies for agent connections, configurable via environment variables. Additionally, Prometheus metrics are exposed to monitor server health states, connection counts, and dial durations.

pkg/agent/loadbalancer · high confidence

Added a new \pkg/passwd\ package that provides a structured way to read, update, and write node password and role information. The \Read\ function parses CSV-based password files, handling missing files gracefully and validating that records contain at least two columns. The \EnsureUser\ method updates or creates user entries, supporting both explicit passwords and automatic generation of random tokens for new users. The \Write\ method persists changes to disk using a temporary file and atomic rename to ensure filesystem compatibility. A comprehensive test suite (\passwd\_test.go\) validates reading, updating, and edge cases like K10 token prefix stripping.

pkg/passwd · medium confidence

Added a new rootless execution mode that allows K3s to run as a non-root user. This includes mounting necessary directories (logs, CNI, kubelet, etc.) into a user-specific state directory, configuring port forwarding via a built-in or slirp4netns driver, and validating required kernel sysctls. The implementation is restricted to Linux; attempting to use rootless mode on Windows will result in a panic.

pkg/rootless · high confidence

A new \pkg/version\ package is added, defining variables for the program name (defaulting to 'k3s'), its uppercase variant, the version string, and the git commit hash. The program name is exposed as a variable, allowing it to be changed at compile time rather than being hardcoded.

pkg/version · high confidence

A new \apiproxy.go\ file introduces a \Proxy\ interface and implementation in \pkg/agent/proxy\ that manages connections to the supervisor and API server. When load-balancing is enabled, the proxy starts local load-balancers on static ports (one below each other) to route traffic, returning the local load-balancer URLs instead of the actual server addresses. This allows agents to connect to local load-balancers rather than directly to remote servers, supporting features like health checks and IPv6. The proxy also handles fallback addresses and port configuration for both supervisor and API server endpoints.

pkg/agent/proxy · high confidence

A new \Driver\ interface is introduced in \pkg/cluster/managed/drivers.go\, defining a pluggable architecture for managed cluster backends. The interface specifies methods for initialization, lifecycle management (Start, Reset, Restore), snapshotting, and member management. The file also includes a global registry (\RegisterDriver\, \Registered\) to manage multiple driver implementations, allowing the system to support different storage or database backends through a unified interface.

pkg/cluster/managed · medium confidence

The system now uses a centralized \Executor\ interface to manage the lifecycle of Kubernetes components (API server, scheduler, controller manager, etc.) and node services (containerd, CNI). This change encapsulates the execution logic, allowing different drivers to implement the interface, which facilitates the transition to an embedded architecture where components like the cloud controller manager and etcd are managed internally rather than as separate processes. Users benefit from more robust component startup and shutdown sequencing, including proper context passing and wait-group handling to prevent premature exits.

pkg/daemons/executor · high confidence

The pkg/util package introduces new utility functions to manage API server readiness and RBAC validation. WaitForAPIServerReady and APIServerReadyChan now poll the /readyz endpoint with a configurable timeout and context support, ensuring components wait for the API server before starting. WaitForRBACReady and CheckRBAC provide polling mechanisms to verify RBAC permissions using SelfSubjectAccessReview or SubjectAccessReview. Additionally, GetRESTConfig and GetClientSet simplify Kubernetes client initialization with default timeouts and rate limits, while SendError and SendErrorWithID standardize error responses and logging. These changes improve startup reliability and error handling in the control plane.

pkg/util · high confidence

Added new middleware functions for authentication and authorization in the server's HTTP handler chain. The \auth\ package now provides \HasRole\ and \IsLocalOrHasRole\ for role-based access control, and \Delegated\ for Kubernetes-style client certificate and SubjectAccessReview-based authentication. Additionally, a \MaxInFlight\ middleware was added to limit concurrent requests, and a \RequestInfo\ middleware was introduced to enrich request context with verb, resource, and GVK information.

pkg/server/auth · high confidence

A new deploy controller has been introduced to manage the lifecycle of Kubernetes manifests. The controller watches for file changes and applies them to the cluster, supporting features such as disabling specific manifests, handling symlinks for logical path preservation, and using the \wrangler\ library for apply operations. The implementation includes a \Stage\ function that embeds and processes manifest files, and a \WatchFiles\ function that triggers periodic checks for updates. Tests verify that symlinked directories are followed correctly and that regular manifests remain removable when disabled.

pkg/deploy · high confidence

Added new utility functions to the agent's util package: a WriteFile helper that creates parent directories and writes content to a file, and a CopyFile function that copies files with optional handling for missing source files. Additionally, a case-insensitive suffix check function (HasSuffixI) was added to the strings utility.

pkg/agent/util · medium confidence

The nodeconfig package introduces new annotations to store the node's CLI arguments and environment variables, enabling other components to detect configuration changes. Sensitive values (such as tokens, datastore endpoints, and secret keys) are redacted with asterisks in the stored annotations. Additionally, labels are added or removed based on the egress selector mode to indicate supported functionality.

pkg/nodeconfig · high confidence

The cluster initialization logic has been refactored into separate modules: bootstrap.go handles loading and saving bootstrap data to the datastore, encrypt.go implements AES-GCM encryption for sensitive cluster configuration, and https.go manages the dynamic TLS listener and certificate generation. A new address\_controller.go introduces a node controller that dynamically updates the allowed TLS Subject Alternative Names (SANs) based on active control-plane and etcd nodes, filtering out invalid addresses. Additionally, a profile.go module is added to expose the Go pprof debugging endpoints on the supervisor port.

pkg/cluster · high confidence

The server command's entry point and configuration mapping have been consolidated into a new file at pkg/cli/server/server.go. This change centralizes how the server CLI parses arguments and maps them to the internal server configuration, including datastore (etcd/S3) settings, TLS/SSL parameters, feature flags (e.g., disable agent, disable CCM), and network settings (advertise IP, flannel backend). This refactoring simplifies the CLI interface and ensures consistent initialization of the server components.

pkg/cli/server · high confidence

Users can now store sensitive S3 backup configuration (access keys, endpoints, CA bundles, etc.) in a Kubernetes Secret rather than using CLI flags or config files. The system reads these settings from a specified secret, allowing for more secure and flexible S3 snapshot management. This change introduces new files (config\_secret.go, s3.go) that handle secret retrieval and client initialization, along with corresponding unit tests.

pkg/etcd/s3 · high confidence

The agent subsystem has been removed, including the Go implementation files for configuration, containerd, flannel, proxy, syssetup, and tunnel management. The corresponding CLI commands for running the agent and kubectl wrapper have also been deleted. This eliminates the previous mechanism for initializing and managing the node agent, network (flannel), and system setup, indicating a shift away from the prior agent-based architecture.

(repo-wide) · high confidence

The version package, which previously exposed the application's version and git commit hash, has been removed from the codebase.

version · high confidence

The embedded executor implementation has been moved from \pkg/executor\ into a new \pkg/executor/embed\ package, separating the embedded runtime logic from the main executor interface. This change also includes platform-specific implementations for Linux and Windows, and extracts the embedded etcd startup logic into \pkg/executor/embed/etcd\.

pkg/executor · high confidence

The HTTP request handlers for the K3s server have been moved from the \pkg/server\ package into a new \pkg/server/handlers\ package. This refactoring groups related HTTP handlers—such as those for certificates, secrets encryption, and token rotation—into a single, organized location, improving code structure and maintainability without changing the external API or behavior.

pkg/server/handlers · high confidence

The package now supports extracting zstd-compressed tarballs, replacing the previous gzip-based approach. The new implementation includes memory limits for the zstd decoder and validates file paths to prevent directory traversal issues.

pkg/untar · medium confidence

The agent configuration retrieval logic has been refactored to use jittered polling with exponential backoff when fetching node configuration from the server, improving stability during startup. Node authentication has been updated to include the node name and IP in the request headers, and the system now falls back to basic or bearer authentication if node identity authentication is rejected. Additionally, platform-specific containerd and CRI-Dockerd configurations are now applied via OS-specific files (config\_linux.go, config\_windows.go), and unit tests have been added to validate resolv.conf parsing and containerd QoS class configuration.

pkg/agent/config · high confidence

The agent startup sequence is now implemented in new platform-specific files (run.go, run\_linux.go, run\_windows.go) that handle container runtime initialization, network setup, and crictl configuration. This refactors how the agent bootstraps, validates network configuration (including dual-stack and IPv6 support), and manages the transition from deprecated pointer libraries and raw ListWatch calls to modern helpers.

pkg/agent · medium confidence

The agent's HTTPS handling is now managed through a centralized router and listener setup in the \pkg/agent/https\ package. This change introduces a \Start\ function that creates a new HTTPS listener and applies authentication/authorization filters, while also supporting the wrapping of existing handlers. This provides a consistent entry point for HTTPS traffic to the agent.

pkg/agent/https · medium confidence

The pkg/datadir package now defines default paths for data and configuration, using version.Program to construct paths like /var/lib/rancher/k3s and ${HOME}/.rancher/k3s. The Resolve and LocalHome functions implement logic to select between privileged (system) and unprivileged (home) directories based on permissions, enabling rootless operation.

pkg/datadir · medium confidence

The metrics subsystem has been refactored to use a shared Prometheus registry (DefaultRegisterer) and a unified HTTP /metrics endpoint. On startup, the application automatically registers metrics from the load balancer, etcd snapshot manager, remote dialer, and lasso, ensuring all these components expose their metrics through the same registry. The metrics server is now started by binding the /metrics path to the standard Prometheus handler, replacing the previous per-component or ad-hoc registration patterns.

pkg/metrics · medium confidence

The static package now supports conditional compilation via build tags. A new 'nostage' build tag allows users to disable the staging of static assets entirely, which is useful for environments where embedding or writing these files is unnecessary or undesirable. When the 'no\_stage' tag is not present, the system stages static files from the embedded filesystem to the specified data directory, maintaining the existing behavior for standard builds.

pkg/static · high confidence

The configuration types in \pkg/daemons/config/types.go\ have been significantly expanded to support new cluster networking, storage, and runtime options. The \Node\ struct now includes fields for egress selector mode, embedded registry, and containerd/cri-dockerd configurations. A new \EtcdS3\ struct defines parameters for S3-compatible etcd snapshot storage, while the \Agent\ struct gains fields for dual-stack CIDRs, node IPs/DNS, image credentials, and TLS settings. These changes enable users to configure advanced networking, storage backends, and runtime behaviors directly through the daemon's configuration.

pkg/daemons/config · high confidence

The Flannel networking agent has been refactored to support dual-stack (IPv4/IPv6) configurations and multiple backends including VXLAN, host-gateway, IPsec, and Wireguard. The implementation now uses a \netMode\ type to determine network configuration, enabling IPv6 masquerading and IPv6-only setups. The CNI configuration is generated dynamically based on the node's cluster CIDRs, and the agent waits for the PodCIDR assignment before starting. Additionally, the codebase has been updated to use modern Go practices, such as \context\ for error handling and \renameio\ for atomic file writes on Linux, while falling back to standard \os.WriteFile\ on Windows.

pkg/agent/flannel · high confidence

The kubectl wrapper now detects the kubeconfig path from the --kubeconfig flag and the KUBECONFIG environment variable. On Windows, it strips the first argument to support multi-call binary execution. Additionally, the wrapper checks if the kubeconfig file is world-readable and issues a warning if it is not, suggesting the use of --write-kubeconfig-mode or --write-kubeconfig-group to fix permissions.

pkg/kubectl · high confidence

The embedded containerd runtime has been upgraded to v2, introducing new built-in support for Linux snapshotter plugins including overlayfs, btrfs, devmapper, zfs, fuse-overlayfs, and nix-snapshotter on Linux, while providing stubs for Windows and non-Linux platforms. This change updates the containerd integration layer to register these snapshotter plugins and expose utility functions to detect their availability, enabling users to leverage advanced storage backends for container images and containers.

pkg/containerd · high confidence

Added a new HTTP router implementation in pkg/util/mux that wraps the standard library's http.ServeMux to provide middleware support. This change replaces the previous reliance on the github.com/gorilla/mux library, shifting to a custom routing solution that allows applying middlewares to matched routes.

pkg/util/mux · high confidence

The agent CLI entry point has been refactored into a new file (pkg/cli/agent/agent.go) that handles process title concealment, cgroup v2 evacuation, logging initialization, and signal context setup before delegating to the core agent logic. Additionally, a new kubectl CLI entry point (pkg/cli/kubectl/kubectl.go) has been added to wrap the kubectl main function. These changes restructure how the agent and kubectl commands are invoked from the CLI, introducing new behaviors around process title hiding, cgroup management, and signal handling.

pkg/cli/agent · medium confidence

The CLI has been refactored to use the Urfave CLI v2 framework, which restructures the command hierarchy and introduces new subcommands for managing certificates (k3s certificate check/rotate/rotate-ca), tokens (k3s token create/delete/generate/list/rotate), and secrets encryption (k3s secrets-encrypt status/enable/disable/prepare/rotate/reencrypt/rotate-keys). Additionally, shell completion is now handled via a dedicated k3s completion command supporting Bash and Zsh, and the etcd-snapshot command now includes save, delete, list, and prune subcommands with S3 backup support. The agent and server subcommands have been reorganized to expose more configuration flags for networking, runtime, and node settings.

pkg/cli/cmds · high confidence

The \ctr\ CLI command handler has been updated to use the Urfave CLI v2 library, replacing the previous implementation. This change updates the underlying framework for parsing command-line arguments and managing the \ctr\ subcommand within the K3s CLI interface.

pkg/cli/ctr · high confidence

The containerd configuration template has been updated to version 3, introducing support for additional runtime classes (crun, wasm, nvidia), SELinux, and systemd cgroup settings. The template now handles private registry configurations, snapshotter options (including Stargz and Nix), and CNI directory settings. Windows-specific handling for named pipe addresses and path escaping has also been refined.

pkg/agent/templates · medium confidence

The K3s CLI is restructured into a multi-call binary (k3s) that dispatches to subcommands, alongside standalone wrappers for specific tools (agent, server, cert, token, etcd-snapshot, secrets-encrypt, crictl, ctr, kubectl). This change introduces a new \--prefer-bundled-bin\ flag that allows users to prefer bundled binaries over host-installed ones, and adds shell completion support. The multi-call binary also handles symlink aliases for external CLIs and manages data directory resolution.

cmd · high confidence

The network policy controller will now wait for the node to become Ready and for the external cloud provider taint to be removed before starting. This prevents the controller from crashing or failing to initialize when the node is still in an uninitialized or not-yet-ready state, improving startup reliability.

pkg/agent/netpol · high confidence

The node controller has been refactored to use a dedicated handler that watches for node creation and removal events, updating the CoreDNS ConfigMap with the node's internal IP addresses and hostname. This change introduces a cache-based watch on the CoreDNS ConfigMap to avoid repeated API server calls, and ensures that node host entries are correctly synced or removed when nodes are added or deleted.

pkg/node · high confidence

The node password validation logic has been refactored to store and verify passwords in Kubernetes Secrets of type 'k3s-io/node-password' rather than relying on local files or in-memory state. A new controller in pkg/nodepassword manages these secrets, handling creation, migration of legacy secrets, and cleanup of orphaned entries. This change introduces a new dependency on the 'wrangler' library for controller management and updates the authentication flow to require the node password informer to be synced before using the cache, improving reliability during cluster startup and preventing race conditions.

pkg/nodepassword · high confidence

The permissions utility now implements platform-specific logic for the IsPrivileged function. On non-Windows systems, it checks if the process is running as root (UID 0). On Windows, it verifies that the process is a member of the BUILTIN\\Administrators group. This ensures that privilege checks are correctly enforced across different operating systems.

pkg/util/permissions · medium confidence

The embedded registry (Spegel) integration has been refactored to use new bootstrapper interfaces that prevent the node from advertising itself as an upstream registry. A deferred OCI store implementation is introduced to delay the connection to the containerd backend, and the registry mirror configuration now correctly injects TLS settings and updates node annotations and labels to support peer-to-peer image distribution.

pkg/spegel · high confidence

The agent daemon now generates and writes kubelet configuration files (drop-ins) rather than passing all settings as CLI flags. This change introduces OS-specific implementations (agent\_linux.go and agent\_windows.go) that build the kubelet configuration map and arguments, while the main agent.go orchestrates the startup sequence using these generated configs. Users may see changes in how kubelet is configured, particularly regarding the handling of --config and --config-dir flags which are now copied into managed drop-in directories.

pkg/daemons/agent · high confidence

The client access package has been reorganized by splitting the previous monolithic implementation into separate files for token handling (token.go) and kubeconfig generation (kubeconfig.go). This change introduces new public APIs for parsing and validating cluster join tokens, as well as generating client kubeconfig files, while maintaining the same underlying functionality for connecting to the K3s server.

pkg/clientaccess · high confidence

The monolithic etcd management logic has been split into dedicated controllers and handlers to improve modularity and testability. A new API addresses controller (\apiaddresses\_controller.go\) watches Kubernetes EndpointSlices to update the etcd datastore with API server addresses. A member controller (\member\_controller.go\) handles the addition and removal of etcd cluster members based on node annotations. A metadata controller (\metadata\_controller.go\) manages node labels and annotations for etcd nodes. The snapshot functionality has been separated into a dedicated controller (\snapshot\_controller.go\) that syncs snapshot metadata to a ConfigMap, and a handler (\snapshot\_handler.go\) that exposes snapshot operations (save, list, prune, delete) via HTTP. Additionally, a simple gRPC resolver (\resolver.go\) is introduced to bypass etcd's internal resolver for better failover handling, and snapshot metrics (\snapshotmetrics/snapshotmetrics.go\) are added to track performance. These changes restructure the \pkg/etcd\ package to separate concerns, making the codebase easier to maintain and test.

pkg/etcd · high confidence

The network proxy logic in \pkg/daemons/control/proxy\ has been refactored to use a custom \errors\ package (\github.com/k3s-io/k3s/pkg/util/errors\) for error handling, specifically replacing the use of \github.com/pkg/errors\ which was removed as a dependency. The \Proxy\ function now manages bidirectional data piping between two connections, handling errors via a dedicated channel and logging warnings for non-EOF errors. This change aligns with the broader project goal of removing the archived \github.com/pkg/errors\ dependency.

pkg/daemons/control/proxy · medium confidence

The secrets encryption configuration logic has been refactored into a new \config.go\ file, introducing structured handling for AES-CBC and SecretBox providers, along with identity (no-encryption) states. This change consolidates the logic for reading, writing, and managing encryption keys and providers, supporting the enable/disable and rotation workflows for secrets encryption.

pkg/secretsencrypt · medium confidence

The server package has been refactored to improve the initialization and lifecycle management of controllers. A new \Context\ struct and \NewContext\ constructor centralize the creation of Kubernetes and Wrangler client factories, replacing the previous scattered initialization logic. The \StartServer\ function now explicitly manages the startup sequence: it waits for the API server to be ready, runs startup hooks, stages files, and then starts the controllers. This change introduces a more robust lifecycle management for controllers, ensuring that components like the node password controller and leader-elected controllers are started in the correct order and with proper context cancellation. The \Config\ struct has been updated to include \StartupHooks\ and \Controllers\ fields, allowing for more flexible and modular server configuration.

pkg/server · high confidence

The agent tunnel implementation has been refactored to watch Kubernetes EndpointSlices instead of Endpoints, improving reliability and performance. The tunnel now supports EgressSelector modes (Cluster and Pod) to control which traffic is routed through the tunnel, and includes logic to wait for RBAC permissions before starting watches. Additionally, the tunnel respects the configured Kubelet port and address, and handles IPv6 addresses correctly when building proxy addresses.

pkg/agent/tunnel · medium confidence

The containerd agent's configuration and image loading logic has been refactored into new, platform-specific files. On Linux, the agent now supports cgroup v2, systemd cgroups, SELinux, and a wider range of container runtimes (crun, nvidia, and various WASM shims). On Windows, the agent configures the Windows container runtime and disables unsupported features like overlayfs. Both platforms now use a templated config generation system (config-v3.toml.tmpl) and a new \watcher.go\ to monitor the images directory for automatic image imports and pre-pulling. The \command.go\ and \config.go\ files handle process management and config writing, while \runtimes.go\ discovers available runtimes via PATH.

pkg/agent/containerd · high confidence

The tunnel server implementation was refactored to support egress proxy mode, tracking node and pod IP addresses via a CIDR trie for routing. The control-plane startup logic was restructured: the \Server\ function now delegates to \cfg.Cluster.Start\ and uses a delayed context cancellation, while the \Prepare\ function handles tunnel and authenticator setup. A new \TunnelServer\ struct manages the remotedialer server and watches for node/pod changes to update the routing table. Unit tests were added for the server startup logic.

pkg/daemons/control · high confidence

The file pkg/tls/storage.go, which previously handled the persistence and retrieval of TLS listener configuration via a Kubernetes Custom Resource (ListenerConfig), has been deleted. This removes the local storage mechanism for TLS state, indicating a shift away from using this specific Kubernetes resource for managing TLS configuration.

pkg/tls · high confidence

The generated Go types and controllers for the k3s.cattle.io/v1 API, including the ListenerConfig resource and its associated deep copy, client, and lifecycle adapter files, have been removed from the codebase. This eliminates the previously available API surface for managing ListenerConfig objects in the k3s.cattle.io group.

types/apis · high confidence

The main.go file in the types/codegen directory has been deleted. This file previously served as the entry point for generating types using the Norman generator, relying on the k3s.cattle.io/v1 API schema. Its removal indicates that this specific code generation process is no longer required or has been superseded by a different approach.

types/codegen · high confidence

The project has migrated from the external go-bindata library to Go's native embed package. This change updates the data loading mechanism in pkg/data to use the built-in embed functionality, which simplifies the codebase and removes the dependency on the previous binding tool.

pkg/data · high confidence

The project has migrated from the external go-bindata library to Go's built-in embed package for handling embedded static assets. This change updates the internal API for accessing embedded files, ensuring compatibility with modern Go tooling and linting requirements while maintaining the same functional interface for retrieving asset data and file names.

pkg/util/bindata · high confidence

The build system was restructured to support the K3s project. Legacy scripts for a different product (Rio) were removed, and new scripts were added to handle K3s-specific build tasks, including versioning, artifact validation, image scanning, and airgap packaging. The \version.sh\ script was replaced with a more robust \version.sh\ that extracts versions from Go modules. The \build\ script was updated to compile K3s binaries and their dependencies. The \ci\ script was updated to run the new \binary\_size\_check.sh\ and \download\ scripts. The \package\ script was updated to use the new \package-airgap\ and \package-cli\ scripts. The \validate\ script was updated to run \go mod tidy\ and \go mod verify\.

scripts · high confidence

Add CA certificate verification test for Docker environments; Add Docker conformance test suite; Add Docker scale test for large CNCF runners; Add Docker-based E2E tests for service traffic policies and firewall rules; Add Docker-based dual-stack integration test; Add Docker-based end-to-end tests for token management; Add E2E split-server test suite; Add E2E startup test suite for K3s cluster validation; Add E2E test suite for Tailscale integration; Add E2E tests for WebAssembly workloads; Add Ginkgo-based Docker skew test suite; Add Go-based e2e test suite for Docker-based etcd clusters; Add Rocky Linux 8 install test; Add T4 Docker test suite and test helpers; Add end-to-end test for node-external-ip configuration; Add end-to-end tests for etcd snapshotting to S3; Add end-to-end tests for private registry functionality; Add end-to-end tests for the embedded registry mirror; Add hardened Docker test suite for network policy verification; Add integration test for CA certificate rotation; Add integration test for dual-stack networking; Add integration tests for etcd snapshot management; Add integration tests for server startup scenarios; Added Docker-based snapshot restore test suite; Added Docker-based upgrade test suite for K3s; Added E2E test infrastructure and scripts; Added Fedora-based install test infrastructure; Added Go-based e2e test suite for Docker lazy pull functionality; Added Longhorn integration tests; Added SELinux RPM installation tests for SUSE and SLE Micro distributions; Added Terraform infrastructure for k3s performance testing; Added Vagrant-based install tests for openSUSE Leap and MicroOS; Added automated install test for Ubuntu 24.04; Added end-to-end test for Multus CNI integration; Added end-to-end test for custom CA certificate rotation; Added end-to-end tests for Btrfs snapshotter support; Added end-to-end tests for dual-stack (IPv4/IPv6) cluster configurations; Added end-to-end tests for secrets encryption; Added end-to-end tests for secrets encryption key rotation and lifecycle; Added end-to-end tests for the auto-import feature; Added install tests for CentOS 9 and Rocky Linux 9; Added integration test for Nix snapshotter; Added integration test for certificate rotation; Added integration test for custom etcd arguments; Added integration test for etcd snapshot restore; Added integration test for flannel-backend=none configuration; Added integration tests for K3s kube-\* server flags; Added integration tests for local storage functionality; Added integration tests for secrets encryption lifecycle; Added mock implementations for testing; Added performance test automation scripts; Added rootless E2E test suite; Added test fixture for etcd member zip; Consolidate test utility functions and add testing documentation; Convert Docker-based end-to-end tests to Go; E2E test infrastructure and utilities; New E2E test suite for cluster validation; New integration test infrastructure and flannel-ipv6-masq test.

The project's Go dependencies have been updated, most notably upgrading the Kubernetes version to 1.36.3-k3s1 and Go to 1.26.5. This update includes bumps to core components such as containerd v2.3.2, runc v1.4.2, etcd v3.6.14, and kine v0.16.3, alongside various other library updates to maintain compatibility and security.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 66.

• Code Health 64
• Architecture 100
• Maturity 74
• Readiness 75
• Security 61

• 300 commits — 248 feature/other, 52 fixes

• (root) — 89 commits
• .github/workflows — 67 commits
• pkg/agent — 14 commits
• pkg/cli — 13 commits
• pkg/etcd — 11 commits
• scripts/airgap — 11 commits
• (repo) — 10 commits
• manifests/traefik.yaml — 10 commits
• tests/e2e — 9 commits
• updatecli/updatecli.d — 8 commits
• manifests/coredns.yaml — 6 commits
• tests/docker — 5 commits
• pkg/cloudprovider — 4 commits
• pkg/daemons — 4 commits
• tests/integration — 4 commits
• pkg/executor — 3 commits
• pkg/server — 3 commits
• pkg/util — 3 commits
• .github/actions — 2 commits
• .github/dependabot.yml — 2 commits

• fix: Bump containerd with the fix for []byte Get tag from k3s-io/containerd
• fix: Bump cri-api and containerd for upstream env string fix
• fix: Bump golang.org/x/net to v0.55.0 to fix [CVE redacted] (#14203)
• fix: Bump helm-controller for job race fix
• fix: Bump kine for NATS conformance fixes
• fix: Bump kine for list/watch revision fixes
• fix: Bump kine for t4 fixes
• fix: Bump klipper-helm image for revision check fix
• fix: Bump spegel to v0.7.1 for libp2p-kad-dht panic fix
• fix: Download script fix to not be based for /v to use a better pattern for versions
• fix: Fix [CVE redacted]: Update docker/docker to v25.0.13 (#13473)
• fix: Fix S3 test
• fix: Fix SANs added from comma-separated node-external-ip list
• fix: Fix VPN node IP not being applied to kubelet (#13457)
• fix: Fix atomic write in WriteSubnetFile
• fix: Fix cloud-controller-manager exiting due to missing core RBAC
• fix: Fix coverage reports for e2e and integration tests
• fix: Fix cron to run everyday at 6PM UTC (#14041)
• fix: Fix deprecated updatecli apply command
• fix: Fix docker dualstack test
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

k3s-io/k3s was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.