Add minor-update target-stage gate annotation

Introduce a core.openstack.org/update-target-stage annotation on
OpenStackVersion. When set, the update controller completes all
stages up to and including the named stage, marks the next stage as
blocked (FalseCondition/RequestedReason), and pauses reconciliation.

Removing the annotation or advancing it to a later stage resumes the
update.

Includes stage-name constants, the gated-message format string,
controller logic for all seven stages, functional tests for block/resume/
advance scenarios, webhooks and updated operator documentation.

AI-assisted: Cursor (Claude Sonnet 4.6 by Anthropic)

Author: ciecierski

api/core/v1beta1/conditions.go

@@ -605,4 +605,7 @@ const (
 
 	// OpenStackVersionMinorUpdateAvailableMessage
 	OpenStackVersionMinorUpdateAvailableMessage = "update available"
+
+	// OpenStackVersionMinorUpdateReadyGatedMessage - format string; arg is the target stage name
+	OpenStackVersionMinorUpdateReadyGatedMessage = "Minor update progression stopped after stage: %s. Set annotation to any stage after %s to resume OpenStack update or remove the annotation to run to completion."
 )

api/core/v1beta1/openstackversion_types.go

@@ -34,8 +34,128 @@ const (
 	MinorUpdateControlPlane string = "Minor Update Controlplane In Progress"
 	// MinorUpdateComplete -
 	MinorUpdateComplete string = "Complete"
+
+	// MinorUpdateTargetStageAnnotation - specifies the update stage after which the minor update
+	// should pause. All stages up to and including the named stage will be completed; subsequent
+	// stages will be blocked until the annotation is removed or updated to a later stage.
+	// During an update, the webhook rejects moving this annotation to an earlier stage, and
+	// rejects adding it behind stages already completed when it was absent at update start.
+	// Valid values: "ovn-controlplane", "ovn-dataplane", "rabbitmq", "mariadb", "memcached",
+	// "keystone", "controlplane". Remove the annotation to let the update proceed to completion.
+	MinorUpdateTargetStageAnnotation string = "core.openstack.org/update-target-stage"
+
+	// MinorUpdateStageOVNControlplane - stage name for OVN controlplane update
+	MinorUpdateStageOVNControlplane string = "ovn-controlplane"
+	// MinorUpdateStageOVNDataplane - stage name for OVN dataplane update
+	MinorUpdateStageOVNDataplane string = "ovn-dataplane"
+	// MinorUpdateStageRabbitMQ - stage name for RabbitMQ update
+	MinorUpdateStageRabbitMQ string = "rabbitmq"
+	// MinorUpdateStageMariaDB - stage name for MariaDB update
+	MinorUpdateStageMariaDB string = "mariadb"
+	// MinorUpdateStageMemcached - stage name for Memcached update
+	MinorUpdateStageMemcached string = "memcached"
+	// MinorUpdateStageKeystone - stage name for Keystone update
+	MinorUpdateStageKeystone string = "keystone"
+	// MinorUpdateStageControlplane - stage name for full controlplane update
+	MinorUpdateStageControlplane string = "controlplane"
 )
 
