Add docs for CRD field selection

jpbetz · jpbetz · commit 8c0a57a1e1f3 · 2024-03-18T11:09:04.000-04:00
diff --git a/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md b/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md
@@ -292,6 +292,50 @@ When you add a custom resource, you can access it using:
   (generating one is an advanced undertaking, but some projects may provide a client along with
   the CRD or AA).
 
+
+## Custom resource field selectors
+
+[Field Selectors](/docs/concepts/overview/working-with-objects/field-selectors/)
+let clients select custom resources based on the value of one or more resource
+fields.
+
+All custom resources support the `metadata.name` and `metadata.namespace` field
+selectors.
+
+Fields declared in a {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}}
+may also be used with field selectors when included in the `spec.versions[*].selectableFields` field of the
+{{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}}.
+
+### Selectable fields for custom resources {#crd-selectable-fields}
+
+{{< feature-state feature_gate_name="CustomResourceFieldSelectors" >}}
+
+You need to enable the `CustomResourceFieldSelectors`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to
+use this behavior, which then applies to all CustomResourceDefinitions in your
+cluster.
+
+The `spec.versions[*].selectableFields` field of a {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} may be used to
+declare which other fields in a custom resource may be used in field selectors.
+The following example adds the `.spec.color` and `.spec.size` fields as
+selectable fields.
+
+{{% code_sample file="customresourcedefinition/shirt-resource-definition.yaml" %}}
+
+Field selectors can then be used to get only resources with with a `color` of `blue`:
+
+```shell
+kubectl get shirts.stable.example.com --field-selector spec.color=blue
+```
+
+The output should be:
+
+```
+NAME       COLOR  SIZE
+example1   blue   S
+example2   blue   M
+```
+
 ## {{% heading "whatsnext" %}}
 
 * Learn how to [Extend the Kubernetes API with the aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).
diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/custom-resource-field-selectors.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/custom-resource-field-selectors.md
@@ -0,0 +1,16 @@
+---
+title: CustomResourceFieldSelectors
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.30"  
+---
+
+Enable `selectableFields` in the
+{{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} API to allow filtering
+of custom resource **list**, **watch** and **deletecollection** requests.
diff --git a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md
@@ -1624,6 +1624,96 @@ my-new-cron-object   * * * * *   1          7s
 The `NAME` column is implicit and does not need to be defined in the CustomResourceDefinition.
 {{< /note >}}
 
+### Field selectors
+
+[Field Selectors](/docs/concepts/overview/working-with-objects/field-selectors/)
+let clients select custom resources based on the value of one or more resource
+fields.
+
+All custom resources support the `metadata.name` and `metadata.namespace` field
+selectors.
+
+Fields declared in a {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}}
+may also be used with field selectors when included in the `spec.versions[*].selectableFields` field of the
+{{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}}.
+
+#### Selectable fields for custom resources {#crd-selectable-fields}
+
+{{< feature-state state="alpha" for_k8s_version="v1.30" >}}
+{{< feature-state feature_gate_name="CustomResourceFieldSelectors" >}}
+
+You need to enable the `CustomResourceFieldSelectors`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to
+use this behavior, which then applies to all CustomResourceDefinitions in your
+cluster.
+
+The `spec.versions[*].selectableFields` field of a {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} may be used to
+declare which other fields in a custom resource may be used in field selectors.
+The following example adds the `.spec.color` and `.spec.size` fields as
+selectable fields.
+
+Save the CustomResourceDefinition to `shirt-resource-definition.yaml`:
+
+{{% code_sample file="customresourcedefinition/shirt-resource-definition.yaml" %}}
+
+Create the CustomResourceDefinition:
+
+```shell
+kubectl apply -f https://k8s.io/examples/customresourcedefinition/shirt-resource-definition.yaml
+```
+
+Define some Shirts by editing `shirt-resources.yaml`; for example:
+
+{{% code_sample file="customresourcedefinition/shirt-resources.yaml" %}}
+
+Create the custom resources:
+
+```shell
+kubectl apply -f https://k8s.io/examples/customresourcedefinition/shirt-resources.yaml
+```
+
+Get all the resources:
+
+```shell
+kubectl get shirts.stable.example.com
+```
+
+The output is:
+
+```
+NAME       COLOR  SIZE
+example1   blue   S
+example2   blue   M
+example3   green  M
+```
+
+Fetch blue shirts (retrieve Shirts with a `color` of `blue`):
+
+```shell
+kubectl get shirts.stable.example.com --field-selector spec.color=blue
+```
+
+Should output:
+
+```
+NAME       COLOR  SIZE
+example1   blue   S
+example2   blue   M
+```
+
+Get only resources with a `color` of `green` and a `size` of `M`:
+
+```shell
+kubectl get shirts.stable.example.com --field-selector spec.color=green,spec.size=M
+```
+
+Should output:
+
+```
+NAME       COLOR  SIZE
+example2   blue   M
+```
+
 #### Priority
 
 Each column includes a `priority` field. Currently, the priority
diff --git a/content/en/examples/customresourcedefinition/shirt-resource-definition.yaml b/content/en/examples/customresourcedefinition/shirt-resource-definition.yaml
@@ -0,0 +1,36 @@
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: shirts.stable.example.com
+spec:
+  group: stable.example.com
+  scope: Namespaced
+  names:
+    plural: shirts
+    singular: shirt
+    kind: Shirt
+  versions:
+  - name: v1
+    served: true
+    storage: true
+    schema:
+      openAPIV3Schema:
+        type: object
+        properties:
+          spec:
+            type: object
+            properties:
+              color:
+                type: string
+              size:
+                type: string
+    selectableFields:
+    - jsonPath: .spec.color
+    - jsonPath: .spec.size
+    additionalPrinterColumns:
+    - jsonPath: .spec.color
+      name: Color
+      type: string
+    - jsonPath: .spec.size
+      name: Size
+      type: string
diff --git a/content/en/examples/customresourcedefinition/shirt-resources.yaml b/content/en/examples/customresourcedefinition/shirt-resources.yaml
@@ -0,0 +1,24 @@
+---
+apiVersion: stable.example.com/v1
+kind: Shirt
+metadata:
+  name: example1
+spec:
+  color: blue
+  size: S
+---
+apiVersion: stable.example.com/v1
+kind: Shirt
+metadata:
+  name: example2
+spec:
+  color: blue
+  size: M
+---
+apiVersion: stable.example.com/v1
+kind: Shirt
+metadata:
+  name: example3
+spec:
+  color: green
+  size: M
