Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new field selectors doc #9174

Merged
merged 3 commits into from
Jul 19, 2018
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
---
title: Field Selectors
weight: 60
---

_Field selectors_ enable you to [select Kubernetes resources](/docs/concepts/overview/working-with-objects/kubernetes-objects) on the basis of the value of one or more resource fields. Here are some example field selector queries:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From the style guide: use simple and direct language.

_Field selectors_ let you [select Kubernetes resources](/docs/concepts/overview/working-with-objects/kubernetes-objects) based on the value of one or more resource fields. Here are some sample field selector queries:

So:

Field selectors let you select Kubernetes resources based on the value of one or more resource fields. Here are some sample field selector queries:


* `metadata.name=my-service`
* `metadata.namespace!=default`
* `status.phase=Pending`

This `kubectl` command, for example, would select all Pods for which the value of the [`status.phase`](/docs/concepts/workloads/pods/pod-lifecycle/#pod-phase) field is `Running`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This `kubectl` command selects all Pods for which the value of the [`status.phase`](/docs/concepts/workloads/pods/pod-lifecycle/#pod-phase) field is `Running`:

So:

This kubectl command selects all Pods for which the value of the status.phase field is Running:


```shell
$ kubectl get pods --field-selector status.phase=Running
```

{{< note >}}
Field selectors are essentially resource *filters*. By default, no selectors/filters are applied, meaning that all resources of the specified type are selected. This makes the following `kubectl` queries equivalent:

```shell
$ kubectl get pods
$ kubectl get pods --field-selector ""
```
{{< /note >}}

## Supported fields

Which fields can be used with field selectors varies by Kubernetes resource type. *All* resource types do, however, support the `metadata.name` and `metadata.namespace` fields. If you attempt to use field selectors on a field that isn't supported for that resource, you will receive an error. Here's an example:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Supported field selectors vary by Kubernetes resource type. All resource types support the `metadata.name` and `metadata.namespace` fields. Using unsupported field selectors produces an error. For example:

So:

Supported field selectors vary by Kubernetes resource type. All resource types support the metadata.name and metadata.namespace fields. Using unsupported field selectors produces an error. For example:


```shell
$ kubectl get ingress --field-selector foo.bar=baz
Error from server (BadRequest): Unable to find "ingresses" that match label selector "", field selector "foo.bar=baz": "foo.bar" is not a known field selector: only "metadata.name", "metadata.namespace"
```

## Supported operators

The `!=` field selector operator is supported in addition to `=` (used in the example directly above). This `kubectl` command, for example, would select all Kubernetes Services that are not in the `default` namespace:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Avoid passive voice when possible.

You can use the `!=` and `=` operators with field selectors. For example, this `kubectl` command selects all Kubernetes Services that aren't in the `default` namespace:

So:

You can use the != and = operators with field selectors. For example, this kubectl command selects all Kubernetes Services that aren't in the default namespace:


```shell
$ kubectl get services --field-selector metadata.namespace!=default
```

{{< warning >}}
Please note that *only* the `=` and `!=` operators are supported as field selector operators. [Label selector](/docs/concepts/overview/working-with-objects/labels) syntax should *not* be taken as a general guide to field selector syntax. If you require more complex queries involving selectors like [`in` or `notin`](/docs/concepts/overview/working-with-objects/labels#set-based-requirement), you may be better served by label selectors.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this a warning? What, per the style guide, makes this information crucial and/or dangerous? Specify the consequences.

I'll hold further feedback on this sentence until you've addressed the bit above. ☝️

{{< /warning >}}

## Chained selectors

As with [label](/docs/concepts/overview/working-with-objects/labels) and other selectors, field selectors can be chained together as a comma-separated list. This `kubectl` command would select all Pods for which the `status.phase` does not equal `Running` *and* the `spec.restartPolicy` field equals `Always`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As with `[label](/docs/concepts/overview/working-with-objects/labels)` and other selectors, field selectors can be chained together as a comma-separated list. This `kubectl` command selects all Pods for which the `status.phase` does not equal `Running` and the `spec.restartPolicy` field equals `Always`:

So:

As with [label](/docs/concepts/overview/working-with-objects/labels) and other selectors, field selectors can be chained together as a comma-separated list. This kubectl command selects all Pods for which the status.phase does not equal Running and the spec.restartPolicy field equals Always:


```shell
$ kubectl get pods --field-selector=status.phase!=Running,spec.restartPolicy=Always
```

## Multiple resource types

Field selectors can be used to select across multiple resource types. This `kubectl` command would select all Statefulsets *and* Services that are not in the `default` namespace:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Avoid the passive voice.

You can use field selectors across multiple resource types. This `kubectl` command selects all Statefulsets and Services that are not in the `default` namespace:

So:

You can use field selectors across multiple resource types. This kubectl command selects all Statefulsets and Services that are not in the default namespace:


```shell
$ kubectl get statefulsets,services --field-selector metadata.namespace!=default
```