Developer guide on Blockstor

Building

Mon, 01 Jan 0001 00:00:00 +0000

Binaries

Blockstor is a Go module, github.com/cozystack/blockstor. make build regenerates the manifests and deep-copy code, runs go fmt and go vet, and builds the controller, the satellite, the CLI and the migration tool into bin/. The API server builds the usual Go way:

make build
go build -o bin/apiserver ./cmd/apiserver

Binary	Source	What it is
`controller`	`cmd/controller`	controller-runtime manager with the controller-side reconcilers.
`apiserver`	`cmd/apiserver`	the stateless LINSTOR-compatible REST front end.
`satellite`	`cmd/satellite`	the per-node manager that drives DRBD, LUKS and storage.
`blockstor`	`cmd/blockstor`	the operator CLI.
`linstor-migrate`	`cmd/linstor-migrate`	the LINSTOR database converter.

Other generators: make manifests regenerates the CRDs and RBAC from the kubebuilder markers in api/v1alpha1, and make generate regenerates the deep-copy code.

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Each tier answers a different question, and a change is expected to come with tests at the lowest tier that can catch the bug.

Tier	What it covers	Where
L1 unit	Logic, run on every commit	`*_test.go` next to the code
L2 contract, golden	Recorded `golinstor` responses replayed against the server, byte diff	`tests/contract/`
L3 contract, oracle	The same requests to a real LINSTOR and to blockstor, JSON diff	`tests/contract/`
Integration	Controllers and REST against a real Kubernetes API server (envtest), satellites faked	`tests/integration/`
L4 integration on DRBD	`make smoke` on the stand	`tests/smoke*.sh`
L5 e2e	csi-sanity and piraeus-operator e2e on the stand	`tests/e2e/`
L6 operator CLI	The real CLI, through REST and the satellite, down to the DRBD kernel state	`tests/e2e/cli-matrix/`
L7 replay	Operator workflows replayed, and the CLI parity diff against upstream	`tests/operator-harness/`

Unit tests and lint

go test ./...
make lint

Tests that need envtest skip themselves when KUBEBUILDER_ASSETS is not set. make test downloads the envtest binaries and runs the suite with them. make lint must be clean before a push.

Repository layout

Mon, 01 Jan 0001 00:00:00 +0000

api/v1alpha1/ CRD types and kubebuilder markers
cmd/ controller, apiserver, satellite, blockstor CLI, linstor-migrate
internal/controller/ controller-side reconcilers
internal/cli/ the blockstor CLI
pkg/ REST, stores, satellite, storage, DRBD, LUKS, placer, dispatcher
config/ generated CRDs, RBAC and kustomize bases
stand/ the Talos and QEMU dev stand and the reference manifests
tests/ contract, integration, e2e, cli-matrix and replay suites
docs/ design notes, parity deltas and audit history
site/ this website

Path	What lives there
`api/v1alpha1/`	The CRD types. `make manifests` turns their markers into `config/crd/bases/`.
`pkg/api/v1/`	The REST wire types, shaped like upstream LINSTOR’s, and the layer-stack resolver.
`pkg/rest/`	The LINSTOR-compatible REST handlers.
`pkg/store/`, `pkg/store/k8s/`	The in-memory and CRD-backed stores behind one `store.Store` interface, and the translation between wire and CRD shapes.
`internal/controller/`	Controller-side reconcilers: resources, definitions, groups, pools, snapshots, nodes, plus tiebreakers, auto-diskful, eviction, rebalancing and migration.
`pkg/satellite/controllers/`	Satellite-side reconcilers for resources, pools, snapshots and physical devices, and the `events2` observer.
`pkg/satellite/`	The DRBD, LUKS and storage layer reconciler and snapshot shipping.
`pkg/storage/`	Storage providers: LVM, LVM-thin, ZFS, ZFS-thin, loopfile and file.
`pkg/drbd/`	`drbdadm` and `drbdsetup` wrappers, the `.res` renderer, the `events2` parser and the options resolver.
`pkg/luks/`	The `cryptsetup` wrapper.
`pkg/placer/`	The autoplacer: capacity-weighted, anti-affinity aware.
`pkg/dispatcher/`	Translates CRDs into the desired state a satellite applies: layers, options, passphrases.
`internal/cli/`	The `blockstor` CLI. Its design is in `docs/cli-design.md`.
`cmd/linstor-migrate/`	The LINSTOR database converter.

Internals

Mon, 01 Jan 0001 00:00:00 +0000

This page is about the invariants whose violation would quietly corrupt cluster state. For the user-level picture, see Architecture. For a tour of the code, follow the call graph from cmd/controller/main.go and cmd/satellite/main.go.

Spec and Status

Every blockstor CRD has two halves:

Spec is desired state. Users, REST handlers and the controller’s placement write it. The satellite writes Spec in two places: Resource.Spec.Flags (and ToggleDiskCancel) while it carries out a toggle-disk, and the discovered volume groups and ZFS pools in Node.Spec.Props.
Status is observed state. The satellite writes what it reads from the kernel (drbdsetup events2, drbdadm status, lvs), and the controller’s allocators write values derived from Spec. The REST API writes Status in one place: the resource activate endpoint with ?reallocate-port=true clears Resource.Status.DRBDPort through a Status patch. The allocator only fills an empty Spec.DRBDPort, and the controller copies the spec value back into Status, so the port does not change.

A whole-object Update is unsafe whenever both halves have different writers: a Spec write in flight would overwrite a concurrent Status write, and the other way round. Status goes through the Status subresource. Fields with more than one writer, such as Resource.Status.DRBDPort from the controller next to DiskState and CurrentGi from the satellite, go through Server-Side Apply with separate field managers, blockstor-controller and blockstor-satellite, so each side owns only its own fields.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Licensing: Apache 2.0, clean room

Blockstor is Apache 2.0. Do not copy structure or code from GPL sources, in particular linstor-server and drbd-utils. You may read them to understand behaviour, never to reproduce how they are written.

Hard rules:

No GPL-licensed spec files in the tree. LINSTOR’s rest_v1_openapi.yaml declares GPLv3, and code generated from it is a derivative work.
No code generated from a GPL source by any tool.
No Go dependency under GPL, AGPL, LGPL or SSPL. CI enforces this through license-check.yml, which runs go-licenses check --disallowed_types=forbidden,restricted over ./cmd/.... That is a denylist: it fails on licenses go-licenses classifies as forbidden or restricted, and lets everything else through, so check a new dependency’s license yourself.
Every Go source file carries an SPDX-License-Identifier: Apache-2.0 header.

Apache-2.0 projects that are safe to study and depend on: golinstor, the authoritative description of the REST wire shape; piraeus-operator; linstor-csi; drbd-reactor; and the public DRBD 9 documentation and man pages.