diff --git a/site/content/en/latest/tasks/operations/graceful-shutdown.md b/site/content/en/latest/tasks/operations/graceful-shutdown.md new file mode 100644 index 0000000000..3f6bc08f20 --- /dev/null +++ b/site/content/en/latest/tasks/operations/graceful-shutdown.md @@ -0,0 +1,91 @@ +--- +title: "Graceful Shutdown and Hitless Upgrades" +--- + +Envoy Gateway enables zero-downtime deployments through graceful connection draining during pod termination. + +## Overview + +The shutdown manager sidecar coordinates graceful connection draining during pod termination, providing: + +- Zero-downtime rolling updates +- Configurable drain timeouts +- Automatic health check failure to remove pods from load balancer rotation + +### Shutdown Process + +1. Kubernetes sends SIGTERM to the pod +2. Shutdown manager fails health checks via `/healthcheck/fail` + - This causes Kubernetes readiness probes to fail + - External load balancers and services stop routing new traffic to the pod + - Existing connections continue to be served while draining +3. Connection monitoring begins, polling `server.total_connections` +4. Process exits when connections reach zero or drain timeout is exceeded + +## Configuration + +Graceful shutdown behavior includes default values that can be overridden using the EnvoyProxy resource. The EnvoyProxy resource can be referenced in two ways: +1. **Gateway-level**: Referenced from a Gateway via `infrastructure.parametersRef` +2. **GatewayClass-level**: Referenced from a GatewayClass via `parametersRef` + +**Default Values:** +- `drainTimeout`: 60 seconds - Maximum time for connection draining +- `minDrainDuration`: 10 seconds - Minimum wait before allowing exit + +{{< tabpane text=true >}} +{{% tab header="Gateway-Level Configuration" %}} + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: eg +spec: + gatewayClassName: eg + infrastructure: + parametersRef: + group: gateway.envoyproxy.io + kind: EnvoyProxy + name: graceful-shutdown-config + listeners: + - name: http + port: 80 + protocol: HTTP +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyProxy +metadata: + name: graceful-shutdown-config +spec: + shutdown: + drainTimeout: "90s" # Override default 60s + minDrainDuration: "15s" # Override default 10s +``` + +{{% /tab %}} +{{% tab header="GatewayClass-Level Configuration" %}} + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: eg +spec: + controllerName: gateway.envoyproxy.io/gatewayclass-controller + parametersRef: + group: gateway.envoyproxy.io + kind: EnvoyProxy + name: graceful-shutdown-config +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyProxy +metadata: + name: graceful-shutdown-config +spec: + shutdown: + drainTimeout: "90s" # Override default 60s + minDrainDuration: "15s" # Override default 10s +``` + +{{% /tab %}} +{{< /tabpane >}}