From d591f7e3bc84eb5ab1c523ff6e0a4b182fbba65a Mon Sep 17 00:00:00 2001 From: Andrew Sy Kim Date: Tue, 24 Nov 2020 21:37:28 -0500 Subject: [PATCH] add docs for EndpointSlice conditions Signed-off-by: Andrew Sy Kim --- .../services-networking/endpoint-slices.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/content/en/docs/concepts/services-networking/endpoint-slices.md b/content/en/docs/concepts/services-networking/endpoint-slices.md index 11b788a0ca..6abf1f6ed1 100644 --- a/content/en/docs/concepts/services-networking/endpoint-slices.md +++ b/content/en/docs/concepts/services-networking/endpoint-slices.md @@ -93,6 +93,46 @@ EndpointSlices support three address types: * IPv6 * FQDN (Fully Qualified Domain Name) +### Conditions + +The EndpointSlice API stores conditions about endpoints that may be useful for consumers. +The three conditions are `ready`, `serving`, and `terminating`. + +#### Ready + +`ready` is a condition that maps to a Pod's `Ready` condition. A running Pod with the `Ready` +condition set to `True` should have this EndpointSlice condition also set to `true`. For +compatibility reasons, `ready` is NEVER `true` when a Pod is terminating. Consumers should refer +to the `serving` condition to inspect the readiness of terminating Pods. The only exception to +this rule is for Services with `spec.publishNotReadyAddresses` set to `true`. Endpoints for these +Services will always have the `ready` condition set to `true`. + +#### Serving + +{{< feature-state for_k8s_version="v1.20" state="alpha" >}} + +`serving` is identical to the `ready` condition, except it does not account for terminating states. +Consumers of the EndpointSlice API should check this condition if they care about pod readiness while +the pod is also terminating. + +{{< note >}} + +Although `serving` is almost identical to `ready`, it was added to prevent break the existing meaning +of `ready`. It may be unexpected for existing clients if `ready` could be `true` for terminating +endpoints, since historically terminating endpoints were never included in the Endpoints or +EndpointSlice API to begin with. For this reason, `ready` is _always_ `false` for terminating +endpoints, and a new condition `serving` was added in v1.20 so that clients can track readiness +for terminating pods independent of the existing semantics for `ready`. + +{{< /note >}} + +#### Terminating + +{{< feature-state for_k8s_version="v1.20" state="alpha" >}} + +`Terminating` is a condition that indicates whether an endpoint is terminating. +For pods, this is any pod that has a deletion timestamp set. + ### Topology information {#topology} {{< feature-state for_k8s_version="v1.20" state="deprecated" >}}