fix: reject image items in a (Cluster)ReplicatedImageSet spec.filter

Author: plaffitt

api/kuik/v1alpha1/clusterreplicatedimageset_types.go

@@ -5,11 +5,13 @@ import (
 )
 
 // ClusterReplicatedImageSetSpec defines the desired state of ClusterReplicatedImageSet.
+// +kubebuilder:validation:XValidation:rule="!has(self.filter) || ((!has(self.filter.include) || self.filter.include.all(i, !has(i.image))) && (!has(self.filter.exclude) || self.filter.exclude.all(i, !has(i.image))))",message="spec.filter image items are not supported on ClusterReplicatedImageSet; image selection is per-upstream via spec.upstreams[].imageFilter"
 type ClusterReplicatedImageSetSpec struct {
 	ReplicatedImageSetBase `json:",inline"`
 
-	// Filter selects which pods, namespaces and images this resource applies
-	// to. It replaces the deprecated imageFilter.
+	// Filter selects which pods and namespaces this resource applies to (label,
+	// annotation and namespace dimensions). The image dimension is not supported
+	// here: image selection is per-upstream via spec.upstreams[].imageFilter.
 	// +optional
 	Filter ClusterFilter `json:"filter,omitempty"`
 }

api/kuik/v1alpha1/replicatedimageset_types.go

@@ -20,11 +20,13 @@ type ReplicatedImageSetBase struct {
 }
 
 // ReplicatedImageSetSpec defines the desired state of ReplicatedImageSet.
+// +kubebuilder:validation:XValidation:rule="!has(self.filter) || ((!has(self.filter.include) || self.filter.include.all(i, !has(i.image))) && (!has(self.filter.exclude) || self.filter.exclude.all(i, !has(i.image))))",message="spec.filter image items are not supported on ReplicatedImageSet; image selection is per-upstream via spec.upstreams[].imageFilter"
 type ReplicatedImageSetSpec struct {
 	ReplicatedImageSetBase `json:",inline"`
 
-	// Filter selects which pods and images this resource applies to. It
-	// replaces the deprecated imageFilter.
+	// Filter selects which pods this resource applies to (label and annotation
+	// dimensions). The image dimension is not supported here: image selection is
+	// per-upstream via spec.upstreams[].imageFilter.
 	// +optional
 	Filter Filter `json:"filter,omitempty"`
 }

config/crd/bases/kuik.enix.io_clusterreplicatedimagesets.yaml

@@ -45,8 +45,9 @@ spec:
             properties:
               filter:
                 description: |-
-                  Filter selects which pods, namespaces and images this resource applies
-                  to. It replaces the deprecated imageFilter.
+                  Filter selects which pods and namespaces this resource applies to (label,
+                  annotation and namespace dimensions). The image dimension is not supported
+                  here: image selection is per-upstream via spec.upstreams[].imageFilter.
                 properties:
                   exclude:
                     items:
@@ -193,6 +194,12 @@ spec:
                 maxItems: 32
                 type: array
             type: object
+            x-kubernetes-validations:
+            - message: spec.filter image items are not supported on ClusterReplicatedImageSet;
+                image selection is per-upstream via spec.upstreams[].imageFilter
+              rule: '!has(self.filter) || ((!has(self.filter.include) || self.filter.include.all(i,
+                !has(i.image))) && (!has(self.filter.exclude) || self.filter.exclude.all(i,
+                !has(i.image))))'
           status:
             description: ClusterReplicatedImageSetStatus defines the observed state
               of ClusterReplicatedImageSet.

config/crd/bases/kuik.enix.io_replicatedimagesets.yaml

@@ -44,8 +44,9 @@ spec:
             properties:
               filter:
                 description: |-
-                  Filter selects which pods and images this resource applies to. It
-                  replaces the deprecated imageFilter.
+                  Filter selects which pods this resource applies to (label and annotation
+                  dimensions). The image dimension is not supported here: image selection is
+                  per-upstream via spec.upstreams[].imageFilter.
                 properties:
                   exclude:
                     items:
@@ -188,6 +189,12 @@ spec:
                 maxItems: 32
                 type: array
             type: object
