Storage Requirements
OLIVE uses ordinary PersistentVolumeClaims. It does not care which provisioner is behind them, and it has no opinion about how you operate that provisioner.
This page states what OLIVE claims and what it assumes. How you satisfy it — which storage system, which redundancy, which snapshot schedule, how you monitor capacity — is yours.
What claims storage
Per tenant:
| Component | Access mode | Size | Contents |
|---|---|---|---|
couchdb | ReadWriteOnce | couchdbPvcSize, default 1Gi | The tenant's connectivity content: datapoints, connectors, templates, authentication entries |
seaweedfs | ReadWriteOnce | seaweed.pvcSize | Uploaded files and the microfrontend components |
Per deployment:
| Component | Access mode | Size | Contents |
|---|---|---|---|
workflow-engine-postgres | ReadWriteOnce | size, default 10Gi | The Temporal workflow engine's PostgreSQL database, managed by CloudNativePG |
Vault and Keycloak also hold state, but they are cluster infrastructure rather than part of the OLIVE platform. See Infrastructure Charts.
ReadWriteOnceNo OLIVE component needs ReadWriteMany. Any provisioner that can serve RWO volumes is sufficient, which rules out the most common source of storage trouble before it starts.
Choosing the StorageClass
Every OLIVE volume resolves its StorageClass by the same rule, first hit wins:
global.localDev: true→local-path, for desktop clusters with no storage system installed.global.storageClassName, if set → that class, for every claim in the deployment.- The chart's own value (
storageClassName;cnpg.cluster.storage.storageClassfor the PostgreSQL clusters) → that class, for that chart. - Otherwise →
default.
How default is handled
default means the cluster's default StorageClass — the one kubectl get storageclass marks (default). Kubernetes has no special meaning for the string default (it would look for a class of that name, which EKS and RKE2 do not have), so the charts never render it: for default, and for an empty value, they leave storageClassName off the claim, which is how Kubernetes picks the default class. Any other value is rendered as-is.
| Cluster | Typical setting |
|---|---|
Cluster with a default StorageClass (EKS with gp2/gp3 marked default, most managed clusters) | default — nothing to set |
| EKS without a default class | gp3 (EBS CSI driver) |
| RKE2 with Longhorn | longhorn |
| Desktop / Rancher Desktop | global.localDev: true → local-path |
global:
storageClassName: default # or gp3, longhorn, ...
If the resolved class does not exist — or the cluster has no default class — the claims stay Pending and the pods with them, with no other symptom.
This resolution applies from the chart versions built on utilities 1.10.0 (couchdb 1.8.0, seaweedfs 1.2.0, workflow-engine-postgres 1.2.0, keycloak-infra 1.4.0) onwards, which is every chart in 1.3. Earlier versions rendered storageClassName: longhorn explicitly, and a StatefulSet's volume claim template is immutable — rendering a different value makes the StatefulSet update fail. On clusters installed with those earlier versions, set global.storageClassName: longhorn (or whatever they were created with) before upgrading.
See Chart Values Reference → Storage class for the deployment values.
What the class should provide
| Requirement | Why |
|---|---|
| Dynamic provisioning | The claims are created by the StatefulSets; nothing pre-creates volumes |
allowVolumeExpansion: true | Required to grow a volume after it has been created. Without it, growing a tenant's storage means a manual migration rather than editing the claim — see Sizing the volumes |
| A reclaim policy you have chosen deliberately | Delete removes the volume when the claim goes; Retain keeps it and holds the capacity until you release it by hand. Both are defensible — see Uninstall and Teardown for what each means when a tenant is removed |
| Encryption at rest, if your environment requires it | OLIVE configures no encryption of its own. Whether tenant data on disk is encrypted is decided entirely by this class — see Encryption at rest |
Encryption at rest
OLIVE encrypts nothing at rest, and has no value that turns it on. Every component writes to an ordinary PersistentVolumeClaim with no application-level encryption configured: a tenant's CouchDB, its SeaweedFS object storage, and the CloudNativePG PostgreSQL clusters behind Temporal and Keycloak. OLIVE neither sets up nor expects any store-specific encryption feature in any of them.
That makes this a StorageClass requirement, and a cluster-operator one. If the data has to be encrypted on disk, the class the claims resolve to must deliver it — an encrypted EBS class with a KMS key on EKS, an encrypted Longhorn or Ceph pool on RKE2, or whatever your CSI driver offers — and it has to be in place before the first deployment, because an existing volume is not encrypted retroactively by changing the class.
# What the classes on this cluster actually do — parameter names are driver-specific
kubectl get sc -o yaml | grep -E 'name:|encrypted|kmsKeyId|encryption'
Two things follow from it:
- Backups inherit nothing. A snapshot or a file-level backup of an encrypted volume is not itself encrypted unless the backup target encrypts it. That is a separate setting in your backup tool.
- Vault is the one exception. Vault encrypts its own storage backend with its unseal key regardless of the volume underneath, so Vault's contents are protected even on an unencrypted class. Nothing else in the stack behaves that way — and the Kubernetes Secrets that the Vault Secrets Operator materialises from it are plaintext again on the other side. See Secrets in etcd.
Enabling volume expansion
allowVolumeExpansion is a field on the StorageClass, not an OLIVE value. It is set wherever the class comes from — the Longhorn installation, the CSI driver's own chart, or the manifest your cluster bootstrap applies:
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: longhorn
provisioner: driver.longhorn.io
allowVolumeExpansion: true # sibling of provisioner, not under parameters
What the classes on a cluster currently allow:
kubectl get sc -o custom-columns='NAME:.metadata.name,EXPANSION:.allowVolumeExpansion,PROVISIONER:.provisioner'
The field is mutable, so it can be turned on for a class that already exists, and it then applies to volumes provisioned before the change:
kubectl patch sc <class> -p '{"allowVolumeExpansion":true}'
It has to be enabled before a resize is attempted. Enabling it afterwards does not complete a resize that was already rejected.
| Class | Expansion |
|---|---|
| Longhorn | Supported; the class Longhorn installs has the field set already |
EBS CSI (gp3) | Supported; current driver chart versions set it |
EKS in-tree gp2 | Supported by the driver, but the class EKS creates often leaves the field unset — patch it |
A class can carry allowVolumeExpansion: true over a driver that cannot expand volumes. The patch is accepted and the resize then never completes: the claim stays in Resizing or FileSystemResizePending with events and no progress, rather than failing outright. Confirm the driver supports expansion before relying on it.
Sizing the volumes
couchdbPvcSize and seaweed.pvcSize are read when the claim is created. Set them to the size the tenant is expected to need before the first deployment — that is the only point at which the size is purely a values decision.
| Value | Component | Default |
|---|---|---|
couchdbPvcSize | couchdb | 1Gi |
seaweed.pvcSize | seaweedfs | 20Gi |
A volume can only be made larger. Kubernetes rejects a smaller size, both in a new claim template and on an existing claim.
seaweedfs does not use more than 32 GBThe seaweedfs deployment is capped at 32 GB of usable object storage. Raising seaweed.pvcSize beyond that provisions a larger volume but no more usable capacity: uploads start failing at the cap while the volume still reports free space. The cap is not something seaweed.pvcSize changes. If a tenant needs more than 32 GB of object storage, raise it with OLIVE support at olive-support@boc-group.com rather than resizing the volume.
Increasing the size later
Changing the value in values.yaml on a running deployment is not sufficient. The size lives in the StatefulSet's volume claim template, which is immutable, and a claim template is never reapplied to a claim that already exists — so the sync is rejected and the volume keeps the size it was created with. This holds for couchdb and seaweedfs alike.
These steps need permissions a platform administrator does not have: deleting a StatefulSet in the tenant namespace, and reading the cluster's StorageClasses. They are the cluster operator's work. An administrator can set the size in values and nothing more — see Chart Values Reference → Volume sizes.
Growing an existing volume needs the resolved StorageClass to have allowVolumeExpansion: true, and then these steps per claim. The claims are named couchdb-data-<statefulset>-0 and data-<statefulset>-0:
# 1. Find the StatefulSet and its claim
kubectl get statefulset,pvc -n <namespace>
# 2. Remove the StatefulSet but keep its pod, its claim and its data
kubectl delete statefulset <statefulset> -n <namespace> --cascade=orphan
# 3. Grow the claim to the new size
kubectl patch pvc <claim> -n <namespace> \
-p '{"spec":{"resources":{"requests":{"storage":"20Gi"}}}}'
Then set the same size in values.yaml and sync. The StatefulSet is recreated with the new template and adopts the pod that is still running. Both sizes have to match, otherwise the deployment stays out of sync and the next sync fails again.
Confirm the volume actually grew:
kubectl get pvc <claim> -n <namespace> -o jsonpath='{.status.capacity.storage}{"\n"}'
If the reported capacity is still the old one, the filesystem is waiting for the pod to restart:
kubectl delete pod <pod> -n <namespace>
Step 2 is safe because the data-store StatefulSets retain their claims — see Volume retention below. Take a snapshot first regardless; these are live databases.
Volume retention
The data-store StatefulSets set persistentVolumeClaimRetentionPolicy to Retain for both whenDeleted and whenScaled. Deleting a StatefulSet therefore keeps its claim and its data.
Deleting the namespace deletes the claims anyway, and a claim that survives will be re-bound by a new deployment with the same names. Both facts matter mainly at teardown, which is where they are covered.
Backup labels on the data volumes
OLIVE labels the volume claims that hold state, so that a backup tool can select them. Which tool, and how it runs, is your decision — OLIVE marks what is worth backing up and takes no position on how the backup is taken.
One value controls it for couchdb and seaweedfs, and it belongs in the shared namespace values:
global:
volumeLabels:
my-backup-selector/include: 'true'
global.volumeLabels | Result |
|---|---|
| unset | the default label, olive-boc/backup: velero — the selector OLIVE's own example schedules use |
| a map | used verbatim, replacing the default entirely |
{} | no backup labels at all |
A map replaces rather than merges on purpose. Helm merges maps across values files, so a default defined in values.yaml could be added to but never replaced — one cluster's labels would always arrive on top of another's.
They are part of the StatefulSet's volumeClaimTemplates. A release installed with one set of labels has to keep rendering exactly that set, or every sync fails with spec: Forbidden.
So decide the label before the first install. Changing it later means recreating the StatefulSet, which is a data migration rather than a values change.
Which volumes actually matter, and which of them have to be captured together, is in What to Back Up.
Capacity
Storage grows with tenant content and uploaded files. Each tenant carries its own claims, so the footprint scales with the number of tenants rather than with load. Capacity is one of the three limits that make pods stay Pending; see Platform Scaling.
Not in scope
How you run storage is not documented here and is not something OLIVE supports: choosing a provisioner, installing or operating Longhorn, Ceph or a cloud CSI driver, monitoring capacity and I/O, snapshot scheduling and retention, replica placement, or migrating between storage systems. Those belong to your storage platform's documentation and to whoever operates your cluster.