Using SQLite as K3s' Datastore for Lightweight Edge Clusters

Problem: Simplifying state management for small K3s deployments

When you run K3s on a single board computer, a virtual machine for CI, or a temporary demo cluster, the default etcd datastore adds operational overhead. You must monitor etcd health, manage its TLS certificates, and perform coordinated backups of multiple members. For workloads with low write frequency and a handful of nodes, this complexity can outweigh the benefits of a highly available key‑value store.

Thesis: Enabling the embedded SQLite datastore removes etcd overhead while keeping K3s functional, but it introduces scalability and consistency limits that must be understood before use.

When SQLite makes sense

• Single‑node or two‑node clusters where leader election is trivial.
• Development, testing, or edge environments with infrequent API writes (e.g., occasional deployments, monitoring scrapes).
• Scenarios where a single file backup/restore is preferable to coordinating etcd snapshots.

How to enable SQLite datastore

Start the K3s server with the --datastore-endpoint flag pointing to a SQLite file. The driver is bundled in the binary, so no extra installation is required.

# Run as root or with sudo
sudo k3s server \
  --datastore-endpoint sqlite3:///var/lib/rancher/k3s/server/db.sqlite \
  --disable=traefik \
  --write-kubeconfig-mode 644

Where to run: On the host that will act as the K3s server.
Permissions: The process needs write access to the directory containing the SQLite file (typically /var/lib/rancher/k3s/server/). Running as root or using sudo satisfies this.
Expected check: After the server starts, examine the journal or console output for the line Using sqlite3 datastore. If you see etcd‑related logs, the flag was not honored.

Verifying the setup and performing a safe backup

Once the server is up, you can confirm that cluster state is persisted in the SQLite file.

1. Check that the database file exists and is non‑zero:

ls -lh /var/lib/rancher/k3s/server/db.sqlite

1. Deploy a simple resource to generate writes:

kubectl get nodes   # should show the node Ready
kubectl run nginx --image=nginx --restart=Never

1. Observe file growth (size will increase modestly):

stat -c%s /var/lib/rancher/k3s/server/db.sqlite

Backup procedure: To obtain a consistent snapshot, stop the K3s server first (or rely on a clean shutdown via systemctl stop k3s). Then copy the SQLite file:

sudo systemctl stop k3s
sudo cp /var/lib/rancher/k3s/server/db.sqlite /backup/k3s-db-$(date +%F).sqlite
sudo systemctl start k3s

Copying the file while the server is running can produce an inconsistent snapshot because SQLite may hold active write transactions; restoring from such a backup may lead to startup errors or missing resources.

Trade‑offs and limitations

• Write concurrency: SQLite uses file‑level locking. Under heavy API write load (many concurrent pod creations, scaling events, or controller loops), you may see increased latency and occasional leader‑election‑like pauses because only one writer can proceed at a time.
• Node count: The feature is tested and recommended for up to roughly five nodes. Beyond that, the lack of etcd’s distributed consensus can cause stale reads and slower propagation of changes.
• No built‑in watch performance: etcd provides efficient watch mechanisms; SQLite relies on polling‑style notifications inside K3s, which can increase CPU usage when many clients watch resources.

If you anticipate sustained write rates higher than a few operations per second, or you need to run production workloads across many nodes, revert to the default etcd datastore by omitting the --datastore-endpoint flag.

Actionable closing

For edge or disposable clusters where operational simplicity outweighs the need for high write throughput, the SQLite datastore offers a straightforward backup‑friendly alternative to etcd. Start with the flag, verify the Using sqlite3 datastore log, and monitor the SQLite file size under your typical workload. If you notice latency spikes during scaling or frequent API calls, plan a migration to etcd before the cluster grows beyond a handful of nodes.