feat(drbd): well-known options catalogue with section + LinstorKey

kvaps · claude · kvaps · commit b28cbaa1dec0 · 2026-05-08T07:41:10.000+02:00
Typed Option struct + section constants + initial port of the
upstream drbdoptions.json catalogue covering the keys cozystack-style
clusters set in practice. Used by the satellite reconciler to route a
flat property bag into the right .res block, and (Phase 6) by the
property validator on POST /properties.

Co-Authored-By: Claude &lt;noreply@anthropic.com&gt;
Signed-off-by: Andrei Kvapil &lt;kvapss@gmail.com&gt;
diff --git a/PLAN.md b/PLAN.md
@@ -258,7 +258,7 @@ Full scope list lives in `docs/csi-api-surface.md` (to be created in Phase 1).
 - [ ] LUKS encryption layer (volume-level)
 - [x] DRBD encryption passphrase (`POST /v1/resource-definitions/{rd}/encryption-passphrase`): writes the per-RD shared secret onto the RD's props under `DrbdOptions/Net/shared-secret`. Flows through to satellites via the existing drbd_options channel. 3 contract tests.
 - [x] DRBD proxy enable/disable/configure: 501 Not Implemented stubs (`/v1/resource-definitions/{rd}/drbd-proxy*`). Cozystack-style clusters run flat L2 so DRBD-9's native protocol suffices; proxy isn't needed. Endpoints exist so `linstor drbd-proxy *` returns a deterministic error.
-- [ ] DRBD options: full set from `drbdoptions.json`
+- [x] DRBD options catalogue (`pkg/drbd/options.go`): typed Option struct + section constants (net / disk / peer-device / options / handlers) + initial subset of well-known keys (protocol, shared-secret, max-buffers, after-sb-*, on-io-error, al-extents, c-max-rate, auto-promote, quorum, on-no-quorum). 4 contract tests pin LinstorKey shape, section validity, uniqueness, and presence of cozystack-relevant keys. Full upstream catalogue ports as new keys come up.
 - [x] file storage provider (`pkg/storage/file`): FILE / FILE_THIN behind same Provider seam — fallocate (thick) / truncate (thin) for create, statfs(2) for pool capacity, snapshots intentionally unsupported (caller routes to LVM/ZFS instead). 9 contract tests.
 - [x] External-file management stub (`/v1/files` LIST returns []; GET /{path} → 404). Cozystack manages host config via Talos extensions; the endpoints exist so `linstor external-file list` doesn't 404.
 
