The integration and subsequent removal of K3s within TrueNAS Scale represents one of the most significant pivots in the evolution of iXsystems' storage platform. Originally introduced as the bedrock for the "Apps" ecosystem, K3s—a lightweight Kubernetes distribution—was intended to modernize how users deployed containerized workloads on their NAS hardware. By leveraging the orchestration capabilities of Kubernetes, TrueNAS Scale sought to move beyond the restrictive nature of traditional jail systems found in TrueNAS Core, offering a scalable, industry-standard method for managing microservices, databases, and utility applications. However, the intersection of Kubernetes' inherent complexity and the specific needs of the home-lab and small-enterprise user base created a friction point that eventually led to a fundamental shift in the OS architecture.
The K3s Implementation and User Experience
For a substantial period, K3s served as the invisible engine powering the application interface in TrueNAS Scale. The adoption was met with significant enthusiasm from both the development teams and the power-user community, who viewed the move to Kubernetes as a liberation from "old thinking" architectural patterns. The primary goal was to provide a flexible environment where users could deploy complex application stacks without manually managing the underlying container networking and storage volumes.
From a technical perspective, the K3s implementation allowed for the use of Helm charts, which are packages of information that Kubernetes uses to reproduce applications. This allowed iXsystems and third-party providers like TrueCharts to offer "one-click" installations of complex software. However, this abstraction layer came with a cost. The sheer richness and complexity of Helm charts often led to instability. Different sets of charts frequently clashed, creating a fragmented user experience where one application's requirements would break another's configuration. This volatility made the charts difficult to maintain, port, and integrate into the core TrueNAS experience, ultimately leading to a decision to deprecate this specific method of deployment.
Accessing the Kubernetes API and Remote Management
By default, TrueNAS Scale limits direct interaction with the underlying K3s cluster to prevent accidental configuration drift or security vulnerabilities. The K3s API typically listens on port 6443. While the service is active, it is shielded by the system's IPTABLES configuration to prevent unauthorized external access.
For users who require direct administrative control over their cluster, there are specific technical hurdles to overcome. The Kubernetes API is protected by a DROP rule in the IPTABLES. To grant external access, a user must manually remove this restriction. This can be achieved through two primary methods:
Using a helper script known as Truetool, which provides a simplified wrapper for common bash operations:
./truetool.sh --kubeapi-enable
Using the direct iptables command to delete the specific rule created by iXsystems:
iptables -D INPUT -p tcp -m tcp --dport 6443 -m comment --comment "iX Custom Rule to drop connection requests to k8s cluster from external sources" -j DROP
Once the port is open, the administrator must transfer the kubeconfig file located at /etc/rancher/k3s/k3s.yaml to a local management machine. On the local machine, the KUBECONFIG environment variable must be set to point to this file to allow tools like kubectl to authenticate with the TrueNAS cluster.
Example of local configuration:
export KUBECONFIG=/Users/sab/.kube/truenas
kubectl get ns
A critical operational detail is that these IPTABLES changes are not persistent. Upon a system reboot, the network rules are reverted to their initial state, meaning the DROP rule is reapplied, and external API access is severed.
Local Cluster Interaction and Tooling
For users who prefer not to expose their API to the network, local interaction is possible but comes with ergonomic trade-offs. The most direct method is utilizing the built-in sudo k3s kubectl command. While this avoids the need for external configuration files, it introduces several inefficiencies:
- The user is prompted for the sudo password for every single command execution.
- Advanced management tools like
k9sfail to function correctly because they rely onkubectl editunder the hood, which does not bridge well with the sudo wrapper.
To resolve these issues, the recommended path for power users is the installation of a standalone kubectl binary and k9s on the local shell, ensuring that the shell's path includes ~/bin. This allows for a more seamless interaction with the cluster namespaces, such as default, kube-system, kube-public, kube-node-lease, openebs, and specific application namespaces like ix-pihole or tc-system.
The Migration to Native Docker
As of version 24.10, TrueNAS Scale underwent a massive architectural shift, moving away from Kubernetes/K3s in favor of native Docker. This decision was driven by the realization that the vast majority of the user base—estimated by some community members to be as high as 99%—preferred the simplicity and ubiquity of Docker over the orchestration overhead of Kubernetes.
This transition has significant implications for users on newer versions, such as 25.04.1. On these versions, commands related to k3s or kubectl will return "command not found" errors because the binaries and the underlying service have been removed from the OS. This shift effectively eliminates the "Kubernetes tax"—the CPU and RAM overhead required to run the K3s control plane—and replaces it with a leaner container engine.
For users who relied on the DNS-like service discovery provided by K3s, where containers could be reached by name on an internal network, the move to Docker requires alternative solutions. Some users have turned to third-party projects to replicate this internal networking behavior, ensuring that Docker containers remain accessible via DNS names within the local network.
Comparative Analysis of Orchestration Strategies
The transition from K3s to Docker represents a move from a complex orchestrator to a simple container runtime. The following table outlines the differences in how these technologies function within the TrueNAS ecosystem.
| Feature | K3s (Legacy Scale) | Native Docker (Current Scale) |
|---|---|---|
| Primary Goal | Microservices Orchestration | Simple Application Deployment |
| Configuration Method | Helm Charts / YAML | Docker Compose / UI |
| Resource Overhead | Moderate to High | Low |
| Networking | K8s CNI / Service DNS | Docker Bridge / Custom Networks |
| Learning Curve | Steep (Kubernetes API) | Shallow (Container basics) |
| Stability | Variable (Chart conflicts) | High (Standardized) |
| Management Tools | kubectl, k9s, Helm | docker cli, Portainer |
Impact on Enterprise and Community Users
The removal of K3s has created a divide in how different user tiers interact with TrueNAS. iXsystems has acknowledged that while the majority of the community prefers Docker, there are legitimate enterprise use cases for Kubernetes.
For Enterprise users, the solution provided is the implementation of a Sandbox. K3s support is maintained within a Sandbox environment for those who absolutely require Kubernetes orchestration for their workloads. This ensures that corporate clients can maintain their existing CI/CD pipelines and orchestration logic without being forced into a Docker-only workflow.
For the broader community, the focus has shifted toward providing guides on running Kubernetes within a Sandbox. This allows the user to maintain the core stability of the TrueNAS OS while experimenting with K3s in an isolated environment. This approach prevents the "bad experience" caused by conflicting Helm charts from affecting the stability of the primary storage system.
Technical Challenges and Failures in the K3s Era
The period of K3s integration was not without significant technical friction. Users attempting to deploy complex identity providers, such as Authentik, encountered systemic issues with ingress and environment variables. For instance, users reported that passing the AUTHENTIK_EXTERNAL_HOST variable did not successfully populate the OpenID Configuration URL inside the application.
Attempts to resolve these issues by converting "Official" apps to "Custom" apps to manually inject ingress rules often resulted in validation errors, such as Additional property ingress is not allowed. These failures highlight the rigidity of the TrueNAS app wrapper; because the system was designed to abstract the Kubernetes complexity, it often blocked the very advanced configurations that power users needed to fix broken applications.
The DevOps Perspective: Moving Beyond Integrated K3s
For the professional DevOps engineer or the "extreme" tech enthusiast, the integrated K3s in TrueNAS was often seen as a "black box" that offered too many restrictions and too little transparency. The inability to easily manage the cluster manually, combined with the risk of the OS overriding custom configurations during updates, led many to seek a complete decoupling of storage and orchestration.
The emerging best practice for these users is to treat TrueNAS strictly as a storage provider (via NFS or iSCSI) and to deploy a dedicated Kubernetes cluster on separate hardware. This can be achieved through automation tools like Ansible, allowing for a "proper" K3s setup that is independent of the NAS operating system. By removing the orchestration layer from the storage server, the user gains:
- Total control over the K3s API and versioning.
- Freedom to use any Helm chart without iXsystems' wrapper restrictions.
- Elimination of the risk that an OS update will wipe out IPTABLES rules or modify the kubeconfig.
- Ability to scale the cluster across multiple nodes (Multi-node K3s) rather than being limited to a single-node cluster on the NAS.
Final Technical Analysis of the Architectural Pivot
The trajectory of TrueNAS Scale from K3s to Docker is a case study in the tension between "feature completeness" and "user accessibility." Kubernetes is an industry-standard tool, but its application within a NAS OS introduced a layer of complexity that outweighed its benefits for the average user. The reliance on Helm charts created a fragile ecosystem where the "ease of use" promised by the UI was undermined by the underlying instability of the charts.
By reverting to native Docker, iXsystems has effectively simplified the software stack. This reduces the attack surface by removing the exposed K3s API and reduces the resource footprint on the host machine. While some users view this as "going backwards," from a systems engineering perspective, it is a move toward stability. The failure of the K3s concept in TrueNAS was not a failure of Kubernetes itself, but a failure of the abstraction layer used to present Kubernetes to a non-specialist audience.
The transition underscores a fundamental truth in consumer electronics and smart device software: the most powerful tool is not always the best tool if the friction of management exceeds the value of the feature. For the minority of users who require the power of K3s, the transition to Sandbox environments or external clusters provides a sustainable path forward that does not compromise the integrity of the storage platform.