From 9317dcfff033fe04ad407c6939949eabc4ecfc85 Mon Sep 17 00:00:00 2001
From: Luc Perkins <lucperkins@gmail.com>
Date: Wed, 18 Jul 2018 17:39:42 -0700
Subject: [PATCH] Add new field selectors doc (#9174)

* Add new field selectors doc

* Address wording issues and remove warning

* add note on = and ==

Signed-off-by: lucperkins <lucperkins@gmail.com>
---
 .../working-with-objects/field-selectors.md   | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 content/en/docs/concepts/overview/working-with-objects/field-selectors.md

diff --git a/content/en/docs/concepts/overview/working-with-objects/field-selectors.md b/content/en/docs/concepts/overview/working-with-objects/field-selectors.md
new file mode 100644
index 00000000000..243eecce24d
--- /dev/null
+++ b/content/en/docs/concepts/overview/working-with-objects/field-selectors.md
@@ -0,0 +1,58 @@
+---
+title: Field Selectors
+weight: 60
+---
+
+_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 example field selector queries:
+
+* `metadata.name=my-service`
+* `metadata.namespace!=default`
+* `status.phase=Pending`
+
+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`:
+
+```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
+
+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
+
+You can use the `=`, `==`, and `!=` operators with field selectors (`=` and `==` mean the same thing). This `kubectl` command, for example, selects all Kubernetes Services that aren't in the `default` namespace:
+
+```shell
+$ kubectl get services --field-selector metadata.namespace!=default
+```
+
+## 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 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
+
+You 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
+```