+            x-kubernetes-validations:
+            - message: spec.filter image items are not supported on ReplicatedImageSet;
+                image selection is per-upstream via spec.upstreams[].imageFilter
+              rule: '!has(self.filter) || ((!has(self.filter.include) || self.filter.include.all(i,
+                !has(i.image))) && (!has(self.filter.exclude) || self.filter.exclude.all(i,
+                !has(i.image))))'
           status:
             description: ReplicatedImageSetStatus defines the observed state of ReplicatedImageSet.
             type: object

helm/kube-image-keeper/crds/kuik.enix.io_clusterreplicatedimagesets.yaml

@@ -44,8 +44,9 @@ spec:
             properties:
               filter:
                 description: |-
-                  Filter selects which pods, namespaces and images this resource applies
-                  to. It replaces the deprecated imageFilter.
+                  Filter selects which pods and namespaces this resource applies to (label,
+                  annotation and namespace dimensions). The image dimension is not supported
+                  here: image selection is per-upstream via spec.upstreams[].imageFilter.
                 properties:
                   exclude:
                     items:
@@ -192,6 +193,12 @@ spec:
                 maxItems: 32
                 type: array
             type: object
+            x-kubernetes-validations:
+            - message: spec.filter image items are not supported on ClusterReplicatedImageSet;
+                image selection is per-upstream via spec.upstreams[].imageFilter
+              rule: '!has(self.filter) || ((!has(self.filter.include) || self.filter.include.all(i,
+                !has(i.image))) && (!has(self.filter.exclude) || self.filter.exclude.all(i,
+                !has(i.image))))'
           status:
             description: ClusterReplicatedImageSetStatus defines the observed state
               of ClusterReplicatedImageSet.

helm/kube-image-keeper/crds/kuik.enix.io_replicatedimagesets.yaml

@@ -43,8 +43,9 @@ spec:
             properties:
               filter:
                 description: |-
-                  Filter selects which pods and images this resource applies to. It
-                  replaces the deprecated imageFilter.
+                  Filter selects which pods this resource applies to (label and annotation
+                  dimensions). The image dimension is not supported here: image selection is
+                  per-upstream via spec.upstreams[].imageFilter.
                 properties:
                   exclude:
                     items:
@@ -187,6 +188,12 @@ spec:
                 maxItems: 32
                 type: array
             type: object
+            x-kubernetes-validations:
+            - message: spec.filter image items are not supported on ReplicatedImageSet;
+                image selection is per-upstream via spec.upstreams[].imageFilter
+              rule: '!has(self.filter) || ((!has(self.filter.include) || self.filter.include.all(i,
+                !has(i.image))) && (!has(self.filter.exclude) || self.filter.exclude.all(i,
+                !has(i.image))))'
           status:
             description: ReplicatedImageSetStatus defines the observed state of ReplicatedImageSet.
             type: object

internal/controller/kuik/mirror_reconciler_test.go

@@ -274,6 +274,36 @@ var _ = Describe("CRD admission validation", func() {
 		}
 		Expect(k8sClient.Create(ctx, ism)).To(MatchError(ContainSubstring("mutually exclusive")))
 	})
+
+	It("rejects an image item in a ReplicatedImageSet spec.filter (image selection is per-upstream)", func() {
+		ris := &kuikv1alpha1.ReplicatedImageSet{
+			ObjectMeta: metav1.ObjectMeta{Name: "ris-image-filter", Namespace: "default"},
+			Spec: kuikv1alpha1.ReplicatedImageSetSpec{
+				Filter: kuikv1alpha1.Filter{Include: []kuikv1alpha1.FilterItem{{Image: "nginx.*"}}},
+			},
+		}
+		Expect(k8sClient.Create(ctx, ris)).To(MatchError(ContainSubstring("image selection is per-upstream")))
+	})
+
+	It("rejects an image item in a ClusterReplicatedImageSet spec.filter", func() {
+		cris := &kuikv1alpha1.ClusterReplicatedImageSet{
+			ObjectMeta: metav1.ObjectMeta{Name: "cris-image-filter"},
+			Spec: kuikv1alpha1.ClusterReplicatedImageSetSpec{
+				Filter: kuikv1alpha1.ClusterFilter{Exclude: []kuikv1alpha1.ClusterFilterItem{{FilterItem: kuikv1alpha1.FilterItem{Image: "nginx.*"}}}},
+			},
+		}
+		Expect(k8sClient.Create(ctx, cris)).To(MatchError(ContainSubstring("image selection is per-upstream")))
+	})
+
+	It("accepts a label item in a ReplicatedImageSet spec.filter", func() {
+		ris := &kuikv1alpha1.ReplicatedImageSet{
+			ObjectMeta: metav1.ObjectMeta{Name: "ris-label-filter", Namespace: "default"},
+			Spec: kuikv1alpha1.ReplicatedImageSetSpec{
+				Filter: kuikv1alpha1.Filter{Include: []kuikv1alpha1.FilterItem{{Label: "app=foo"}}},
+			},
+		}
+		Expect(k8sClient.Create(ctx, ris)).To(Succeed())
+	})
 })
 
 // conflictOnFirstUpdateClient wraps a client.Client and returns a conflict

