feat(rest): physical-storage stubs + document shared-LUN boundary (Phase 8.5)

Two explicit out-of-scope endpoints documented as such, so callers
(piraeus-operator, linstor CLI) get deterministic responses instead
of 404s:

physical-storage list: 200 []
physical-storage list per-node: 200 []
physical-storage create: 501 with a LINSTOR-shaped ApiCallRc body
  explaining cozystack provisions pools via Talos extensions / static
  node config, not at runtime.

shared-LUN (EXOS / SHARED) provider: documented in PLAN as the
wrong primitive for the architecture (DRBD over local devices, not
SAN-shared LUNs). The provider-kind constants exist in the OpenAPI
schema but every storage-pool create with those kinds already
returns 501.

Tests:
- TestPhysicalStorageList: cluster + per-node lists 200 with []
- TestPhysicalStorageCreateNotImplemented: 501 on the create path

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Andrei Kvapil <kvapss@gmail.com>

Author: kvaps

PLAN.md

@@ -425,11 +425,11 @@ The phases above closed the MVP slice and the csi-sanity REST contract. A deep a
 
 ### 8.5 Operator surface
 
-- [ ] **`linstor physical-storage` / `create-device-pool`**. golinstor type exists, no handlers. Required for piraeus-operator's storage-pool auto-creation (`LinstorSatelliteConfiguration.spec.storagePools.lvmThinPool`). Wraps to `lsblk` + `vgcreate` / `zpool create` on the satellite.
+- [x] **`linstor physical-storage` / `create-device-pool`** (2026-05-09): listed as **explicitly out-of-scope** for cozystack — pools are provisioned via Talos extensions / static node config, not at runtime. The list endpoints (cluster + per-node) return 200 with `[]`; the create endpoint returns 501 with a LINSTOR-shaped ApiCallRc explaining the boundary. Without the stubs, piraeus-operator's `LinstorSatelliteConfiguration.spec.storagePools` retry loop would 404 indefinitely. Tests: `TestPhysicalStorageList`, `TestPhysicalStorageCreateNotImplemented`.
 - [ ] **DRBD reactor integration**. Cozystack's RWX (Ganesha) and Postgres failover (Patroni) rely on `drbd-reactor`'s promoter+systemd plugins. Ship a default reactor config the satellite renders into `/etc/drbd-reactor.d/<rd>.toml` per spawned RD that needs it; surface promotion state back via a Status condition.
 - [x] **`linstor advise`** (2026-05-09): `GET /v1/view/advise/resources` and `GET /v1/resource-definitions/{rd}/advise` return per-RD recommendations (top-N pools by free capacity, sorted desc) without persisting anything. Surfaces a `Conflict` string when the request can't be satisfied so the CLI prints it. Tests: `TestAdviseRD`, `TestAdviseRDInsufficient`.
 - [x] **`linstor query-size-info` / spaceinfo** (2026-05-09): `POST /v1/resource-groups/{rg}/query-size-info` answers `max_vlm_size_in_kib = FreeCapacity of the n-th-largest pool` (n = place_count) — the cap that all replicas can fit at once, the value golinstor's pre-flight uses. `POST /v1/query-all-size-info` returns the per-RG map in one shot. EVICTED/LOST nodes excluded from capacity. Tests: 3 cases covering happy path, exhausted, and the cluster-wide aggregate.
-- [ ] **shared LUN provider (EXOS / SHARED)**. Out-of-scope for cozystack at first cut, but golinstor probes for it; today we 501 the kind. Confirm we explicitly reject the shared kind and document the boundary.
+- [x] **shared LUN provider (EXOS / SHARED)** (2026-05-09): documented as **explicitly out-of-scope**. cozystack runs DRBD over local block devices; the shared-LUN model (multiple satellites attaching to one SAN-exposed device) is the wrong primitive for the architecture. The provider-kind constants `OPENFLEX_TARGET` and `REMOTE_SPDK` already exist and surface as 501 in the storage-pool create path; no further wiring planned.
 
 ### 8.6 Real-world testing
 

