kubefleet-dev · Yetkin Timocin (ytimocin) · Aug 14, 2026 · Aug 14, 2026 · Aug 18, 2026 · Aug 18, 2026
@@ -16,6 +16,64 @@ limitations under the License.
 
 package v1alpha1
 
+// The annotation and label keys that KubeFleet reserves for the placement APIs.
+//
+// Note that these keys carry the KubeFleet domain itself rather than the API group; they are
+// set on arbitrary Kubernetes objects, not only on the objects of this group.
+const (
+	// KubeFleetPrefix is the domain that prefixes every reserved annotation and label key below,
+	// per the Kubernetes convention that reserves unprefixed keys for end users.
+	KubeFleetPrefix = "kubefleet.dev/"
+
+	// ClusterSelectorsAnnotation is the annotation that requests annotation-based placement for the
+	// resource it is set on. Its value is a semicolon-separated list of cluster selectors, each of
+	// which is a comma-separated list of LABEL_KEY=LABEL_VALUE label matchers with an optional
+	// count=N|All directive, e.g.:
+	//
+	//     kubefleet.dev/cluster-selectors: "env=staging,count=All;env=canary,region=eastus,count=1"
+	//
+	// KubeFleet keeps a PlacementPolicy (or ClusterPlacementPolicy) object in sync with the
+	// annotation for as long as it is present.
+	//
+	// The key names what the value holds rather than what KubeFleet does with it, matching the
+	// clusterSelectors field of the generated policy: the annotation is one way to write that field,
+	// and the two are read together often enough that they should not have to be translated.
+	//
+	// Within the annotation, `region` may be used in place of the well-known
+	// topology.kubernetes.io/region label key, and `alias` in place of ClusterAliasLabel.
+	ClusterSelectorsAnnotation = KubeFleetPrefix + "cluster-selectors"
+
+	// ClusterAliasLabel is the label that KubeFleet reserves on member cluster objects for selecting
+	// clusters by their name (alias).
+	ClusterAliasLabel = KubeFleetPrefix + "cluster-alias"
+)
+
+// The labels that record, on a placement policy KubeFleet generated from an annotation, the
+// resource whose annotation caused it to exist.
+//
+// These keys carry the API group rather than the bare KubeFleet domain, since unlike the keys
+// above they are set on objects of this group.
+//
+// The labels exist so that a policy can be found with a List when its generated name is not known;
+// the owner reference on the policy remains the authoritative record of where it came from. Note
+// that ParentNameLabel is lossy: the name of a resource can run to 253 bytes while a label value
+// stops at 63, so for a longer name the label holds a prefix and a hash instead, and selecting on
+// it with the resource's own name matches nothing.
+const (
+	// ParentAPIGroupLabel holds the API group of the resource a policy was generated from. It is
+	// the empty string for resources in the core API group, and is always present, so that
+	// core-group resources can be selected as readily as any other.
+	ParentAPIGroupLabel = "placement.kubefleet.dev/parent-api-group"
+
+	// ParentKindLabel holds the kind of the resource a policy was generated from, spelled as the
+	// kind itself is (Deployment, not deployment).
+	ParentKindLabel = "placement.kubefleet.dev/parent-kind"
+
+	// ParentNameLabel holds the name of the resource a policy was generated from, shortened if it
+	// does not fit in a label value.
+	ParentNameLabel = "placement.kubefleet.dev/parent-name"
+)
+
 type ObjectReference struct {
 	// The namespace of the referenced object.
 	//

@@ -149,7 +149,17 @@ type PlacementPolicySpec struct {
 	Tolerations []Toleration `json:"tolerations,omitempty"`
 }
 
-// +kubebuilder:validation:XValidation:rule="!has(self.minCount) || !has(self.count) || (type(self.count) == string && self.count == 'All') || (type(self.count) == int && self.minCount <= self.count) || (type(self.count) == string && self.count.matches('^[0-9]+$') && self.minCount <= int(self.count))",message="minCount must be less than or equal to count when count is not All"
+// A string form of count is compared against minCount only when it is a numeric one of at most the
+// three digits that the count field's own pattern permits -- the {1,3} bound below must move with
+// that pattern's ceiling. Any other string ("All", or junk the pattern rejects) passes this rule
+// vacuously, so that the field's own validation reports the real problem alone. The previous,
+// unbounded digit guard let a string longer than an int64 reach int(), turning a plain pattern
+// violation into an opaque evaluation error beside it. The digit class is spelled [0-9]{1,3}
+// rather than mirroring the pattern's [1-9][0-9]{0,2} verbatim because the CEL cost estimator
+// prices a regex by its length against an unbounded string -- an int-or-string is opaque to the
+// sibling MaxLength -- and the longer spelling does not fit the budget.
+
+// +kubebuilder:validation:XValidation:rule="!has(self.minCount) || !has(self.count) || (type(self.count) == int && self.minCount <= self.count) || (type(self.count) == string && (!self.count.matches('^[0-9]{1,3}$') || self.minCount <= int(self.count)))",message="minCount must be less than or equal to count"
 type ClusterSelector struct {
 	// A list of terms that form the selector. The terms are ORed, i.e., a cluster would match the selector
 	// if it matches any of the terms.
@@ -160,14 +170,22 @@ type ClusterSelector struct {
 	// +kubebuilder:validation:MaxItems=5
 	Terms []ClusterLabelAndPropertySelectorTerm `json:"terms,omitempty"`
 
+	// The two validation markers below split the work by form: a pattern constrains only the string
+	// form of an int-or-string ("All", and digits arriving as a quoted string), so the CEL rule is
+	// what bounds the integer form. Without it, an unquoted count outside 1-999 is accepted while
+	// the same number in quotes is rejected. This block is deliberately detached from the field's
+	// doc comment: it is rationale for maintainers, not schema documentation for users.
+
 	// The desired number of clusters that KubeFleet should select based on the given terms.
 	//
 	// The default value is 1. To select all clusters that match the given terms, use the value "All".
 	//
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:default=1
 	// +kubebuilder:validation:XIntOrString
+	// +kubebuilder:validation:MaxLength=3
 	// +kubebuilder:validation:Pattern="^([1-9][0-9]{0,2}|All)$"
+	// +kubebuilder:validation:XValidation:rule="type(self) == int ? self >= 1 && self <= 999 : true",message="count must be between 1 and 999, or \"All\""
 	Count *intstr.IntOrString `json:"count,omitempty"`
 
 	// The minimum number of clusters that KubeFleet should select based on the given terms, when KubeFleet is not able

@@ -969,7 +969,8 @@ type RollingUpdateConfig struct {
 	// Defaults to 25%.
 	// +kubebuilder:default="25%"
 	// +kubebuilder:validation:XIntOrString
-	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]+)$"
+	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]{1,9})$"
+	// +kubebuilder:validation:XValidation:rule="type(self) == int ? self >= 0 : true",message="maxUnavailable must be a non-negative integer or a percentage"
 	// +kubebuilder:validation:Optional
 	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable,omitempty"`
 
