Merge pull request #29740 from SergeyKanzhelev/grpcProbeDocsPlaceholder

gRPC probes support (KEP 2727)
2021-11-30 16:09:18 -08:00
parent 6a684469cb ef6668539c
commit f17f3884a2
4 changed files with 71 additions and 6 deletions
@@ -220,11 +220,57 @@ After 15 seconds, view Pod events to verify that liveness probes:
 kubectl describe pod goproxy
 ```

+## Define a gRPC liveness probe
+
+{{< feature-state for_k8s_version="v1.23" state="alpha" >}}
+
+If your application implements [gRPC Health Checking Protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md),
+kubelet can be configured to use it for application liveness checks.
+
+{{< codenew file="pods/probe/grpc-liveness.yaml">}}
+
+To use a gRPC probe, `port` must be configured. If the health endpoint is configured
+on a non-default service, `service` must be configured.
+
+{{< note >}}
+Unlike HTTP and TCP probes, named ports cannot be used and custom host cannot be configured.
+{{< /note >}}
+
+Configuration problems (e.g. incorrect port and service, unimplemented health checking protocol)
+are considered a probe failure, similar to HTTP and TCP probes.
+
+Before Kubernetes 1.23, gRPC health probes were often implemented using [grpc-health-probe](https://github.com/grpc-ecosystem/grpc-health-probe/),
+as described in the blog post [Health checking gRPC servers on Kubernetes](/blog/2018/10/01/health-checking-grpc-servers-on-kubernetes/).
+The built-in gRPC probes behavior is similar to one implemented by grpc-health-probe.
+When migrating from grpc-health-probe to built-in probes, remember the following differences:
+
+- Built-in probes will run against pod IP, unlike grpc-health-probe that often runs against `127.0.0.1`.
+  Be sure to configure your gRPC endpoint to listen for pod IP address.
+- Built-in probes do not currently support any authentication parameters (like `-tls`).
+- There are no error codes in built-in probes. All errors are considered as probe failures.
+- If `ExecProbeTimeout` feature gate is set to `false`, grpc-health-probe will NOT
+  respect `timeoutSeconds` setting (which defaults to 1s),
+  while built-in probe will fail on timeout.
+
+To try the gRPC liveness check, create a Pod using the command below.
+In the example below, etcd pod is configured to use gRPC liveness probe.
+
+
+```shell
+kubectl apply -f https://k8s.io/examples/pods/probe/content/en/examples/pods/probe/grpc-liveness.yaml
+```
+
+After 15 seconds, view Pod events to verify that the liveness probes has not failed:
+
+```shell
+kubectl describe pod etcd-with-grpc
+```
+
 ## Use a named port

 You can use a named
 [ContainerPort](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#containerport-v1-core)
-for HTTP or TCP liveness checks:
+for HTTP and TCP probes. Note, gRPC probe does not support named port.

 ```yaml
 ports:
@@ -349,7 +395,7 @@ This defect was corrected in Kubernetes v1.20. You may have been relying on the
 even without realizing it, as the default timeout is 1 second.
 As a cluster administrator, you can disable the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) `ExecProbeTimeout` (set it to `false`)
 on each kubelet to restore the  behavior from older versions, then remove that override
-once all the exec probes in the cluster have a `timeoutSeconds` value set.  
+once all the exec probes in the cluster have a `timeoutSeconds` value set.
 If you have pods that are impacted from the default 1 second timeout,
 you should update their probe timeout so that you're ready for the
 eventual removal of that feature gate.