Project challenges / verified progress
Beacon: give it somewhere to live

The engineering notebook

Keep the database

How can Beacon keep SQLite data when Pods are disposable?

Loading Vault account...
Phase 3 — Share machines and keep state

Step 01 of 06

Understand the idea

A container’s local files can disappear when Kubernetes replaces a Pod. A PersistentVolume keeps selected data, such as Beacon’s database file, available across Pod restarts. It does not make SQLite safe for multiple writers on different machines.

STATE HAS THREE LAYERSStatefulSetstable pod identityPVCpod asks for storagePVcluster provides diskStorageClassprovisioning rulesNode diskkind stores locally
A Pod filesystem dies with the Pod. Durable state needs a claim, a provisioned volume and a workload shape that will not mount one SQLite file from two Pods during a rollout.
Step 01

Key technical ideas

Pod filesystems are ephemeral

Files written inside a container's writable layer disappear when the Pod is replaced. That is fine for caches and fatal for SQLite. A restart of the same container may preserve some local state briefly, but a reschedule or rollout does not. Durable data must live on a volume outside the container filesystem and be mounted into the Pod.

PVC is the app's storage request

A PersistentVolumeClaim says what the workload needs: size, access mode and optionally a StorageClass. A PersistentVolume is the actual storage the cluster binds to that claim. Dynamic provisioning lets a StorageClass create the PV automatically. In kind, the default provisioner uses local storage inside the node container, which is enough for learning, not for production durability.

SQLite makes rolling Deployment semantics dangerous

A Deployment with two replicas and one writable SQLite database is a trap. During rollout, old and new Pods can overlap. Two processes may try to write the same file unless the volume and app are carefully designed for it. SQLite is excellent for one writer in one place; it is not a shared multi-writer cluster database.

StatefulSet gives stable identity

A StatefulSet creates Pods with stable names like beacon-0 and stable volume claims derived from templates. It rolls them in order and keeps identity tied to storage. For Beacon's local SQLite version, one replica in a StatefulSet matches the database's shape: one service instance, one persistent database file, one clear owner.

A notebook cannot be in two desks
one notebook
one person writes safely
two people write at once
pages tear, order lies

SQLite is the notebook. It is robust, simple and honest about its shape. Kubernetes has to respect that shape instead of pretending every workload wants ten replicas.

PV, PVC, StorageClass and StatefulSet

TermQuestion answeredBeacon use

StorageClass

How is storage made?

kind default

PersistentVolume

What storage exists?

Provisioned disk

PVC

What does app request?

1Gi, RWO

Access mode

Who may mount it?

ReadWriteOnce

StatefulSet

Who owns stable storage?

beacon-0

Technical terms used at work

  • PersistentVolume — A cluster storage resource, provisioned manually or dynamically.

  • PersistentVolumeClaim — A namespaced request for storage made by a workload.

  • StorageClass — The rule set for dynamically creating volumes.

  • StatefulSet — A controller for Pods with stable names, ordered rollout and stable volume claims.