StatefulSet Headless Service Endpoint Mapper

Threat/Impact Level: HIGH | Downtime Risk: HIGH | Time to Fix: 5–10 mins

TL;DR

• What broke: The headless Service's spec.selector does not match the labels on the StatefulSet's spec.template.metadata.labels, so kube-proxy and the Endpoints controller register zero backing pods.
• How to fix it: Align the Service spec.selector labels exactly with the pod template labels in the StatefulSet. Verify with kubectl get endpoints my-service.
• Shortcut: Use our Client-Side Sandbox above to paste both YAMLs and auto-refactor the selector alignment without leaking your config to any third-party server.

$ kubectl get endpoints my-service
NAME         ENDPOINTS   AGE
my-service   <none>      8m

$ kubectl describe service my-service
....
Selector:          app=my-svc
Endpoints:         <none>

How to Fix It

Basic Fix — Align the Selector

The Service spec.selector must be a subset of the pod template labels. Every key-value pair in the selector must exist verbatim in spec.template.metadata.labels.

# headless-service.yaml
 apiVersion: v1
 kind: Service
 metadata:
   name: my-service
 spec:
   clusterIP: None
   selector:
-    app: my-svc
+    app: my-service
   ports:
     - port: 9042
       targetPort: 9042

# statefulset.yaml
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
   name: my-service
 spec:
   serviceName: "my-service"
   selector:
     matchLabels:
-      app: my-service-node
+      app: my-service
   template:
     metadata:
       labels:
-        app: my-service-node
+        app: my-service

Verify immediately:

# Endpoints should now list pod IPs
kubectl get endpoints my-service -n <namespace>

# Confirm pod labels match
kubectl get pods -l app=my-service -n <namespace>

# Test headless DNS resolution from within the cluster
kubectl run dns-test --image=busybox:1.36 --restart=Never -it --rm \
  -- nslookup my-service.<namespace>.svc.cluster.local

Enterprise Best Practice — Enforce Label Contracts with a Shared Label Schema

The root cause is label values being defined in two places with no single source of truth. Fix this structurally:

1. Use Helm named templates to stamp labels from one definition:

# _helpers.tpl
+{{- define "mychart.selectorLabels" -}}
+app.kubernetes.io/name: {{ .Chart.Name }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}

# service.yaml
 spec:
   selector:
-    app: my-svc
+    {{- include "mychart.selectorLabels" . | nindent 4 }}

# statefulset.yaml
 spec:
   selector:
     matchLabels:
-      app: my-service-node
+      {{- include "mychart.selectorLabels" . | nindent 6 }}
   template:
     metadata:
       labels:
-        app: my-service-node
+        {{- include "mychart.selectorLabels" . | nindent 8 }}

2. Use kubectl.kubernetes.io/last-applied-configuration diff in your CD pipeline to catch selector drift before apply.

3. Add a pre-deploy validation step:

# Dry-run apply and grep for endpoint readiness
kubectl apply --dry-run=server -f manifests/ \
  && kubectl get endpoints my-service -n staging | grep -v '<none>'

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

# policy/statefulset_service_selector.rego
package kubernetes.statefulset

deny[msg] {
  input.kind == "StatefulSet"
  svc := data.services[_]
  svc.spec.clusterIP == "None"
  svc.metadata.name == input.spec.serviceName
  key := svc.spec.selector[k]
  not input.spec.template.metadata.labels[k] == key
  msg := sprintf("Service selector key '%v' not found in StatefulSet pod template labels", [k])
}

conftest test manifests/ --policy policy/

checkov -d . --framework kubernetes --check CKV_K8S_43

# kustomization.yaml
commonLabels:
  app: my-service
  app.kubernetes.io/part-of: my-platform

# ArgoCD post-sync hook or Flux health check
kubectl wait --for=condition=Ready pod -l app=my-service -n production --timeout=120s \
  && kubectl get endpoints my-service -n production | grep -v '<none>' \
  || (echo "ENDPOINT CHECK FAILED" && exit 1)