feat(controller): gate new instances on referenced data behind a feature flag

Instances whose template references ConfigMaps or Secrets now receive a
ReferencedData scheduling gate at creation, so the provider does not launch
them before their mounted data exists on the cell. Launching ungated would
surface as containers missing env vars or mount sources rather than a clear
pending state.

Stamping is controlled by the new enableReferencedDataGate feature flag,
default off: the gate must not be introduced until the cell gate-clearing
reconciler and provider gate-honoring are deployed everywhere, otherwise
gated instances would stall indefinitely or launch without their data.
Templates with no references never receive the gate regardless of the flag.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: scotwells

cmd/main.go

@@ -273,9 +273,12 @@ func main() {
 	}
 
 	if enableCellControllers {
+		wdOpts := controller.WorkloadDeploymentReconcilerOptions{
+			EnableReferencedDataGate: serverConfig.FeatureFlags.EnableReferencedDataGate,
+		}
 		if err = (&controller.WorkloadDeploymentReconciler{
 			NetworkingEnabled: features.FeatureGate.Enabled(features.NetworkingIntegration),
-		}).SetupWithManager(mgr); err != nil {
+		}).SetupWithManager(mgr, wdOpts); err != nil {
 			setupLog.Error(err, "unable to create controller", "controller", "WorkloadDeployment")
 			os.Exit(1)
 		}

internal/config/config.go

@@ -37,6 +37,9 @@ type WorkloadOperator struct {
 
 	Discovery DiscoveryConfig `json:"discovery"`
 
+	// FeatureFlags configures optional management-plane feature gates.
+	FeatureFlags FeatureFlagsConfig `json:"featureFlags,omitempty"`
+
 	// ReferencedData configures the ReferencedDataController.
 	ReferencedData ReferencedDataConfig `json:"referencedData,omitempty"`
 }