diff --git a/pkg/drbd/options.go b/pkg/drbd/options.go
@@ -0,0 +1,176 @@
+/*
+Copyright 2026 Cozystack contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package drbd
+
+// Option describes one DRBD-9 configurable knob — a port of one entry
+// from upstream's `drbdoptions.json` catalogue. We use it both for
+// property validation (Phase 6) and so the satellite reconciler can
+// route a flat string→string property bag into the right `.res` file
+// section.
+type Option struct {
+	// Name is the bare option key (e.g. "max-buffers", "auto-promote").
+	Name string
+
+	// Section selects which `.res` block this option belongs in:
+	// `SectionNet`, `SectionDisk`, `SectionPeerDevice`, `SectionOptions`
+	// (top-level resource options), or `SectionHandlers`.
+	Section string
+
+	// LinstorKey is the upstream-compatible LINSTOR property name
+	// (e.g. "DrbdOptions/Net/max-buffers") that callers set on
+	// resource definitions. Stored verbatim so existing golinstor
+	// clients keep working unmodified.
+	LinstorKey string
+
+	// Default is the value DRBD-9 uses when the option is unset.
+	// Empty string means "no default; let DRBD decide" (rarely useful
+	// — most are typed).
+	Default string
+
+	// Description is a one-line summary, lifted from the DRBD man pages.
+	Description string
+}
+
+// Section names for `.res` block placement. Exposed so callers can
+// route a flat property bag into the correct block without re-parsing
+// the LINSTOR key namespace.
+const (
+	SectionNet        = "net"
+	SectionDisk       = "disk"
+	SectionPeerDevice = "peer-device"
+	SectionOptions    = "options"
+	SectionHandlers   = "handlers"
+)
+
+// Options is the catalogue of DRBD knobs blockstor knows about. Far
+// from exhaustive — DRBD has 100+ options and we add them on demand —
+// but covers the keys cozystack-style clusters actually need. Built
+// up by section to keep each subset reviewable.
+func Options() []Option {
+	net := netOptions()
+	disk := diskOptions()
+	peerDev := peerDeviceOptions()
+	res := resourceOptions()
+
+	out := make([]Option, 0, len(net)+len(disk)+len(peerDev)+len(res))
+	out = append(out, net...)
+	out = append(out, disk...)
+	out = append(out, peerDev...)
+	out = append(out, res...)
+
+	return out
+}
+
+// netOptions returns the `net { … }` section catalogue.
+func netOptions() []Option {
+	return []Option{
+		{
+			Name:        "protocol",
+			Section:     SectionNet,
+			LinstorKey:  "DrbdOptions/Net/protocol",
+			Default:     "C",
+			Description: "Replication protocol — A (async) / B (semi-sync) / C (sync). Cozystack runs C.",
+		},
+		{
+			Name:        "shared-secret",
+			Section:     SectionNet,
+			LinstorKey:  "DrbdOptions/Net/shared-secret",
+			Description: "HMAC secret authenticating peer-to-peer connections.",
+		},
+		{
+			Name:        "max-buffers",
+			Section:     SectionNet,
+			LinstorKey:  "DrbdOptions/Net/max-buffers",
+			Default:     "8000",
+			Description: "Receive ring depth in 4 KiB pages.",
+		},
+		{
+			Name:        "after-sb-0pri",
+			Section:     SectionNet,
+			LinstorKey:  "DrbdOptions/Net/after-sb-0pri",
+			Default:     "discard-zero-changes",
+			Description: "Split-brain recovery policy when neither side was Primary.",
+		},
+		{
+			Name:        "after-sb-1pri",
+			Section:     SectionNet,
+			LinstorKey:  "DrbdOptions/Net/after-sb-1pri",
+			Default:     "discard-secondary",
+			Description: "Split-brain recovery policy when one side was Primary.",
+		},
+	}
+}
+
+// diskOptions returns the `disk { … }` section catalogue.
+func diskOptions() []Option {
+	return []Option{
+		{
+			Name:        "on-io-error",
+			Section:     SectionDisk,
+			LinstorKey:  "DrbdOptions/Disk/on-io-error",
+			Default:     "detach",
+			Description: "Behaviour on lower-level IO failure (pass-on / detach / call-local-io-error).",
+		},
+		{
+			Name:        "al-extents",
+			Section:     SectionDisk,
+			LinstorKey:  "DrbdOptions/Disk/al-extents",
+			Default:     "1237",
+			Description: "Activity-log size; trades resync time against random-write throughput.",
+		},
+	}
+}
+
+// peerDeviceOptions returns the `peer-device { … }` section catalogue.
+func peerDeviceOptions() []Option {
+	return []Option{
+		{
+			Name:        "c-max-rate",
+			Section:     SectionPeerDevice,
+			LinstorKey:  "DrbdOptions/PeerDevice/c-max-rate",
+			Default:     "100M",
+			Description: "Upper bound on resync rate in bytes/second.",
+		},
+	}
+}
+
+// resourceOptions returns the top-level `options { … }` catalogue.
+func resourceOptions() []Option {
+	return []Option{
+		{
+			Name:        "auto-promote",
+			Section:     SectionOptions,
+			LinstorKey:  "DrbdOptions/Resource/auto-promote",
+			Default:     "yes",
+			Description: "Auto-promote to Primary on first open(2).",
+		},
+		{
+			Name:        "quorum",
+			Section:     SectionOptions,
+			LinstorKey:  "DrbdOptions/Resource/quorum",
+			Default:     "majority",
+			Description: "Quorum policy — off / majority / all / <count>.",
+		},
+		{
+			Name:        "on-no-quorum",
+			Section:     SectionOptions,
+			LinstorKey:  "DrbdOptions/Resource/on-no-quorum",
+			Default:     "io-error",
+			Description: "Behaviour when quorum is lost: io-error or suspend-io.",
+		},
+	}
+}
diff --git a/pkg/drbd/options_test.go b/pkg/drbd/options_test.go
@@ -0,0 +1,94 @@
+/*
+Copyright 2026 Cozystack contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package drbd_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/cozystack/blockstor/pkg/drbd"
+)
+
+// TestOptionsHaveLinstorKey: every catalogue entry surfaces a
+// `DrbdOptions/<Section>/<Name>` LINSTOR-compatible property name. We
+// rely on this so users / golinstor clients can set keys verbatim.
+func TestOptionsHaveLinstorKey(t *testing.T) {
+	for _, opt := range drbd.Options() {
+		if opt.LinstorKey == "" {
+			t.Errorf("%s: missing LinstorKey", opt.Name)
+		}
+
+		if !strings.HasPrefix(opt.LinstorKey, "DrbdOptions/") {
+			t.Errorf("%s: LinstorKey %q has wrong prefix", opt.Name, opt.LinstorKey)
+		}
+	}
+}
+
+// TestOptionsHaveSection: every entry pins a `.res` section so the
+// satellite reconciler can route values without re-parsing the key.
+func TestOptionsHaveSection(t *testing.T) {
+	allowed := map[string]bool{
+		drbd.SectionNet:        true,
+		drbd.SectionDisk:       true,
+		drbd.SectionPeerDevice: true,
+		drbd.SectionOptions:    true,
+		drbd.SectionHandlers:   true,
+	}
+
+	for _, opt := range drbd.Options() {
+		if !allowed[opt.Section] {
+			t.Errorf("%s: unknown section %q", opt.Name, opt.Section)
+		}
+	}
+}
+
+// TestOptionsUniqueLinstorKeys: catalogue must not have duplicates,
+// otherwise property validation gets ambiguous.
+func TestOptionsUniqueLinstorKeys(t *testing.T) {
+	seen := map[string]struct{}{}
+
+	for _, opt := range drbd.Options() {
+		if _, dup := seen[opt.LinstorKey]; dup {
+			t.Errorf("duplicate LinstorKey %q", opt.LinstorKey)
+		}
+
+		seen[opt.LinstorKey] = struct{}{}
+	}
+}
+
+// TestOptionsCoverWellKnownKeys: a few keys cozystack-style clusters
+// rely on must be present.
+func TestOptionsCoverWellKnownKeys(t *testing.T) {
+	want := []string{
+		"DrbdOptions/Net/protocol",
+		"DrbdOptions/Net/shared-secret",
+		"DrbdOptions/Resource/auto-promote",
+		"DrbdOptions/Resource/quorum",
+		"DrbdOptions/Resource/on-no-quorum",
+	}
+
+	got := map[string]bool{}
+	for _, opt := range drbd.Options() {
+		got[opt.LinstorKey] = true
+	}
+
+	for _, key := range want {
+		if !got[key] {
+			t.Errorf("missing well-known key %q from catalogue", key)
+		}
+	}
+}
