Choosing the Right Datastore for K3s: SQLite vs. External DBs

The Overhead of the Kubernetes Control Plane

Standard Kubernetes relies on etcd, a distributed key-value store that requires a quorum of at least three nodes to maintain consistency. For edge deployments, IoT gateways, or local development environments, maintaining a three-node etcd cluster is often overkill. It consumes significant memory and introduces networking complexity that can outweigh the benefits of the orchestrator itself.

K3s solves this by substituting etcd with SQLite by default. This decision transforms the control plane from a distributed system into a lightweight, single-binary process, allowing a fully functional cluster to run on a single node with minimal resource footprints. The primary takeaway is simple: SQLite is ideal for single-server simplicity, but external databases are mandatory for high availability (HA).

How SQLite Simplifies the Edge

In a default K3s installation, the k3s server process encapsulates the API server, scheduler, and controller manager. Instead of communicating with a separate etcd cluster, it writes the cluster state directly to a local SQLite file. This eliminates the need for the etcd binary and its associated memory overhead.

This architecture is particularly effective for "single-node clusters" where the server also acts as the worker. Because SQLite is a file-based database, there are no ports to manage for the datastore and no complex certificates to rotate for a database cluster. The state is stored locally, making backups as simple as copying a directory.

Moving to High Availability with External DBs

SQLite is a local file; it cannot be shared across multiple server nodes. If you need a multi-master setup—where multiple K3s servers provide redundancy—you must move the state to a shared external database. K3s supports MySQL and PostgreSQL for this purpose.

In an HA configuration, multiple K3s servers connect to the same external database. The database becomes the single source of truth, allowing any server node to handle API requests and maintain the cluster state. This shifts the burden of availability from the K3s binary to the database layer.

Configuration Comparison: SQLite vs. PostgreSQL

Feature	Default (SQLite)	External (PostgreSQL)
Setup	Automatic / Zero-config	Manual DB provisioning
HA Support	Single-server only	Multi-server supported
Resource Use	Very Low	Moderate (External to K3s)
Storage	Local Disk File	Networked Database

Practical Example: Verifying the SQLite State

To confirm your K3s instance is using SQLite and to locate the state file, you can inspect the server logs and the filesystem. Run these commands on the server node with root or sudo permissions.

# Check logs for SQLite initialization
journalctl -u k3s | grep "database"

Expected check: Look for logs indicating the server is starting with the default SQLite datastore. To verify the physical location of the database, check the K3s data directory:

# List the database directory
ls -l /var/lib/rancher/k3s/server/db/

You should see a k3s.db file. This file contains the entire state of your cluster. Risk: Do not manually edit this file; doing so can corrupt the cluster state and require a full restore from backup.

Performance Limitations and Trade-offs

While SQLite is efficient, it has physical limitations. In edge deployments using SD cards (like Raspberry Pi), disk I/O latency can become a bottleneck. Because SQLite relies on synchronous writes to ensure data integrity, slow flash storage can lead to API server timeouts during high-churn events (e.g., scaling many pods simultaneously).

Additionally, SQLite is not designed for massive scale. If your cluster grows beyond a few dozen nodes or experiences constant state changes, the locking mechanism of SQLite may cause performance degradation compared to a dedicated database.

Closing Decision Matrix

When choosing your datastore, use this logic:

• Use SQLite if: You are running a single-node edge device, a local dev environment, or a small cluster where a single point of failure for the control plane is acceptable.
• Use External DB if: You require zero-downtime upgrades, multi-master redundancy, or are managing a larger fleet of nodes that exceed the I/O capabilities of a single local disk.