@@ -60,6 +63,26 @@ type ReferencedDataConfig struct {
 
 // +k8s:deepcopy-gen=true
 
+// FeatureFlagsConfig holds management-plane feature gates. All flags default
+// to false (off) unless explicitly enabled, so that new capabilities can be
+// merged and deployed safely before the full feature rollout is complete.
+type FeatureFlagsConfig struct {
+	// EnableReferencedDataGate controls whether new Instances receive the
+	// "ReferencedData" scheduling gate when the workload template references
+	// ConfigMaps or Secrets.
+	//
+	// This gate MUST NOT be enabled until both the cell gate-clearing reconciler
+	// (Phase 2) and the unikraft provider gate-honoring (Phase 3) are confirmed
+	// deployed everywhere. Enabling it prematurely will cause gated instances to
+	// either stall indefinitely (cell not yet clearing) or launch without the
+	// referenced data mounted (provider not yet honoring gates).
+	//
+	// Defaults to false.
+	EnableReferencedDataGate bool `json:"enableReferencedDataGate,omitempty"`
+}
+
+// +k8s:deepcopy-gen=true
+
 type WebhookServerConfig struct {
 	// Host is the address that the server will listen on.
 	// Defaults to "" - all addresses.

internal/config/zz_generated.deepcopy.go

@@ -5,6 +5,12 @@ type SchedulingGate string
 const (
 	NetworkSchedulingGate SchedulingGate = "Network"
 	QuotaSchedulingGate   SchedulingGate = "Quota"
+
+	// ReferencedDataSchedulingGate is stamped on new instances when the workload
+	// template references ConfigMaps or Secrets AND the management-plane feature
+	// flag EnableReferencedDataGate is enabled. It is cleared by the cell
+	// InstanceReconciler once all expected companion objects are present.
+	ReferencedDataSchedulingGate SchedulingGate = "ReferencedData"
 )
 
 func (s SchedulingGate) String() string {

internal/controller/instancecontrol/scheduling_gates.go

@@ -13,6 +13,7 @@ import (
 
 	"go.datum.net/compute/api/v1alpha"
 	"go.datum.net/compute/internal/controller/instancecontrol"
+	"go.datum.net/compute/internal/referenceddata"
 )
 
 // Options controls optional behaviours of the stateful instance control strategy.
@@ -22,6 +23,12 @@ type Options struct {
 	// disabled so that Instances are not blocked waiting for a NetworkBinding.
 	// Defaults to true.
 	NetworkingEnabled bool
+
+	// EnableReferencedDataGate controls whether new Instances receive the
+	// ReferencedData scheduling gate when the workload template references
+	// ConfigMaps or Secrets. Defaults to false. See FeatureFlagsConfig for the
+	// full safety rationale.
+	EnableReferencedDataGate bool
 }
 
 // Behavior inspired by https://github.com/kubernetes/kubernetes/tree/master/pkg/controller/statefulset
@@ -103,6 +110,16 @@ func (c *statefulControl) GetActions(
 					{Name: instancecontrol.NetworkSchedulingGate.String()},
 				}, gates...)
 			}
+
+			// Stamp the ReferencedData gate only when the management-plane feature
+			// flag is on AND the template actually references ConfigMaps or Secrets.
+			// The gate must not be inserted before the cell gate-clearing reconciler
+			// and provider gate-honoring are deployed everywhere — see
+			// FeatureFlagsConfig.EnableReferencedDataGate for the full rationale.
+			if c.opts.EnableReferencedDataGate && referenceddata.TemplateReferencesData(deployment.Spec.Template) {
+				gates = append(gates, v1alpha.SchedulingGate{Name: instancecontrol.ReferencedDataSchedulingGate.String()})
+			}
+
 			desiredInstances[i].Spec.Controller = &v1alpha.InstanceController{
 				TemplateHash:    instanceTemplateHash,
 				SchedulingGates: gates,

internal/controller/instancecontrol/stateful/stateful_control.go

@@ -29,7 +29,7 @@ func init() {
 
 func TestFreshDeployment(t *testing.T) {
 	ctx := context.Background()
-	control := New()
+	control := NewWithOptions(Options{})
 
 	deployment := getWorkloadDeployment("test-fresh-deploy", 2)
 
@@ -56,7 +56,7 @@ func TestFreshDeployment(t *testing.T) {
 // at creation time and ignores spec changes on an existing pod.
 func TestUpdateWithAllReadyInstances(t *testing.T) {
 	ctx := context.Background()
-	control := New()
+	control := NewWithOptions(Options{})
 
 	deployment := getWorkloadDeployment("test-deploy", 2)
 
@@ -82,7 +82,7 @@ func TestUpdateWithAllReadyInstances(t *testing.T) {
 
 func TestScaleUpWithNotReadyInstance(t *testing.T) {
 	ctx := context.Background()
-	control := New()
+	control := NewWithOptions(Options{})
 
 	deployment := getWorkloadDeployment("test-deploy", 3)
 
@@ -112,7 +112,7 @@ func TestScaleUpWithNotReadyInstance(t *testing.T) {
 
 func TestScaleUpWithDeletingReadyInstance(t *testing.T) {
 	ctx := context.Background()
-	control := New()
+	control := NewWithOptions(Options{})
 
 	deployment := getWorkloadDeployment("test-deploy", 3)
 
@@ -139,7 +139,7 @@ func TestScaleUpWithDeletingReadyInstance(t *testing.T) {
 
 func TestScaleDownWithAllReadyInstances(t *testing.T) {
 	ctx := context.Background()
-	control := New()
+	control := NewWithOptions(Options{})
 
 	deployment := getWorkloadDeployment("test-deploy", 1)
 

internal/controller/instancecontrol/stateful/stateful_control_test.go

@@ -45,6 +45,11 @@ type WorkloadDeploymentReconciler struct {
 	// actively removed if present), and the networking step is treated as
 	// immediately ready. Defaults to true.
 	NetworkingEnabled bool
+
+	// enableReferencedDataGate mirrors FeatureFlagsConfig.EnableReferencedDataGate.
+	// When true, new Instances whose template references ConfigMaps or Secrets
+	// receive the ReferencedData scheduling gate at creation time.
+	enableReferencedDataGate bool
 }
 
 // +kubebuilder:rbac:groups=compute.datumapis.com,resources=workloaddeployments,verbs=get;list;watch;create;update;patch;delete
@@ -113,7 +118,8 @@ func (r *WorkloadDeploymentReconciler) Reconcile(ctx context.Context, req mcreco
 	}
 
 	instanceControl := instancecontrolstateful.NewWithOptions(instancecontrolstateful.Options{
-		NetworkingEnabled: r.NetworkingEnabled,
+		NetworkingEnabled:        r.NetworkingEnabled,
+		EnableReferencedDataGate: r.enableReferencedDataGate,
 	})
 
 	actions, err := instanceControl.GetActions(ctx, cl.GetScheme(), &deployment, instances.Items)
@@ -549,9 +555,18 @@ func (r *WorkloadDeploymentReconciler) Finalize(ctx context.Context, obj client.
 	return finalizer.Result{}, errDeploymentHasInstances
 }
 
+// WorkloadDeploymentReconcilerOptions configures the WorkloadDeploymentReconciler.
+type WorkloadDeploymentReconcilerOptions struct {
+	// EnableReferencedDataGate mirrors FeatureFlagsConfig.EnableReferencedDataGate.
+	EnableReferencedDataGate bool
+}
+
 // SetupWithManager sets up the controller with the Manager.
-func (r *WorkloadDeploymentReconciler) SetupWithManager(mgr mcmanager.Manager) error {
+func (r *WorkloadDeploymentReconciler) SetupWithManager(mgr mcmanager.Manager, opts ...WorkloadDeploymentReconcilerOptions) error {
 	r.mgr = mgr
+	for _, o := range opts {
+		r.enableReferencedDataGate = o.EnableReferencedDataGate
+	}
 	r.finalizers = finalizer.NewFinalizers()
 	if err := r.finalizers.Register(workloadControllerFinalizer, r); err != nil {
 		return fmt.Errorf("failed to register finalizer: %w", err)