Skip to content

feat(openhab): support shared PVCs and configurable subpaths #969

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
drieks wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(openhab): support shared PVCs and configurable subpaths #969

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 23 additions & 2 deletions charts/openhab/DESIGN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,29 @@ openHAB has three durable directory classes:
things, sitemaps, rules, and service configuration.
- `/openhab/addons` stores drop-in addon JAR files.

The chart creates one PVC per directory by default. Each PVC can be sized
independently or replaced with an existing claim for migration scenarios.
By default, the chart retains the established layout of one PVC per directory.
Set `persistence.claim.enabled=true` to create one release-specific
`<fullname>-data` PVC instead. In that mode, the chart mounts the `userdata`,
`conf`, and `addons` subdirectories into their respective openHAB paths. A
`create-persistence-subpaths` init container creates those subdirectories before
the main container starts, so the mounts do not replace the non-empty directory
structure supplied by the image.

The per-directory `size`, `storageClass`, and `accessMode` settings configure
the default dedicated PVCs. `existingClaim` takes precedence for an individual
directory in either storage mode.

`subPath` is an explicit escape hatch only for an existing or legacy dedicated
PVC; it is deliberately rejected for the chart-managed shared PVC, whose
directory names are fixed by the chart. Every `subPath` must be relative and cannot
contain traversal segments. An existing claim used for more than one openHAB
directory must provide a `subPath` for every use. Mounting one claim's root at
multiple application paths aliases unrelated data directories and is therefore
a template-time configuration error.

The backup CronJob uses the same claim and subpath resolution as the StatefulSet
and creates selected backup subpaths before its read-only backup mounts are
attached. This keeps backups aligned with the running workload's storage view.

## Configuration Design

Expand Down
25 changes: 22 additions & 3 deletions charts/openhab/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,16 +134,35 @@ Use feature flags instead to enable optional components.

### Persistence Parameters

