(The Readiness Probe Trap) #

In K8S, you should never feel safe just because kubectl get pods shows a Pod as Running.
That only means “the container exists and is running”, not “it is ready to receive traffic.”

---

Symptom: Look for Running (0/1) #

The first thing to check is the READY column.

kubectl get pods -n <namespace>

NAME        READY   STATUS    RESTARTS
app-pod     0/1     Running   0

If the STATUS is Running but READY is 0/1?
That means the container is running, but Kubernetes has decided “this thing is not ready yet” and has removed it from the Service endpoints.
Naturally, you won’t be able to connect.

---

Finding the Cause: describe and debug #

To see why the Pod is not ready, check the events with describe.

kubectl describe pod <pod-name> -n <namespace>

If you see “Readiness probe failed” in the Events section, that’s your answer.

If you want to inspect the internal state of the app but the image has no sh, ps, or other basic tools (for example, a Distroless image), attach a temporary debug container like this.

To run the debug command, you need the container name.
You can find the container name from the describe output above.

kubectl debug -it <pod-name> -n <namespace> \
  --image=nicolaka/netshoot --target=<container-name>

After attaching:

ss -lntp   # Check whether the app is actually listening on the port and bound to 0.0.0.0

You can also inspect process and network state using commands like:

ps, curl, ip a, ip route, ip neigh,
nslookup, dig, printenv, df -h,
free -m, getent hosts

Distroless images contain only the application binary and its runtime dependencies.
Shells and basic utilities are intentionally removed.
This improves security, but for troubleshooting, kubectl debug becomes essential.

---

Fix: Adjust the Probe Configuration #

In most cases, this happens because the application startup time is longer than the probe configuration allows.
Increase initialDelaySeconds or fix the health check path.

First, find which controller created the Pod:

kubectl get pod <pod-name> -n <namespace> \
  -o jsonpath='{.metadata.ownerReferences[0].kind}{" "}{.metadata.ownerReferences[0].name}{"\n"}'

This usually returns a ReplicaSet, and in most cases the original source is a Deployment.
(It could be a StatefulSet, but we’ll assume a Deployment here.)

Trace ReplicaSet → Deployment:

kubectl get rs -n <namespace> | grep <replicaset-name>

Edit the resulting Deployment:

kubectl edit deploy <deploy-name> -n <namespace>

Example:

readinessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 30  # Give the application enough time to start

---

Summary #

• Check whether the Pod shows 0/1 in kubectl get pods
• Use describe to confirm Readiness probe failed
• Adjust initialDelaySeconds based on application startup time
• Running describes the container state, not the service readiness

🛠 마지막 수정일: 2025.12.22