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 index aafb04fd83..d91ad53edd 100644 --- 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 new file mode 100644 index 0000000000..5ef021173f --- /dev/null +++ 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 index f2e3e5d1e0..20d0ea8b8a 100644 --- 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 new file mode 100644 index 0000000000..111d0d7489 --- /dev/null +++ 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 new file mode 100644 index 0000000000..8a123333cc --- /dev/null +++ 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