website/src/content/docs/crds.md

@@ -25,7 +25,7 @@ This is particularly useful for multi-homed projects (e.g., Thanos, Prometheus,
 | Field | Required | Description |
 | --- | --- | --- |
 | `spec.priority` | | Controls ordering of alternatives relative to the original image and other CRs. Negative values place alternatives before the original image; positive values place them after. Default is `0` (original image first). |
-| `spec.filter` | | Selects which pods and namespaces (cluster-scoped only) this resource applies to. The `image` dimension is **not** supported here and is **ignored**: image selection is done per-upstream via `spec.upstreams[].imageFilter`. See [Resource filtering](/resource-filtering/). |
+| `spec.filter` | | Selects which pods and namespaces (cluster-scoped only) this resource applies to. The `image` dimension is **not** supported here and an `image` item is **rejected at admission**: image selection is done per-upstream via `spec.upstreams[].imageFilter`. See [Resource filtering](/resource-filtering/). |
 | `spec.upstreams[]` | | List of upstream image sources that should be considered equivalent. |
 | `spec.upstreams[].registry` | ✅ | Registry where the upstream image is hosted (e.g. `docker.io`, `quay.io`). |
 | `spec.upstreams[].path` | ✅ | Path identifying the image in the registry (e.g. `/thanosio/thanos`). |

website/src/content/docs/resource-filtering.md

@@ -39,7 +39,7 @@ Items are grouped by dimension (all `image` items together, all `label` items to
 This makes the filter a faithful superset of the per-dimension filters it replaces: a resource applies to an `(pod, image)` pair when the image passes the image dimension, the namespace passes the namespace dimension, and the pod passes the label and annotation dimensions.
 
 :::note
-`(Cluster)ReplicatedImageSet` is the exception: it ignores the `image` dimension of `spec.filter` and selects images per-upstream instead. See [Per-upstream image filtering](#per-upstream-image-filtering-on-clusterreplicatedimageset).
+`(Cluster)ReplicatedImageSet` is the exception: it has no `image` dimension in `spec.filter` (an `image` item is rejected at admission) and selects images per-upstream instead. See [Per-upstream image filtering](#per-upstream-image-filtering-on-clusterreplicatedimageset).
 :::
 
 :::caution
@@ -71,7 +71,7 @@ The operator also exposes a cluster-wide skip list (`skipLabels` / `skipAnnotati
 
 `(Cluster)ReplicatedImageSet` selects images **per upstream** via `spec.upstreams[].imageFilter`, which chooses the images each upstream entry replicates. That field is unrelated to the deprecated top-level `imageFilter` below and is **not** affected by its deprecation.
 
-Because image selection is per-upstream, the **`image` dimension of the top-level `spec.filter` is not supported and is ignored** on `(Cluster)ReplicatedImageSet`: any `image` `include` / `exclude` items there have no effect. Only the `label`, `annotation` and (cluster-scoped) `namespace` dimensions of `spec.filter` apply, as a resource-wide pod / namespace gate.
+Because image selection is per-upstream, the **`image` dimension of the top-level `spec.filter` is not supported** on `(Cluster)ReplicatedImageSet`: an `image` `include` / `exclude` item is rejected at admission. Only the `label`, `annotation` and (cluster-scoped) `namespace` dimensions of `spec.filter` apply, as a resource-wide pod / namespace gate.
 
 ## Examples