docs: clarify AvailableNodeIndexes are not contiguous 0..Size-1

Node indexes are allocated monotonically by the operator and never re-compacted, so
after repeated scale-up-then-scale-down rounds (on-demand-replication-restart, version
upgrades) the indexes - and per-index pod names and PVCs - can grow beyond Spec.Size.
Document this as expected behavior and that indexes are reserved-not-reused to avoid
colliding with not-yet-reclaimed PVCs/PVs and lingering consensus peers. Consumers must
treat the slice as the source of truth and not assume contiguous ordinals.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: qdrant-cloud-bot

api/v1/qdrantcluster_types.go

@@ -994,6 +994,14 @@ type QdrantClusterStatus struct {
 	AvailableNodes int `json:"availableNodes,omitempty"`
 	// AvailableNodeIndexes specifies the indexes of the individual nodes in the cluster
 	// The number of indexes should be equal with the AvailableNodes field.
+	// NOTE: these indexes are NOT guaranteed to be the contiguous range 0..Size-1.
+	// New indexes are allocated monotonically (always above the current maximum) and are
+	// never re-compacted, so after repeated scale-up-then-scale-down rounds (e.g.
+	// on-demand-replication-restart or version upgrades) the indexes - and the per-index
+	// pod names and PVCs - can grow well beyond Spec.Size. This is expected behavior:
+	// indexes are reserved-not-reused to avoid colliding with not-yet-reclaimed PVCs/PVs
+	// and lingering consensus peers from a prior occupant of the same index. Consumers
+	// must treat this slice as the source of truth and must not assume contiguous ordinals.
 	// +optional
 	AvailableNodeIndexes []int `json:"availableNodeIndexes,omitempty"`
 	// DeleteInProgessNodeIndexes specifies the indexes of the nodes in the cluster which are in progress of deleting and required to be deleted.

charts/qdrant-kubernetes-api/templates/region-crds/qdrant.io_qdrantclusters.yaml

@@ -3455,6 +3455,14 @@ spec:
                 description: |-
                   AvailableNodeIndexes specifies the indexes of the individual nodes in the cluster
                   The number of indexes should be equal with the AvailableNodes field.
+                  NOTE: these indexes are NOT guaranteed to be the contiguous range 0..Size-1.
+                  New indexes are allocated monotonically (always above the current maximum) and are
+                  never re-compacted, so after repeated scale-up-then-scale-down rounds (e.g.
+                  on-demand-replication-restart or version upgrades) the indexes - and the per-index
+                  pod names and PVCs - can grow well beyond Spec.Size. This is expected behavior:
+                  indexes are reserved-not-reused to avoid colliding with not-yet-reclaimed PVCs/PVs
+                  and lingering consensus peers from a prior occupant of the same index. Consumers
+                  must treat this slice as the source of truth and must not assume contiguous ordinals.
                 items:
                   type: integer
                 type: array

crds/qdrant.io_qdrantclusters.yaml

@@ -3454,6 +3454,14 @@ spec:
                 description: |-
                   AvailableNodeIndexes specifies the indexes of the individual nodes in the cluster
                   The number of indexes should be equal with the AvailableNodes field.
+                  NOTE: these indexes are NOT guaranteed to be the contiguous range 0..Size-1.
+                  New indexes are allocated monotonically (always above the current maximum) and are
+                  never re-compacted, so after repeated scale-up-then-scale-down rounds (e.g.
+                  on-demand-replication-restart or version upgrades) the indexes - and the per-index
+                  pod names and PVCs - can grow well beyond Spec.Size. This is expected behavior:
+                  indexes are reserved-not-reused to avoid colliding with not-yet-reclaimed PVCs/PVs
+                  and lingering consensus peers from a prior occupant of the same index. Consumers
+                  must treat this slice as the source of truth and must not assume contiguous ordinals.
                 items:
                   type: integer
                 type: array