@@ -983,7 +984,8 @@ type RollingUpdateConfig struct {
 	// Defaults to 25%.
 	// +kubebuilder:default="25%"
 	// +kubebuilder:validation:XIntOrString
-	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]+)$"
+	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]{1,9})$"
+	// +kubebuilder:validation:XValidation:rule="type(self) == int ? self >= 0 : true",message="maxSurge must be a non-negative integer or a percentage"
 	// +kubebuilder:validation:Optional
 	MaxSurge *intstr.IntOrString `json:"maxSurge,omitempty"`
 

@@ -984,7 +984,8 @@ type RollingUpdateConfig struct {
 	// Defaults to 25%.
 	// +kubebuilder:default="25%"
 	// +kubebuilder:validation:XIntOrString
-	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]+)$"
+	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]{1,9})$"
+	// +kubebuilder:validation:XValidation:rule="type(self) == int ? self >= 0 : true",message="maxUnavailable must be a non-negative integer or a percentage"
 	// +kubebuilder:validation:Optional
 	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable,omitempty"`
 
@@ -998,7 +999,8 @@ type RollingUpdateConfig struct {
 	// Defaults to 25%.
 	// +kubebuilder:default="25%"
 	// +kubebuilder:validation:XIntOrString
-	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]+)$"
+	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]{1,9})$"
+	// +kubebuilder:validation:XValidation:rule="type(self) == int ? self >= 0 : true",message="maxSurge must be a non-negative integer or a percentage"
 	// +kubebuilder:validation:Optional
 	MaxSurge *intstr.IntOrString `json:"maxSurge,omitempty"`
 

