9.17 Kubernetes Readiness Gate Behavior

Kubernetes Readiness Gate Behavior is the mechanism that extends a Pod's readiness determination beyond the built-in ContainersReady condition by allowing external controllers to inject their own custom conditions into the Pod's status, which must also evaluate to true before the Pod's overall Ready condition can become true, enabling readiness to depend on signals outside the Pod's own containers.

Purpose and Motivating Scenario

Readiness Dependent on External State

Standard container readiness probes can only observe what is directly checkable from within or against the container itself, but some architectures require a Pod's readiness to depend on external state, such as whether a service mesh sidecar has finished registering the Pod with a control plane, or whether an external load balancer has confirmed the Pod as a healthy backend.

Extending Rather Than Replacing Standard Readiness

Readiness gates do not replace the standard ContainersReady condition derived from container-level readiness probes; instead, they add additional required conditions on top of it, meaning both the standard container readiness and every declared readiness gate condition must be satisfied for the Pod to be marked ready.

Configuration Through readinessGates

Declaring Custom Conditions

The readinessGates field on a Pod specification lists one or more conditionType values, each referencing a condition type that some external controller is expected to set on the Pod's status, distinguishing these from the standard, built-in condition types Kubernetes manages automatically.

External Controller Responsibility

Because Kubernetes itself has no built-in knowledge of what these custom condition types represent, an external controller, typically part of the platform or service mesh being integrated, is responsible for watching the Pod and setting the corresponding condition to True once its own criteria have been satisfied.

Effect on Pod Readiness Aggregation

All Conditions Must Be True

The Pod's overall Ready condition is computed by requiring that ContainersReady is true and that every condition type listed in readinessGates also currently has a status of True; if any listed condition is missing, False, or Unknown, the Pod as a whole is considered not ready regardless of how healthy its containers otherwise appear.

Blocking Effect on Traffic and Rollouts

Because Service endpoint inclusion and Deployment rollout progress both depend on the aggregate Ready condition, a readiness gate that never transitions to true will permanently prevent the Pod from receiving traffic and will stall any rolling update relying on that Pod becoming ready, even if every container inside it is functioning perfectly.

Common Integration Patterns

Service Mesh Sidecar Injection

A frequently cited use case involves a service mesh injecting a sidecar proxy alongside the main application container and using a readiness gate to ensure the Pod is not considered ready until the sidecar has successfully registered itself with the mesh's control plane, preventing traffic from reaching the Pod before the mesh's routing and security policies are actually in effect.

External Load Balancer Health Confirmation

Another pattern uses a readiness gate to hold a Pod out of service until an external load balancer or ingress controller has explicitly confirmed the Pod as a healthy backend, coordinating Kubernetes-native readiness with the state of infrastructure that exists outside the cluster's own control plane.

Operational Considerations

Diagnosing Stuck Readiness

When a Pod appears to have healthy, passing container readiness probes yet remains marked as not ready, inspecting the Pod's full condition list for any readiness gate conditions still reporting False or missing entirely is a necessary diagnostic step, since this state is invisible if only container-level readiness is examined.

Dependency on Correctly Functioning External Controllers

Since readiness gates rely entirely on an external controller to set the corresponding condition, any malfunction, delay, or misconfiguration in that controller directly and silently affects Pod readiness from the perspective of Kubernetes itself, making the health of the gate-setting controller an implicit dependency of the Pod's own readiness.