Add docs for CRD field selection
Joe Betz
parent
1f2b53a0ac
commit
8c0a57a1e1
|
|
@ -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/).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue