feat(storage): shared-LUN architectural hooks (Phase 8.5)

Add SharedSpaceID to StoragePool CRD spec and REST shape.

Pools sharing a backing LUN (e.g. EXOS / NetApp / Ceph-RBD-as-shared-disk
slices attached to multiple satellites) now contribute their free
capacity once to cluster totals instead of summing, and the autoplacer
treats them as anti-affine so a 2-replica RD never lands on pools that
physically share the same disk.

The SAN-shared-LUN model isn't needed today, but landing the hooks now
keeps the door open without retrofitting the placer/query-size-info
paths later. Empty SharedSpaceID = local pool (default), so existing
behaviour is unchanged.

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

Author: kvaps

api/v1alpha1/storagepool_types.go

@@ -40,6 +40,16 @@ type StoragePoolSpec struct {
 	// +kubebuilder:validation:Enum=LVM;LVM_THIN;ZFS;ZFS_THIN;FILE;FILE_THIN;DISKLESS
 	ProviderKind string `json:"providerKind"`
 
+	// sharedSpaceId groups pools that physically share the same backing
+	// LUN (e.g. an EXOS / NetApp / Ceph-RBD-as-shared-disk slice attached
+	// to multiple satellites). Pools in the same group contribute their
+	// free capacity once to cluster totals instead of summing, and the
+	// autoplacer treats them as anti-affine for replica placement so a
+	// 2-replica RD never lands twice on the same physical LUN.
+	// Empty string = local pool (default).
+	// +optional
+	SharedSpaceID string `json:"sharedSpaceId,omitempty"`
+
 	// props is the LINSTOR property map for this pool.
 	// +optional
 	Props map[string]string `json:"props,omitempty"`

config/crd/bases/blockstor.io.blockstor.io_resources.yaml

@@ -124,8 +124,10 @@ spec:
                 x-kubernetes-list-type: map
               drbdMinor:
                 description: |-
-                  drbdMinor is the local /dev/drbd<N> minor number. Same scoping
-                  rule as drbdPort.
+                  drbdMinor is the local /dev/drbd<N> minor number on the
+                  hosting node. Like drbdPort, allocated per-replica from the
+                  node's minor-range — minors are local device numbers, so two
+                  replicas on different nodes can have unrelated minors.
                 format: int32
                 type: integer
               drbdNodeId:
@@ -140,9 +142,11 @@ spec:
                 type: integer
               drbdPort:
                 description: |-
-                  drbdPort is the TCP port the controller allocated for this RD's
-                  replication mesh. All replicas of the same RD share the port;
-                  the controller stamps the same value on every sibling Resource.
+                  drbdPort is the TCP port this replica listens on. Allocated
+                  from the hosting node's TCP-port range — different replicas
+                  of the same RD can use different ports because each lives on
+                  a different node and the port is local to that node. Matches
+                  upstream LINSTOR's per-resource (not per-RD) port model.
                   nil means not yet allocated.
                 format: int32
                 type: integer

config/crd/bases/blockstor.io.blockstor.io_storagepools.yaml

@@ -65,6 +65,16 @@ spec:
                 - FILE_THIN
                 - DISKLESS
                 type: string
+              sharedSpaceId:
+                description: |-
+                  sharedSpaceId groups pools that physically share the same backing
+                  LUN (e.g. an EXOS / NetApp / Ceph-RBD-as-shared-disk slice attached
+                  to multiple satellites). Pools in the same group contribute their
+                  free capacity once to cluster totals instead of summing, and the
+                  autoplacer treats them as anti-affine for replica placement so a
+                  2-replica RD never lands twice on the same physical LUN.
+                  Empty string = local pool (default).
+                type: string
             required:
             - nodeName
             - providerKind

pkg/api/v1/storage_pool.go

@@ -27,10 +27,16 @@ type StoragePool struct {
 	FreeCapacity     int64             `json:"free_capacity,omitempty"`
 	TotalCapacity    int64             `json:"total_capacity,omitempty"`
 	FreeSpaceMgrName string            `json:"free_space_mgr_name,omitempty"`
-	Reports          []APICallRc       `json:"reports,omitempty"`
-	SupportsSnapshot bool              `json:"supports_snapshots,omitempty"`
-	ExternalLocking  bool              `json:"external_locking,omitempty"`
-	UUID             string            `json:"uuid,omitempty"`
+	// SharedSpaceID groups pools that physically share a backing LUN.
+	// Empty = local pool (default). Pools sharing the same value
+	// contribute one free-capacity figure to cluster totals (instead
+	// of summing) and are treated as anti-affine by the autoplacer.
+	// Wire field name matches upstream LINSTOR (`shared_space`).
+	SharedSpaceID    string      `json:"shared_space,omitempty"`
+	Reports          []APICallRc `json:"reports,omitempty"`
+	SupportsSnapshot bool        `json:"supports_snapshots,omitempty"`
+	ExternalLocking  bool        `json:"external_locking,omitempty"`
+	UUID             string      `json:"uuid,omitempty"`
 }
 
 // APICallRc is the upstream `ApiCallRc` envelope. We define a minimal subset

pkg/placer/placer.go

@@ -80,7 +80,12 @@ func (p *Placer) Place(ctx context.Context, rdName string, filter *apiv1.AutoSel
 		return 0, 0, err
 	}
 
-	state := newState(filter, existing, nodes)
+	allPools, err := p.store.StoragePools().List(ctx)
+	if err != nil {
+		return 0, 0, errors.Wrap(err, "list storage pools")
+	}
+
+	state := newState(filter, existing, nodes, allPools)
 
 	if state.sameTuple == nil && len(filter.ReplicasOnSame) > 0 {
 		candidates, state.sameTuple = pickSameGroup(candidates, nodes,
@@ -170,24 +175,45 @@ func (p *Placer) placeDisklessOnRemaining(ctx context.Context, rdName string, st
 // state holds the per-call lookup tables. Pulled out of Placer so a
 // concurrent Placer call doesn't share the mutable bookkeeping.
 type state struct {
-	nodes     map[string]map[string]string
-	taken     map[string]struct{}
-	sameTuple map[string]string
-	diffSeen  map[string]struct{}
-	filter    *apiv1.AutoSelectFilter
+	nodes      map[string]map[string]string
+	taken      map[string]struct{}
+	sameTuple  map[string]string
+	diffSeen   map[string]struct{}
+	sharedSeen map[string]struct{} // sharedSpaceIDs already used by an existing replica
+	pools      map[string]apiv1.StoragePool
+	filter     *apiv1.AutoSelectFilter
 }
 
-func newState(filter *apiv1.AutoSelectFilter, existing []apiv1.Resource, nodes map[string]map[string]string) *state {
+func newState(filter *apiv1.AutoSelectFilter, existing []apiv1.Resource, nodes map[string]map[string]string, pools []apiv1.StoragePool) *state {
 	s := &state{
-		nodes:     nodes,
-		taken:     make(map[string]struct{}, len(existing)),
-		sameTuple: topologyTuple(existing, nodes, filter.ReplicasOnSame),
-		diffSeen:  topologySeen(existing, nodes, filter.ReplicasOnDifferent),
-		filter:    filter,
+		nodes:      nodes,
+		taken:      make(map[string]struct{}, len(existing)),
+		sameTuple:  topologyTuple(existing, nodes, filter.ReplicasOnSame),
+		diffSeen:   topologySeen(existing, nodes, filter.ReplicasOnDifferent),
+		sharedSeen: make(map[string]struct{}),
+		pools:      poolsByKey(pools),
+		filter:     filter,
 	}
 
 	for i := range existing {
 		s.taken[existing[i].NodeName] = struct{}{}
+
+		// Pre-seed shared-space anti-affinity: if an existing replica
+		// already lives on a shared-LUN pool, no new replica may land
+		// on a pool sharing that LUN identifier.
+		stor := existing[i].Props["StorPoolName"]
+		if stor == "" {
+			continue
+		}
+
+		pool, ok := s.pools[poolKey(existing[i].NodeName, stor)]
+		if !ok {
+			continue
+		}
+
+		if pool.SharedSpaceID != "" {
+			s.sharedSeen[pool.SharedSpaceID] = struct{}{}
+		}
 	}
 
 	return s
@@ -208,6 +234,16 @@ func (s *state) tryPlace(ctx context.Context, st store.Store, rdName string, poo
 		return false, nil
 	}
 
+	// Shared-LUN anti-affinity: pools sharing a backing LUN identifier
+	// cannot host two replicas of the same RD — at the physical layer
+	// they are the same disk, so a 2-replica placement onto the same
+	// SharedSpaceID would offer zero redundancy.
+	if pool.SharedSpaceID != "" {
+		if _, dup := s.sharedSeen[pool.SharedSpaceID]; dup {
+			return false, nil
+		}
+	}
+
 	res := apiv1.Resource{
 		Name:     rdName,
 		NodeName: pool.NodeName,
@@ -229,9 +265,28 @@ func (s *state) tryPlace(ctx context.Context, st store.Store, rdName string, poo
 		s.diffSeen[k+"="+nodeProps[auxKey(k)]] = struct{}{}
 	}
 
+	if pool.SharedSpaceID != "" {
+		s.sharedSeen[pool.SharedSpaceID] = struct{}{}
+	}
+
 	return true, nil
 }
 
+// poolKey is the composite (node, pool) lookup key used to find a
+// StoragePool from a Resource's StorPoolName + NodeName pair.
+func poolKey(node, pool string) string {
+	return node + "\x1f" + pool
+}
+
+func poolsByKey(pools []apiv1.StoragePool) map[string]apiv1.StoragePool {
+	out := make(map[string]apiv1.StoragePool, len(pools))
+	for i := range pools {
+		out[poolKey(pools[i].NodeName, pools[i].StoragePoolName)] = pools[i]
+	}
+
+	return out
+}
+
 func (p *Placer) candidatePools(ctx context.Context, filter *apiv1.AutoSelectFilter) ([]apiv1.StoragePool, error) {
 	all, err := p.store.StoragePools().List(ctx)
 	if err != nil {

pkg/rest/advise.go

@@ -161,6 +161,12 @@ func pickAdvicePools(pools []apiv1.StoragePool, filter *apiv1.AutoSelectFilter,
 		}
 	}
 
+	// Shared-LUN anti-affinity: the placer would refuse to put two
+	// replicas on pools sharing a backing LUN, so the advice surface
+	// must mirror that — otherwise we'd recommend a layout the
+	// resource-create would then reject.
+	candidates = dedupShared(candidates)
+
 	if want > len(candidates) {
 		want = len(candidates)
 	}

pkg/rest/autoplace_test.go

@@ -608,6 +608,120 @@ func TestAutoplaceSkipsEvictedNodes(t *testing.T) {
 	}
 }
 
+// TestAutoplaceSharedLUNAntiAffinity: two pools share the same backing
+// LUN (SharedSpaceID="exos-lun-42"); a 2-replica autoplace must never
+// land both replicas on those pools, even though they live on
+// distinct nodes. Real-world rationale: at the physical layer the
+// LUN is the same disk, so both replicas would sit on the same
+// failure domain — defeating the redundancy a 2-replica RD promises.
+func TestAutoplaceSharedLUNAntiAffinity(t *testing.T) {
+	st := store.NewInMemory()
+	ctx := t.Context()
+
+	if err := st.ResourceDefinitions().Create(ctx, &apiv1.ResourceDefinition{Name: "pvc-shared"}); err != nil {
+		t.Fatalf("seed RD: %v", err)
+	}
+
+	for _, n := range []string{"n1", "n2", "n3"} {
+		if err := st.Nodes().Create(ctx, &apiv1.Node{Name: n, Type: apiv1.NodeTypeSatellite}); err != nil {
+			t.Fatalf("seed node %s: %v", n, err)
+		}
+	}
+
+	// n1 + n2 each see the same EXOS LUN; n3 has its own local pool.
+	pools := []apiv1.StoragePool{
+		{StoragePoolName: "pool", NodeName: "n1", ProviderKind: apiv1.StoragePoolKindLVMThin, SharedSpaceID: "exos-lun-42", FreeCapacity: 9000},
+		{StoragePoolName: "pool", NodeName: "n2", ProviderKind: apiv1.StoragePoolKindLVMThin, SharedSpaceID: "exos-lun-42", FreeCapacity: 9000},
+		{StoragePoolName: "pool", NodeName: "n3", ProviderKind: apiv1.StoragePoolKindLVMThin, FreeCapacity: 5000},
+	}
+	for i := range pools {
+		if err := st.StoragePools().Create(ctx, &pools[i]); err != nil {
+			t.Fatalf("seed pool: %v", err)
+		}
+	}
+
+	base, stop := startServerWithStore(t, st)
+	defer stop()
+
+	body, _ := json.Marshal(apiv1.AutoPlaceRequest{
+		SelectFilter: apiv1.AutoSelectFilter{PlaceCount: 2, StoragePool: "pool"},
+	})
+
+	resp := httpPost(t, base+"/v1/resource-definitions/pvc-shared/autoplace", body)
+	_ = resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status: got %d, want 200", resp.StatusCode)
+	}
+
+	got, err := st.Resources().ListByDefinition(ctx, "pvc-shared")
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+
+	if len(got) != 2 {
+		t.Fatalf("placed: got %d, want 2", len(got))
+	}
+
+	// Exactly one of {n1, n2} can be picked; n3 (local) MUST be the other.
+	nodes := []string{got[0].NodeName, got[1].NodeName}
+	if !slices.Contains(nodes, "n3") {
+		t.Errorf("expected one replica on n3 (the non-shared node); got %v", nodes)
+	}
+
+	sharedHit := 0
+	for _, n := range nodes {
+		if n == "n1" || n == "n2" {
+			sharedHit++
+		}
+	}
+
+	if sharedHit > 1 {
+		t.Errorf("both replicas on the same shared-LUN pool group: %v", nodes)
+	}
+}
+
+// TestAutoplaceSharedLUNExhausted: 2-replica RD against two pools
+// sharing one LUN — only one replica fits, the other has no
+// candidate and the request must 409. Pins the conflict path.
+func TestAutoplaceSharedLUNExhausted(t *testing.T) {
+	st := store.NewInMemory()
+	ctx := t.Context()
+
+	if err := st.ResourceDefinitions().Create(ctx, &apiv1.ResourceDefinition{Name: "pvc-shared-2"}); err != nil {
+		t.Fatalf("seed RD: %v", err)
+	}
+
+	for _, n := range []string{"n1", "n2"} {
+		if err := st.Nodes().Create(ctx, &apiv1.Node{Name: n, Type: apiv1.NodeTypeSatellite}); err != nil {
+			t.Fatalf("seed node %s: %v", n, err)
+		}
+
+		if err := st.StoragePools().Create(ctx, &apiv1.StoragePool{
+			StoragePoolName: "pool",
+			NodeName:        n,
+			ProviderKind:    apiv1.StoragePoolKindLVMThin,
+			SharedSpaceID:   "exos-lun-42",
+		}); err != nil {
+			t.Fatalf("seed pool %s: %v", n, err)
+		}
+	}
+
+	base, stop := startServerWithStore(t, st)
+	defer stop()
+
+	body, _ := json.Marshal(apiv1.AutoPlaceRequest{
+		SelectFilter: apiv1.AutoSelectFilter{PlaceCount: 2, StoragePool: "pool"},
+	})
+
+	resp := httpPost(t, base+"/v1/resource-definitions/pvc-shared-2/autoplace", body)
+	_ = resp.Body.Close()
+
+	if resp.StatusCode != http.StatusConflict {
+		t.Errorf("status: got %d, want 409 (only one shared-LUN slot fits)", resp.StatusCode)
+	}
+}
+
 // TestResourceListAndGet: GET /v1/resource-definitions/{rd}/resources
 // returns all replicas wrapped as ResourceWithVolumes; the per-node
 // GET returns one entry or 404 when missing. linstor-csi's reconciler

pkg/rest/query_size_info.go

@@ -106,6 +106,12 @@ func (s *Server) computeSizeInfo(ctx context.Context, filter *apiv1.AutoSelectFi
 	)
 
 	candidates := make([]apiv1.StoragePool, 0, len(pools))
+	// sharedSeen collapses pools that share a backing LUN: a SAN /
+	// EXOS / Ceph-RBD-as-shared-disk slice attached to multiple
+	// satellites must only contribute its capacity once to cluster
+	// totals. Without this, two pools each "seeing" 100 GiB of the
+	// same LUN would report 200 GiB free.
+	sharedSeen := map[string]struct{}{}
 
 	for i := range pools {
 		pool := pools[i]
@@ -122,11 +128,20 @@ func (s *Server) computeSizeInfo(ctx context.Context, filter *apiv1.AutoSelectFi
 		}
 
 		candidates = append(candidates, pool)
+
+		if pool.SharedSpaceID != "" {
+			if _, dup := sharedSeen[pool.SharedSpaceID]; dup {
+				continue
+			}
+
+			sharedSeen[pool.SharedSpaceID] = struct{}{}
+		}
+
 		totalCapacity += pool.TotalCapacity
 		availableSum += pool.FreeCapacity
 	}
 
-	maxVolKib := worstFreeOfTopN(candidates, replicaCount(filter))
+	maxVolKib := worstFreeOfTopN(dedupShared(candidates), replicaCount(filter))
 
 	return querySizeInfoResponse{
 		SpaceInfo: querySizeInfoSpaceInfo{
@@ -137,6 +152,30 @@ func (s *Server) computeSizeInfo(ctx context.Context, filter *apiv1.AutoSelectFi
 	}, nil
 }
 
+// dedupShared collapses pools that share a backing LUN to a single
+// representative. The placer's anti-affinity already prevents 2 of N
+// replicas from landing on the same SharedSpaceID; the n-th-largest
+// computation must reflect that, otherwise it would overcount the
+// shared LUN as N independent pools.
+func dedupShared(pools []apiv1.StoragePool) []apiv1.StoragePool {
+	out := make([]apiv1.StoragePool, 0, len(pools))
+	seen := map[string]struct{}{}
+
+	for i := range pools {
+		if pools[i].SharedSpaceID != "" {
+			if _, dup := seen[pools[i].SharedSpaceID]; dup {
+				continue
+			}
+
+			seen[pools[i].SharedSpaceID] = struct{}{}
+		}
+
+		out = append(out, pools[i])
+	}
+
+	return out
+}
+
 // worstFreeOfTopN sorts pools by FreeCapacity desc and returns the
 // FreeCapacity of the n-th — i.e. the cap that all `n` replicas can
 // actually fit. Fewer than n candidates → 0 (the request can't be