Paste a selector and the objects it is supposed to match, and find out which of them match and which key failed on the ones that do not. A selector that matches nothing is a valid object: it applies cleanly, reports no error, and quietly does nothing, which is why this is worth checking from the manifest.
Or drop a file anywhere on this panel. Nothing is uploaded: the analysis runs in this tab.
The answer appears here
Paste on the left and press Test selectors. Nothing leaves this tab.
Nothing else to flag.
No formatting problems, and nothing the rules object to. Worth remembering what that covers: this reads the file you pasted, not the account or cluster it will be applied to.
No finding matches that filter.
Real input you can load into the tool above. Each one shows a different thing going wrong, because that is what the tool is for.
A selector that matches nothing, which is a Deployment that creates pods it does not own
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: webIn, NotIn and Exists evaluated against real labels
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
selector:
matchLabels:
app: api
matchExpressions:
- key: tier
operator: In
values: [backend]
template:
metadata:
labels:
app: api
tier: backendThese are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.
spec.selector is immutable. Changing it requires deleting and recreating the Deployment, which is downtime.
Instead:Choose it once. Put changeable metadata in non-selector labels.
A selector matching nothing creates pods the Deployment does not own, so it creates more forever.
Instead:They must agree. The selector must be a subset of the template labels.
A Service selector is equality-only and has no matchExpressions.
Instead:Keep Service selectors simple.
Selectors are read from a Deployment, StatefulSet, DaemonSet, ReplicaSet, Job, Service, PodDisruptionBudget or NetworkPolicy, from any pod spec's nodeSelector, or from a bare matchLabels and matchExpressions block pasted on its own. Objects to match against are Pods, the pod template of a workload, Nodes, Namespaces, or a plain labels map.
When a selector matches nothing, the objects are ranked by how much of the selector each one satisfied and the closest is named, with the requirement that broke it: tier is "backend" but the selector wants "web". Every requirement is ANDed, so one wrong key reads exactly the same as no match at all, and "no match" on its own is not an answer you can act on.
{} matches everything and an absent or null selector matches nothing, and they are one character apart in a diff. What that means depends on the field, so it is reported per field: an empty selector on a Deployment is rejected by the API server outright, an empty Service selector means no endpoints rather than every pod, and an empty PodDisruptionBudget selector selects the whole namespace in policy/v1 while the same YAML selected none in policy/v1beta1.
In and NotIn need at least one item in values. Exists and DoesNotExist need values to be empty, and the object is rejected rather than the extra values being ignored. Gt and Lt exist only in node affinity, and either one in a workload selector is a rejection, which is called out by name here rather than left as a message about an unknown operator. Keys and values are checked as qualified names too: one slash at most, a lowercase DNS subdomain prefix up to 253 characters, and 63 for the name part.
In requires the key to be present. NotIn and DoesNotExist are satisfied by an object that does not carry the key at all, so a set-based exclusion also catches everything unlabelled. That is what the Kubernetes matcher does, and it is not the reading most people give it. It is reported only when it actually decided a match, so it is never a lecture about a rule your input did not exercise.
A Service selector and a nodeSelector are map[string]string: flat, equality only, no wrapper. A workload spec.selector, a PodDisruptionBudget selector and a NetworkPolicy podSelector are a LabelSelector, with matchLabels and matchExpressions. Putting one where the other belongs fails while unmarshalling, with an error that names a Go type instead of your field, so that case is called out by name.
A workload selector is checked against its own pod template, which the API server rejects on apply and which is immutable afterwards. A selector satisfied by a workload's metadata.labels but not by its spec.template.metadata.labels is called out, because those two blocks are written to look identical and copying the wrong one is invisible in review. So is a workload selector that matches more than one pod set, which is how two controllers end up deleting each other's pods. And the case where the labels are right but the namespace is not: if the only object satisfying every requirement sits in another namespace, that is reported as critical, naming the object and the namespace it is in.
What a green verdict does not say: a match here is a match against the objects you pasted, not against everything in the namespace. The tool has no cluster to read, so it cannot know about the pod nobody put in the file, and it does not see the pod-template-hash label a ReplicaSet adds to the pods it creates. Selector keys and values are validated; the labels on the objects you paste are taken as given.
A label selector is a list of requirements evaluated against a map of key/value pairs. That is the whole model: no wildcards, no substring matching, no regular expressions, no OR. It is how a Deployment finds its pods, how a Service finds its endpoints, how a NetworkPolicy decides what it applies to. The failure mode that makes it worth a page is that a selector matching nothing is a perfectly valid object: it applies cleanly, reports no error, and quietly does nothing.
This is the first thing to get right, because the error message when you get it wrong is a Go unmarshalling failure that names a type rather than your field. Some fields are a flat map[string]string and take equality only. Others are a LabelSelector and take matchLabels, matchExpressions, or both. There is no field that accepts either form.
flat map[string]string, equality only
Service spec.selector
pod spec spec.nodeSelector
LabelSelector, matchLabels + matchExpressions
Deployment spec.selector
StatefulSet spec.selector
DaemonSet spec.selector
ReplicaSet spec.selector
PodDisruptionBudget spec.selector
NetworkPolicy spec.podSelectormatchLabels and matchExpressions are not two alternatives to choose between. They are flattened into one list of conditions and all of them must hold. Each entry inside matchExpressions is ANDed with the next one as well. An OR across labels does not exist in a label selector: node affinity gets one through nodeSelectorTerms, which are ORed, and that is a different type in a different field.
selector:
matchLabels:
app: api -> app In (api)
matchExpressions:
- key: tier
operator: In
values: [web] -> tier In (web)
matches only: app=api AND tier=web
a pod with app=api and tier=backend fails on
one key, and that is the same as no matchIn and NotIn compare against a list of values. Exists and DoesNotExist only ask about the key. The two validation rules are a pair because people remember that values is conditional and not which way round it goes: In and NotIn require at least one value, Exists and DoesNotExist require none. Node affinity adds Gt and Lt, which read the label value as an integer, and they are rejected in a plain LabelSelector.
In values must hold >= 1 item
NotIn values must hold >= 1 item
Exists values must be empty
DoesNotExist values must be empty
Gt, Lt node affinity only,
exactly one integer valueOn an object that carries the key they are opposites. On an object that does not carry it at all they are both false in the intuitive reading, and Kubernetes does not use the intuitive reading. In needs the key to be present, so it fails. NotIn is satisfied, because the value it excludes is not there. The consequence: a NotIn is also an implicit "or unlabelled", so an exclusion written to skip one tier also picks up every object nobody labelled.
selector: tier NotIn (web)
pod with tier=web no match
pod with tier=backend MATCH
pod with no tier label MATCH
to consider only labelled objects, AND an
Exists on the same key:
- key: tier
operator: Exists
- key: tier
operator: NotIn
values: [web]These are opposites and they are one character apart. The field being absent, or present and null, means no selector: it matches nothing. The field being present and empty means a selector with zero requirements, and a selector with zero requirements is satisfied by everything. Which of the two you want is a real decision, and an empty podSelector is exactly how a default-deny NetworkPolicy is written.
podSelector: {} every pod in the namespace
podSelector: no pods
(field absent) no pods
a Deployment is the exception: the API server
refuses an empty selector there rather than
letting the controller adopt every podThe API server checks a Deployment, StatefulSet, DaemonSet or ReplicaSet selector against spec.template.metadata.labels and rejects the object with "selector does not match template labels". After creation the selector is immutable, so an apply that changes it is rejected with a field-is-immutable error and the only way through is to delete and recreate the workload, which means the pods go away. Get it right before the first apply.
spec:
selector:
matchLabels: { app: api }
template:
metadata:
labels: { app: web } rejected
on a live Deployment, the fix is the template
labels or a replacement object, because the
selector cannot be editedA workload has metadata.labels on itself and spec.template.metadata.labels on its pods, and they are usually written with the same content. A selector matches pod labels. Copying the object's own block into a Service selector produces a Service with no endpoints, a valid manifest, and nothing anywhere that says which of the two you took.
kind: Deployment
metadata:
labels:
app: api <- the Deployment
spec:
template:
metadata:
labels:
app: api <- the pods
pod-template-hash: ... (added by the
controller)
a Service selector reads the second blockA selector on a namespaced object only considers objects in that object's own namespace, and there is no field that widens it. So a selector is only ever compared here against objects in the same namespace, and a Service in prod will not find the identically labelled pod in staging however carefully the labels were copied. That case is the reason a zero on its own is not an answer, so it is not left as one: when the only object satisfying every requirement is in another namespace, the report says which object and which namespace, and it is raised as critical rather than as a near miss, because nothing about the labels needs changing. A NetworkPolicy is the one place a second namespace enters the picture, through a separate namespaceSelector inside a rule, and even there the podSelector itself does not reach further. Nodes and Namespaces are cluster scoped, so a nodeSelector or a pasted selector is compared against all of them.
Service in prod, selector app=api
pod with app=api in staging
matches 0 of 0 objects in scope
out of scope: Pod/staging/p satisfies every
requirement, in namespace staging
the namespaces are the boundary, not a filter
you can turn off, so the fix is to move the
Service or to label something in prod