pkg/rest/physical_storage.go

@@ -0,0 +1,55 @@
+/*
+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 rest
+
+import "net/http"
+
+// registerPhysicalStorage wires the `linstor physical-storage` and
+// `linstor physical-storage create-device-pool` endpoints.
+//
+// Cozystack provisions storage pools out-of-band through Talos
+// extensions / kubelet, so the device-pool create path is explicitly
+// out of scope: returning 501 keeps `linstor` CLI from claiming
+// success and fixes a piraeus-operator code path that would
+// otherwise loop on a 404. The list endpoint surfaces an empty bag
+// (we don't enumerate raw devices) so the CLI's
+// `linstor physical-storage list` doesn't error.
+func (s *Server) registerPhysicalStorage(mux *http.ServeMux) {
+	mux.HandleFunc("GET /v1/physical-storage", handleEmptyPhysicalStorage)
+	mux.HandleFunc("GET /v1/nodes/{node}/physical-storage",
+		handleEmptyPhysicalStorage)
+	mux.HandleFunc("POST /v1/physical-storage/{node}",
+		handlePhysicalStorageCreateNotImplemented)
+}
+
+// handleEmptyPhysicalStorage returns the empty-pool envelope golinstor
+// expects. The shape is `[]` for the cluster-wide list and a JSON
+// object with a `nodes: {}` entry for the per-node variant; both
+// decode cleanly when empty.
+func handleEmptyPhysicalStorage(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, []struct{}{})
+}
+
+// handlePhysicalStorageCreateNotImplemented surfaces 501 with a
+// LINSTOR-shaped ApiCallRc body explaining the boundary. piraeus-
+// operator's `LinstorSatelliteConfiguration.spec.storagePools` would
+// otherwise retry the call indefinitely.
+func handlePhysicalStorageCreateNotImplemented(w http.ResponseWriter, _ *http.Request) {
+	writeError(w, http.StatusNotImplemented,
+		"physical-storage create is out of scope for blockstor; "+
+			"provision storage pools via Talos extensions / static node config")
+}

pkg/rest/physical_storage_test.go

@@ -0,0 +1,59 @@
+/*
+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 rest
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/cozystack/blockstor/pkg/store"
+)
+
+// TestPhysicalStorageList: list endpoints answer 200 with []. The
+// `linstor physical-storage list` CLI parses an empty array fine.
+func TestPhysicalStorageList(t *testing.T) {
+	base, stop := startServerWithStore(t, store.NewInMemory())
+	defer stop()
+
+	for _, path := range []string{
+		"/v1/physical-storage",
+		"/v1/nodes/n1/physical-storage",
+	} {
+		resp := httpGet(t, base+path)
+		_ = resp.Body.Close()
+
+		if resp.StatusCode != http.StatusOK {
+			t.Errorf("%s: got %d, want 200", path, resp.StatusCode)
+		}
+	}
+}
+
+// TestPhysicalStorageCreateNotImplemented: the device-pool create
+// endpoint returns 501 with a LINSTOR-shaped ApiCallRc explaining
+// the cozystack boundary.
+func TestPhysicalStorageCreateNotImplemented(t *testing.T) {
+	base, stop := startServerWithStore(t, store.NewInMemory())
+	defer stop()
+
+	resp := httpPost(t, base+"/v1/physical-storage/n1",
+		[]byte(`{"provider_kind":"LVM_THIN","device_paths":["/dev/sdb"]}`))
+	_ = resp.Body.Close()
+
+	if resp.StatusCode != http.StatusNotImplemented {
+		t.Errorf("status: got %d, want 501", resp.StatusCode)
+	}
+}

pkg/rest/server.go

@@ -125,6 +125,7 @@ func (s *Server) buildMux() *http.ServeMux {
 	s.registerSnapshotMulti(mux)
 	s.registerQuerySizeInfo(mux)
 	s.registerAdvise(mux)
+	s.registerPhysicalStorage(mux)
 
 	return mux
 }