The default remains the established three-PVC layout. To opt into a single
shared PVC, follow the [storage migration procedure](UPGRADING.md#storage-layout-migration)
and set `persistence.claim.enabled=true`.
In shared-PVC mode, the per-directory size, storage class, and access-mode
settings are not used.

| Parameter | Description | Default |
|-----------|-------------|---------|
| `persistence.claim.enabled` | Opt into one shared PVC for userdata, conf, and addons | `false` |
| `persistence.claim.size` | Generated release-specific data PVC size | `5Gi` |
| `persistence.claim.storageClass` | Generated PVC storage class | `""` (cluster default) |
| `persistence.userdata.enabled` | Enable userdata PVC | `true` |
| `persistence.userdata.size` | userdata PVC size | `5Gi` |
| `persistence.userdata.size` | userdata dedicated PVC size | `5Gi` |
| `persistence.userdata.storageClass` | Storage class | `""` (cluster default) |
| `persistence.userdata.existingClaim` | Use existing PVC | `""` |
| `persistence.userdata.subPath` | Relative directory in an existing or dedicated userdata PVC | unset |
| `persistence.conf.enabled` | Enable conf PVC | `true` |
| `persistence.conf.size` | conf PVC size | `1Gi` |
| `persistence.conf.size` | conf dedicated PVC size | `1Gi` |
| `persistence.conf.existingClaim` | Existing PVC for conf | `""` |
| `persistence.conf.subPath` | Relative directory in an existing or dedicated conf PVC | unset |
| `persistence.addons.enabled` | Enable addons PVC | `true` |
| `persistence.addons.size` | addons PVC size | `2Gi` |
| `persistence.addons.size` | addons dedicated PVC size | `2Gi` |
| `persistence.addons.existingClaim` | Existing PVC for addons | `""` |
| `persistence.addons.subPath` | Relative directory in an existing or dedicated addons PVC | unset |

> **Warning:** A new PVC may contain a `lost+found` directory at its root.
> openHAB then does not recognize the mounted directory as empty on its first
> start, skips initialization, and fails to start. Use a dedicated, empty
> `subPath` instead of mounting the PVC root in this case.

### ConfigMap Parameters

Expand Down
71 changes: 71 additions & 0 deletions charts/openhab/UPGRADING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Upgrading openHAB

## Storage layout migration

This release adds an optional chart-managed shared PVC with `userdata`, `conf`,
and `addons` subpaths. The default remains the existing three chart-managed
PVCs, so a normal upgrade preserves the current storage layout.

### Previous main-branch behavior

`persistence.userdata`, `persistence.conf`, and `persistence.addons` each
created their own PVC by default. Their independent `size`, `storageClass`,
and `accessMode` settings applied to those PVCs. An `existingClaim` replaced
the PVC for that individual directory. The chart allowed these three settings
to remain configured alongside `existingClaim`; in that case they had no
effect because the existing PVC took precedence.

### Opt in to a shared PVC

There are two supported arrangements:

1. Set `persistence.claim.enabled=true`. With no per-directory `existingClaim`,
the chart creates one `<fullname>-data` PVC using `persistence.claim`. It mounts the `userdata`,
`conf`, and `addons` subpaths at the corresponding openHAB directories.
2. Set `existingClaim` for any one, two, or all three directories. The
remaining enabled directories use the chart-managed shared PVC. `subPath`
can be set only for an existing claim; chart-managed shared subpaths are
fixed. Per-directory `size`, `storageClass`, and `accessMode` values are
not used in shared-PVC mode.

### Preserve the current three-PVC layout

This is the default behavior. Existing releases can be upgraded normally,
including with `--reuse-values`; their PVC names and roots remain unchanged.

```yaml
persistence:
userdata:
size: 5Gi
storageClass: <existing-storage-class>
conf:
size: 1Gi
storageClass: <existing-storage-class>
addons:
size: 2Gi
storageClass: <existing-storage-class>
```

Use the actual existing settings, which can be inspected with:

```bash
kubectl get pvc -n <namespace>
```

Then upgrade with those values (or use `--reuse-values`):

```bash
helm upgrade <release> <chart> -n <namespace> -f openhab-storage-upgrade.yaml
```

### Migrate into the new shared PVC

Back up the three existing PVCs first. Create or allow the chart to create a
shared PVC sized for all data, then copy the old PVC roots into `userdata`,
`conf`, and `addons` respectively using a temporary pod or your storage
provider's migration tool. Only after verifying the copies should the new
release mount that shared PVC with the default subpaths. Finally upgrade with
`persistence.claim.enabled=true`.

Do not delete the old PVCs until openHAB has started successfully and the data
has been verified.
102 changes: 86 additions & 16 deletions charts/openhab/docs/storage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ historical persistence data.

## Directories Overview

| Directory | PVC Key | Default Size | Content |
|-----------|---------|-------------|---------|
| `/openhab/userdata` | `persistence.userdata` | 5Gi | Runtime state, JSONDB, logs, persistence data |
| `/openhab/conf` | `persistence.conf` | 1Gi | Items, things, rules, sitemaps, services config |
| `/openhab/addons` | `persistence.addons` | 2Gi | Drop-in JAR bindings/addons |
| Directory | Default PVC | Shared-PVC subPath | Content |
|-----------|-------------|--------------------|---------|
| `/openhab/userdata` | Dedicated userdata PVC | `userdata` | Runtime state, JSONDB, logs, persistence data |
| `/openhab/conf` | Dedicated conf PVC | `conf` | Items, things, rules, sitemaps, services config |
| `/openhab/addons` | Dedicated addons PVC | `addons` | Drop-in JAR bindings/addons |

## userdata

Expand Down Expand Up @@ -48,20 +48,96 @@ Most users will keep this empty (addons installed via the UI go to `userdata`).

**Minimum recommended size**: 2Gi.

## Using Existing PVCs
## PVC Configuration

If you have pre-existing data on PVCs, use `existingClaim`:
By default, the chart creates one dedicated PVC per openHAB directory, matching
the historical chart behavior. Set `persistence.claim.enabled=true` to opt into
one shared PVC. In shared-PVC mode, the chart mounts every directory through a
relative `subPath` and an init container creates these directories before
openHAB starts.

### Default: create three dedicated PVCs

With the default values, the chart creates `<fullname>-userdata`,
`<fullname>-conf`, and `<fullname>-addons`. No persistence configuration is
required. Configure each directory independently when needed.

### Opt in to a single shared PVC

Set `persistence.claim.enabled=true` to create one release-specific PVC named
`<fullname>-data`, mounted with the `userdata`, `conf`, and `addons` subpaths:

```yaml
persistence:
claim:
enabled: true
storageClass: local-path
accessMode: ReadWriteOnce
size: 10Gi
```

The per-directory `size`, `storageClass`, and `accessMode` settings are not
used in shared-PVC mode.

### Use existing PVCs per directory

Set `existingClaim` for any combination of one, two, or all three directories.
When shared-PVC mode is enabled, an enabled directory without an existing claim
uses the chart-managed shared PVC. A single existing PVC can be mounted at its root; an existing PVC shared
by multiple openHAB directories requires a distinct `subPath` for every
directory:

```yaml
persistence:
userdata:
existingClaim: openhab-userdata
conf:
existingClaim: openhab-conf
subPath: data/openhab-conf
```

For one existing shared PVC, repeat its name for each directory that should use
it. When multiple directories resolve to the same claim, the chart renders one
Kubernetes volume and mounts each configured `subPath` from it.

```yaml
persistence:
userdata:
existingClaim: my-openhab-userdata
existingClaim: my-openhab-data
subPath: userdata
conf:
existingClaim: my-openhab-conf
existingClaim: my-openhab-data
subPath: conf
addons:
existingClaim: my-openhab-addons
existingClaim: my-openhab-data
subPath: addons
```

`subPath` is available only with an `existingClaim` or in the default dedicated
PVC mode. It must be relative and
must not contain `..` segments. When one existing claim is used for multiple
directories, each directory must use a distinct `subPath`.

### Configure dedicated PVCs

Set `size`, `storageClass`, or `accessMode` under a directory to configure its
dedicated PVC. An `existingClaim` takes precedence for that directory.

```yaml
persistence:
userdata:
size: 10Gi
storageClass: local-path
```

This is the default and preserves compatibility with previous releases.

> **Warning:** Some filesystems create a `lost+found` directory at the root of
> a new PVC. openHAB then does not consider the mounted directory empty during
> its first start, skips initialization, and fails to start. Mount a dedicated,
> empty `subPath` (for example `openhab/userdata`) instead of the PVC root in
> this case.

## Storage Class Recommendations

For home automation, low-latency local storage is preferred:
Expand All @@ -71,12 +147,6 @@ persistence:
userdata:
storageClass: "local-path" # k3s default
size: 10Gi
conf:
storageClass: "local-path"
size: 2Gi
addons:
storageClass: "local-path"
size: 5Gi
```

## Backup
Expand Down
6 changes: 3 additions & 3 deletions charts/openhab/templates/NOTES.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ App : {{ .Chart.AppVersion }}
================================================================================

{{- if .Values.persistence.userdata.enabled }}
userdata ({{ .Values.persistence.userdata.size }}): Runtime state, logs, JSONDB
userdata ({{ if .Values.persistence.claim.enabled }}shared PVC {{ .Values.persistence.claim.size }}{{ else }}{{ .Values.persistence.userdata.size }} dedicated PVC{{ end }}): Runtime state, logs, JSONDB

@coderabbitai coderabbitai Bot Aug 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Do not report configured sizes for existing PVCs.

The persistence.claim.enabled condition distinguishes shared mode from dedicated mode, but it does not distinguish generated PVCs from existing PVCs. As a result, Line 77 can display persistence.claim.size for a shared existing PVC, and Lines 86 and 95 can display per-directory sizes for dedicated existing PVCs. Those values may not describe the actual PVC capacity.

Use the resolved claim source for the label and size. Show a size only when Helm creates the PVC. Use distinct wording for generated shared claims, shared existing claims, and dedicated existing claims. Add render coverage for all three cases.

Also applies to: 86-86, 95-95

🧰 Tools
🪛 LanguageTool

[style] ~77-~77: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...sistence.claim.enabled }}shared PVC {{ .Values.persistence.claim.size }}{{ else }}{{ ....

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

[style] ~77-~77: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ....persistence.claim.size }}{{ else }}{{ .Values.persistence.userdata.size }} dedicated ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@charts/openhab/templates/NOTES.txt` at line 77, Update the NOTES descriptions
for userdata, addons, and backups to use the resolved claim source rather than
only persistence.claim.enabled: distinguish generated shared claims, shared
existing claims, and dedicated existing claims, and omit configured sizes
whenever the PVC already exists. Add Helm render coverage covering all three
claim scenarios and verify the labels and size suppression for each.

PVC: {{ include "openhab.userdataPvcName" . }}
Mount: /openhab/userdata
{{- else }}
Expand All @@ -83,7 +83,7 @@ App : {{ .Chart.AppVersion }}
{{- end }}

{{- if .Values.persistence.conf.enabled }}
conf ({{ .Values.persistence.conf.size }}): Configuration files synced before startup
conf ({{ if .Values.persistence.claim.enabled }}shared PVC{{ else }}{{ .Values.persistence.conf.size }} dedicated PVC{{ end }}): Configuration files synced before startup
PVC: {{ include "openhab.confPvcName" . }}
Mount: /openhab/conf
{{- else }}
Expand All @@ -92,7 +92,7 @@ App : {{ .Chart.AppVersion }}
{{- end }}

{{- if .Values.persistence.addons.enabled }}
addons ({{ .Values.persistence.addons.size }}): Drop-in JAR addons
addons ({{ if .Values.persistence.claim.enabled }}shared PVC{{ else }}{{ .Values.persistence.addons.size }} dedicated PVC{{ end }}): Drop-in JAR addons
PVC: {{ include "openhab.addonsPvcName" . }}
Mount: /openhab/addons
{{- end }}
Expand Down
Loading
Loading