Piraeus Operator: running LINSTOR storage clusters inside Kubernetes

What the operator actually manages

The Piraeus Operator manages LINSTOR clusters in Kubernetes, and the sentence that defines its scope is that all components of the LINSTOR software stack can be managed by the operator. The list of those components is short and specific. DRBD is there, the block replication layer the whole thing is built on. LINSTOR itself is there, the storage orchestrator. The LINSTOR CSI driver is there, so pods can consume the volumes through the normal Kubernetes storage interface. And the LINSTOR High-Availability Controller is there, which is the piece that keeps replicated volumes in the right place when a node fails. That last component is the reason the operator exists as a separate project rather than being folded into the CSI driver, because the controller and the driver have different lifecycles.

Deploying it, and waiting for it to become ready

Deploying v2 from the repository is a single server-side apply of the released manifest.

$ kubectl apply --server-side -f "https://github.com/piraeusdatastore/piraeus-operator/releases/latest/download/manifest.yaml"
# Verify the operator is running:
$ kubectl wait pod --for=condition=Ready -n piraeus-datastore -l app.kubernetes.io/component=piraeus-operator
pod/piraeus-operator-controller-manager-dd898f48c-bhbtv condition met

The wait command is the part people skip, and it is there because the operator is a controller that has to be running before the resources it reconciles will do anything. The namespace in the example, piraeus-datastore, and the label selector are both part of the shipped manifest, so the command works against a default deployment without editing.

A basic cluster is one custom resource

Once the operator is up, a basic storage cluster is created by applying a LinstorCluster resource, and the empty spec is enough to start.

$ kubectl apply -f - <<EOF
apiVersion: piraeus.io/v1
kind: LinstorCluster
metadata:
  name: linstorcluster
spec: {}
EOF

The API group is piraeus.io and the version is v1, and the spec being empty is the interesting part. Everything the operator does for the cluster comes from the operator's own defaults, so the first resource is a starting point rather than a specification. The documentation set is arranged to match the depth you need, with tutorials to get started, how-to guides to configure a specific aspect or achieve a specific task, an API reference for the LINSTOR related resources you can modify or observe, explanation documents for how Piraeus Datastore works and why it works that way, and a separate upgrades section for the upgrade procedure.

The v1 line is not abandoned, but it is a dead end

The previous version of the operator is still available on the master branch, and the guidance for anyone currently on Piraeus Operator v1 is to continue using it. The project says v1 will be maintained, receiving updates to fix issues or to support new software versions, until a stable upgrade path to v2 is available. That is a deliberate and reasonably careful position. A v1 to v2 upgrade for a storage operator touches how volumes are provisioned, and the default branch of this repository is v2 while the old operator sits on master, so the two live in different places. If you are on v1 today, the practical consequence is that you keep patching v1 and you do not plan an upgrade until the project says the path is stable, which is a different position from the one where the v2 line is the only line.

The Go dependency list, and what it tells you

The module manifest is a good map of the architecture. The LINSTOR client is golinstor at version 0.65.2, which is how the operator talks to the LINSTOR it manages. The storage pieces are first-party forks in the same organisation, with linstor-csi, piraeus-ha-controller and linstor-affinity-controller, which is the key point about the dependency set. Rather than reaching for upstream releases, the operator builds against versions maintained alongside it, so the CSI driver and the controller move in step with the operator instead of drifting. The Kubernetes side uses controller-runtime and cluster-api, with cert-manager as a dependency, which tells you the operator issues its own certificates for the components it installs. The k8s.io libraries are at v0.37.1, and the go directive is 1.26.1.

How the image is built, and why the base image is distroless

The Dockerfile is a two stage build on the golang builder image, with the module manifests copied first so that the dependency download layer is cached and a source change does not invalidate it. Two binaries are produced, the manager and a gencert helper, and both are built with the version stamped in through linker flags. The runtime stage is gcr.io/distroless/static:nonroot, with the comment that it is used as a minimal base image to package the manager binary, and the process runs as the nonroot user with an id of 65532. There is no shell in the final image and no package manager, which is the point of distroless, and it also means the container image cannot be debugged by shelling into it.

Where this is the wrong choice

Two situations make it a poor fit. The first is a cluster where the storage layer is already managed by something else, whether that is a different operator or a hand-rolled DRBD setup, because the Piraeus Operator's value is the bundle, and installing it alongside another storage controller means two things reconciling the same volumes. The second is a team that only needs simple block storage with replication and no interest in the LINSTOR layer, where a plain DRBD setup or a managed cloud disk would be less machinery. The project's own documentation makes the same point in a different way, with a separate explanation section about how Piraeus Datastore works and why it works the way it does, which is a signal that the design has opinions you should read before deploying rather than after.

Editorial conclusion

Piraeus Operator fits a Kubernetes platform team that wants replicated block storage managed by the same declarative workflow as the rest of the cluster, because the LINSTOR stack, including the CSI driver, is installed and reconciled by the operator rather than by hand. It does not fit a team that has already standardised on a different operator or on plain DRBD, because the value here is the bundle rather than any one component, and it does not fit anyone on the v1 line who is not ready to plan the upgrade, since the project asks v1 users to stay on v1 until a stable upgrade path to v2 exists. Before you deploy, read the upgrade documentation for your version, check that your cluster meets the Kubernetes 1.30 requirement shown in the badge, and read the explanation documents rather than only the tutorials, because the design choices behind the storage layout are what you will be living with.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. piraeusdatastore/piraeus-operator on GitHub
3. Project website
4. README
5. Releases