@@ -109,6 +109,7 @@ _See [helm install](https://helm.sh/docs/helm/helm_install/) for command documen
 | `enableClusterInventoryAPI` | Enable cluster inventory APIs | `true` |
 | `enableStagedUpdateRunAPIs` | Enable staged update run APIs | `true` |
 | `enableEvictionAPIs` | Enable eviction APIs | `true` |
+| `enableAnnotationBasedPlacement` | Keep a placement policy in sync with the `kubefleet.dev/cluster-selectors` annotation on a resource. Requires the `placement.kubefleet.dev/v1alpha1` CRDs. No chart installs them yet; apply them from `config/crd/bases/` (the hub agent refuses to start with this flag on until they are present). | `false` |
 | `enablePprof` | Enable pprof endpoint | `true` |
 | `pprofPort` | pprof server port | `6065` |
 | `hubAPIQPS` | QPS for fleet-apiserver (not including events/node heartbeat) | `250` |

@@ -50,6 +50,7 @@ spec:
             - --enable-cluster-inventory-apis={{ .Values.enableClusterInventoryAPI }}
             - --enable-staged-update-run-apis={{ .Values.enableStagedUpdateRunAPIs }}
             - --enable-eviction-apis={{ .Values.enableEvictionAPIs}}
+            - --enable-annotation-based-placement={{ .Values.enableAnnotationBasedPlacement }}
             - --enable-pprof={{ .Values.enablePprof }}
             - --pprof-port={{ .Values.pprofPort }}
             - --max-concurrent-cluster-placement={{ .Values.MaxConcurrentClusterPlacement }}

@@ -67,6 +67,20 @@ rules:
       - approvalrequests/status
     verbs: ["get", "update"]
 
+  # Placement policies the hub-agent generates from the
+  # kubefleet.dev/cluster-selectors annotation on a resource. Unlike the
+  # user-created placement resources above, the hub-agent owns these outright:
+  # it creates one when the annotation appears, updates it when the annotation
+  # changes, and deletes it when the annotation is removed. No status
+  # subresource rule: the generating controller never writes status.
+  #
+  # The broad read rule further down does not cover these, being read-only.
+  - apiGroups: ["placement.kubefleet.dev"]
+    resources:
+      - placementpolicies
+      - clusterplacementpolicies
+    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
+
   # Fleet cluster APIs. MemberCluster is user-created and user-deleted; the
   # hub-agent only adds/removes its finalizer (update) and writes status.
   # InternalMemberCluster is created by the hub-agent and cleaned up via

@@ -48,6 +48,10 @@ affinity: {}
 enableClusterInventoryAPI: true
 enableStagedUpdateRunAPIs: true
 enableEvictionAPIs: true
+# Keeps a placement policy in sync with the kubefleet.dev/cluster-selectors annotation on a resource.
+# It requires the placement.kubefleet.dev/v1alpha1 custom resource definitions, which this chart does not
+# install yet, so it is off by default.
+enableAnnotationBasedPlacement: false
 
 enablePprof: true
 pprofPort: 6065

@@ -44,6 +44,7 @@ import (
 	fleetnetworkingv1alpha1 "go.goms.io/fleet-networking/api/v1alpha1"
 
 	clusterv1beta1 "github.com/kubefleet-dev/kubefleet/apis/cluster/v1beta1"
+	kfplacementv1alpha1 "github.com/kubefleet-dev/kubefleet/apis/kubefleet.dev/placement/v1alpha1"
 	placementv1alpha1 "github.com/kubefleet-dev/kubefleet/apis/placement/v1alpha1"
 	placementv1beta1 "github.com/kubefleet-dev/kubefleet/apis/placement/v1beta1"
 	"github.com/kubefleet-dev/kubefleet/cmd/hubagent/options"
@@ -80,6 +81,7 @@ func init() {
 	utilruntime.Must(fleetnetworkingv1alpha1.AddToScheme(scheme))
 	utilruntime.Must(placementv1alpha1.AddToScheme(scheme))
 	utilruntime.Must(clusterinventory.AddToScheme(scheme))
+	utilruntime.Must(kfplacementv1alpha1.AddToScheme(scheme))
 	// +kubebuilder:scaffold:scheme
 	klog.InitFlags(nil)
 }
@@ -171,6 +173,7 @@ func main() {
 			NetworkingAgentsEnabled: opts.ClusterMgmtOpts.NetworkingAgentsEnabled,
 			MaxConcurrentReconciles: int(math.Ceil(float64(opts.PlacementMgmtOpts.MaxFleetSize) / 100)), //one member cluster reconciler routine per 100 member clusters
 			ForceDeleteWaitTime:     opts.ClusterMgmtOpts.ForceDeleteWaitTime.Duration,
+			SeedClusterAliasLabel:   opts.FeatureFlags.EnableAnnotationBasedPlacement,
 		}).SetupWithManager(mgr, "membercluster-controller"); err != nil {
 			klog.ErrorS(err, "unable to create v1beta1 controller", "controller", "MemberCluster")
 			exitWithErrorFunc()

@@ -51,6 +51,17 @@ type FeatureFlags struct {
 	// ResourcePlacement APIs are a set of KubeFleet APIs for processing namespace scoped resource placements.
 	// This flag does not concern the cluster-scoped placement APIs (`ClusterResourcePlacement` and its related APIs).
 	EnableResourcePlacementAPIs bool
+
+	// Enable annotation-based placement in the KubeFleet hub agent or not.
+	//
+	// With it enabled, the hub agent keeps a placement policy in sync with the
+	// kubefleet.dev/cluster-selectors annotation on any resource it watches, so that a placement can
+	// be expressed without authoring a placement policy by hand.
+	//
+	// This defaults to off. The feature reads and writes the placement.kubefleet.dev/v1alpha1
+	// placement policy APIs, which are alpha and whose custom resource definitions a cluster does not
+	// necessarily have installed.
+	EnableAnnotationBasedPlacement bool
 }
 
 // AddFlags adds flags for FeatureFlags to the specified FlagSet.
@@ -88,6 +99,13 @@ func (o *FeatureFlags) AddFlags(flags *flag.FlagSet) {
 		true,
 		"Enable the ResourcePlacement API support (for namespace-scoped placements) in the KubeFleet hub agent or not.",
 	)
+
+	flags.BoolVar(
+		&o.EnableAnnotationBasedPlacement,
+		"enable-annotation-based-placement",
+		false,
+		"Enable annotation-based placement in the KubeFleet hub agent or not. It requires the placement.kubefleet.dev/v1alpha1 custom resource definitions to be installed.",
+	)
 }
 
 // A list of flag variables that allow pluggable validation logic when parsing the input args.

@@ -334,6 +334,9 @@ func TestFeatureFlags(t *testing.T) {
 				EnableStagedUpdateRunAPIs:   true,
 				EnableEvictionAPIs:          true,
 				EnableResourcePlacementAPIs: true,
+				// Annotation-based placement is alpha and needs CRDs the chart does not install,
+				// so unlike its siblings it is off unless asked for.
+				EnableAnnotationBasedPlacement: false,
 			},
 		},
 		{
@@ -345,13 +348,15 @@ func TestFeatureFlags(t *testing.T) {
 				"--enable-staged-update-run-apis=false",
 				"--enable-eviction-apis=false",
 				"--enable-resource-placement=false",
+				"--enable-annotation-based-placement=true",
 			},
 			wantFeatureFlags: FeatureFlags{
-				EnableV1Beta1APIs:           true,
-				EnableClusterInventoryAPIs:  false,
-				EnableStagedUpdateRunAPIs:   false,
-				EnableEvictionAPIs:          false,
-				EnableResourcePlacementAPIs: false,
+				EnableV1Beta1APIs:              true,
+				EnableClusterInventoryAPIs:     false,
+				EnableStagedUpdateRunAPIs:      false,
+				EnableEvictionAPIs:             false,
+				EnableResourcePlacementAPIs:    false,
+				EnableAnnotationBasedPlacement: true,
 			},
 		},
 		{