+// validMinorUpdateTargetStagesOrdered is the single source of truth for allowed
+// MinorUpdateTargetStageAnnotation values, listed in rollout order.
+var validMinorUpdateTargetStagesOrdered = []string{
+	MinorUpdateStageOVNControlplane,
+	MinorUpdateStageOVNDataplane,
+	MinorUpdateStageRabbitMQ,
+	MinorUpdateStageMariaDB,
+	MinorUpdateStageMemcached,
+	MinorUpdateStageKeystone,
+	MinorUpdateStageControlplane,
+}
+
+// minorUpdateTargetStageConditionTypes maps each validMinorUpdateTargetStagesOrdered entry to its status condition.
+var minorUpdateTargetStageConditionTypes = map[string]condition.Type{
+	MinorUpdateStageOVNControlplane: OpenStackVersionMinorUpdateOVNControlplane,
+	MinorUpdateStageOVNDataplane:    OpenStackVersionMinorUpdateOVNDataplane,
+	MinorUpdateStageRabbitMQ:        OpenStackVersionMinorUpdateRabbitMQ,
+	MinorUpdateStageMariaDB:         OpenStackVersionMinorUpdateMariaDB,
+	MinorUpdateStageMemcached:       OpenStackVersionMinorUpdateMemcached,
+	MinorUpdateStageKeystone:        OpenStackVersionMinorUpdateKeystone,
+	MinorUpdateStageControlplane:    OpenStackVersionMinorUpdateControlplane,
+}
+
+// validMinorUpdateTargetStages is a set derived from validMinorUpdateTargetStagesOrdered for O(1) lookup.
+var validMinorUpdateTargetStages = func() map[string]struct{} {
+	m := make(map[string]struct{}, len(validMinorUpdateTargetStagesOrdered))
+	for _, s := range validMinorUpdateTargetStagesOrdered {
+		m[s] = struct{}{}
+	}
+	return m
+}()
+
+// IsValidMinorUpdateTargetStage reports whether v is a supported minor-update target stage name.
+func IsValidMinorUpdateTargetStage(v string) bool {
+	if v == "" {
+		return false
+	}
+	_, ok := validMinorUpdateTargetStages[v]
+	return ok
+}
+
+// ValidMinorUpdateTargetStages returns allowed annotation values in rollout order.
+func ValidMinorUpdateTargetStages() []string {
+	return validMinorUpdateTargetStagesOrdered
+}
+
+// MinorUpdateTargetStageIndex returns the rollout order index for stage.
+func MinorUpdateTargetStageIndex(stage string) (int, bool) {
+	for i, s := range validMinorUpdateTargetStagesOrdered {
+		if s == stage {
+			return i, true
+		}
+	}
+	return -1, false
+}
+
+// MinorUpdateTargetStageFromAnnotations returns the target-stage annotation value when set and valid.
+func MinorUpdateTargetStageFromAnnotations(annotations map[string]string) (string, bool) {
+	if annotations == nil {
+		return "", false
+	}
+	stage, ok := annotations[MinorUpdateTargetStageAnnotation]
+	if !ok || !IsValidMinorUpdateTargetStage(stage) {
+		return "", false
+	}
+	return stage, true
+}
+
+// MinorUpdateStageAllowedForReconcile reports whether the control plane may patch resources
+// for rollout stage during a minor update. When the target-stage annotation is absent, all
+// stages are allowed. When set, only stages up to and including the target may be reconciled.
+func MinorUpdateStageAllowedForReconcile(annotations map[string]string, stage string) bool {
+	target, ok := MinorUpdateTargetStageFromAnnotations(annotations)
+	if !ok {
+		return true
+	}
+	stageIdx, okStage := MinorUpdateTargetStageIndex(stage)
+	targetIdx, okTarget := MinorUpdateTargetStageIndex(target)
+	if !okStage || !okTarget {
+		return true
+	}
+	return stageIdx <= targetIdx
+}
+
+// LatestCompletedMinorUpdateTargetStageIndex returns the rollout index of the furthest
+// minor-update stage marked True in status, or -1 when no annotated rollout stage has completed.
+func LatestCompletedMinorUpdateTargetStageIndex(status OpenStackVersionStatus) int {
+	latest := -1
+	for i, stage := range validMinorUpdateTargetStagesOrdered {
+		if status.Conditions.IsTrue(minorUpdateTargetStageConditionTypes[stage]) {
+			latest = i
+		}
+	}
+	return latest
+}
+
 // OpenStackVersionSpec - defines the desired state of OpenStackVersion
 type OpenStackVersionSpec struct {
 

api/core/v1beta1/openstackversion_webhook.go

@@ -21,6 +21,7 @@ import (
 	"fmt"
 	"os"
 	"reflect"
+	"strings"
 
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
 	"k8s.io/apimachinery/pkg/runtime/schema"
@@ -74,6 +75,10 @@ func (r *OpenStackVersion) ValidateCreate(ctx context.Context, c goClient.Client
 		)
 	}
 
+	if err := validateMinorUpdateTargetStageAnnotation(r.Annotations, r.GetName()); err != nil {
+		return nil, err
+	}
+
 	versionList, err := GetOpenStackVersions(r.Namespace, c)
 
 	if err != nil {
@@ -114,6 +119,10 @@ func (r *OpenStackVersion) ValidateCreate(ctx context.Context, c goClient.Client
 func (r *OpenStackVersion) ValidateUpdate(ctx context.Context, old runtime.Object, c goClient.Client) (admission.Warnings, error) {
 	openstackversionlog.Info("validate update", "name", r.Name)
 
+	if err := validateMinorUpdateTargetStageAnnotation(r.Annotations, r.GetName()); err != nil {
+		return nil, err
+	}
+
 	_, ok := r.Status.ContainerImageVersionDefaults[r.Spec.TargetVersion]
 	if r.Spec.TargetVersion != openstackVersionDefaults.AvailableVersion && !ok {
 		return nil, apierrors.NewForbidden(
@@ -135,6 +144,11 @@ func (r *OpenStackVersion) ValidateUpdate(ctx context.Context, old runtime.Objec
 		return nil, apierrors.NewInternalError(fmt.Errorf("failed to convert old object to OpenStackVersion"))
 	}
 
+	// Validate that the target stage annotation is not from earlier stage while a minor update is in progress
+	if err := validateMinorUpdateTargetStageAnnotationProgress(oldVersion, r); err != nil {
+		return nil, err
+	}
+
 	// Check if targetVersion is changing and this is a minor update
 	if oldVersion.Spec.TargetVersion != r.Spec.TargetVersion && oldVersion.Status.DeployedVersion != nil {
 		// Check if the skip annotation is present
@@ -174,6 +188,113 @@ func (r *OpenStackVersion) ValidateUpdate(ctx context.Context, old runtime.Objec
 	return nil, nil
 }
 
+func validateMinorUpdateTargetStageAnnotation(annotations map[string]string, resourceName string) error {
+	if annotations == nil {
+		return nil
+	}
+	stage, ok := annotations[MinorUpdateTargetStageAnnotation]
+	if !ok {
+		return nil
+	}
+	annotationField := "metadata.annotations[" + MinorUpdateTargetStageAnnotation + "]"
+	if stage == "" {
+		return apierrors.NewForbidden(
+			schema.GroupResource{
+				Group:    GroupVersion.WithKind("OpenStackVersion").Group,
+				Resource: GroupVersion.WithKind("OpenStackVersion").Kind,
+			}, resourceName, &field.Error{
+				Type:     field.ErrorTypeForbidden,
+				Field:    annotationField,
+				BadValue: stage,
+				Detail:   "Annotation value must not be empty. Remove the annotation or set a valid stage name",
+			},
+		)
+	}
+	if !IsValidMinorUpdateTargetStage(stage) {
+		return apierrors.NewForbidden(
+			schema.GroupResource{
+				Group:    GroupVersion.WithKind("OpenStackVersion").Group,
+				Resource: GroupVersion.WithKind("OpenStackVersion").Kind,
+			}, resourceName, &field.Error{
+				Type:     field.ErrorTypeForbidden,
+				Field:    annotationField,
+				BadValue: stage,
+				Detail: fmt.Sprintf(
+					"Invalid target stage %q. Must be one of: %s",
+					stage,
+					strings.Join(ValidMinorUpdateTargetStages(), ", "),
+				),
+			},
+		)
+	}
+	return nil
+}
+
+func minorUpdateInProgress(v *OpenStackVersion) bool {
+	if v.Status.DeployedVersion == nil {
+		return false
+	}
+	return v.Spec.TargetVersion != *v.Status.DeployedVersion
+}
+
+// validateMinorUpdateTargetStageAnnotationProgress rejects moving the target-stage
+// annotation to an earlier rollout stage while a minor update is in progress, and rejects
+// adding the annotation behind stages already completed when it was absent at update start.
+func validateMinorUpdateTargetStageAnnotationProgress(old, new *OpenStackVersion) error {
+	if !minorUpdateInProgress(new) {
+		return nil
+	}
+	oldStage, oldOK := MinorUpdateTargetStageFromAnnotations(old.Annotations)
+	newStage, newOK := MinorUpdateTargetStageFromAnnotations(new.Annotations)
+	if !newOK {
+		return nil
+	}
+	newIdx, okNew := MinorUpdateTargetStageIndex(newStage)
+	if !okNew {
+		return nil
+	}
+	annotationField := "metadata.annotations[" + MinorUpdateTargetStageAnnotation + "]"
+	gr := schema.GroupResource{
+		Group:    GroupVersion.WithKind("OpenStackVersion").Group,
+		Resource: GroupVersion.WithKind("OpenStackVersion").Kind,
+	}
+
+	if !oldOK {
+		latest := LatestCompletedMinorUpdateTargetStageIndex(old.Status)
+		if latest >= 0 && newIdx < latest {
+			completedStage := validMinorUpdateTargetStagesOrdered[latest]
+			return apierrors.NewForbidden(
+				gr, new.GetName(), &field.Error{
+					Type:     field.ErrorTypeForbidden,
+					Field:    annotationField,
+					BadValue: newStage,
+					Detail: fmt.Sprintf(
+						"Cannot set update target stage to %q while minor update is in progress: update has already completed stage %q (targetVersion %q, deployedVersion %q); choose a further stage",
+						newStage, completedStage, new.Spec.TargetVersion, *new.Status.DeployedVersion,
+					),
+				},
+			)
+		}
+		return nil
+	}
+
+	oldIdx, _ := MinorUpdateTargetStageIndex(oldStage)
+	if newIdx >= oldIdx {
+		return nil
+	}
+	return apierrors.NewForbidden(
+		gr, new.GetName(), &field.Error{
+			Type:     field.ErrorTypeForbidden,
+			Field:    annotationField,
+			BadValue: newStage,
+			Detail: fmt.Sprintf(
+				"Cannot move update target stage from %q to earlier stage %q while minor update is in progress (targetVersion %q, deployedVersion %q); remove the annotation or set a further stage",
+				oldStage, newStage, new.Spec.TargetVersion, *new.Status.DeployedVersion,
+			),
+		},
+	)
+}
+
 // hasAnyCustomImage checks if any image field in CustomContainerImages is set
 func hasAnyCustomImage(images CustomContainerImages) bool {
 	// Check CinderVolumeImages map