Merge pull request #51789 from majiayu000/45927-doc-healthcheck-timeout-kill

docs: document healthcheck timeout termination behavior

api/swagger.yaml

@@ -838,7 +838,9 @@ definitions:
           Value: "UUID2"
 
   HealthConfig:
-    description: "A test to perform to check that the container is healthy."
+    description: |
+      A test to perform to check that the container is healthy.
+      Healthcheck commands should be side-effect free.
     type: "object"
     properties:
       Test:
@@ -849,6 +851,12 @@ definitions:
           - `["NONE"]` disable healthcheck
           - `["CMD", args...]` exec arguments directly
           - `["CMD-SHELL", command]` run command with system's default shell
+
+          A non-zero exit code indicates a failed healthcheck:
+          - `0` healthy
+          - `1` unhealthy
+          - `2` reserved (treated as unhealthy)
+          - other values: error running probe
         type: "array"
         items:
           type: "string"
@@ -862,6 +870,10 @@ definitions:
         description: |
           The time to wait before considering the check to have hung. It should
           be 0 or at least 1000000 (1 ms). 0 means inherit.
+
+          If the health check command does not complete within this timeout,
+          the check is considered failed and the health check process is
+          forcibly terminated without a graceful shutdown.
         type: "integer"
         format: "int64"
       Retries: