github.com/projectcontour/contour@v1.28.2/site/content/docs/1.25/redeploy-envoy.md (about)

     1  # Redeploying Envoy
     2  
     3  The Envoy process, the data path component of Contour, at times needs to be re-deployed.
     4  This could be due to an upgrade, a change in configuration, or a node-failure forcing a redeployment.
     5  
     6  When implementing this roll out, the following steps should be taken:
     7  
     8  1. Stop Envoy from accepting new connections
     9  2. Start draining existing connections in Envoy by sending a `POST` request to `/healthcheck/fail` endpoint
    10  3. Wait for connections to drain before allowing Kubernetes to `SIGTERM` the pod
    11  
    12  ## Overview
    13  
    14  Contour implements an `envoy` sub-command named `shutdown-manager` whose job is to manage a single Envoy instances lifecycle for Kubernetes.
    15  The `shutdown-manager` runs as a new container alongside the Envoy container in the same pod.
    16  It uses a  Kubernetes `preStop` event hook to keep the Envoy container running while waiting for connections to drain. The `/shutdown` endpoint blocks until the connections are drained.
    17  
    18  ```yaml
    19   - name: shutdown-manager
    20     command:
    21     - /bin/contour
    22     args:
    23       - envoy
    24       - shutdown-manager
    25     image: ghcr.io/projectcontour/contour:main
    26     imagePullPolicy: Always
    27     lifecycle:
    28       preStop:
    29         exec:
    30           command:
    31             - /bin/contour
    32             - envoy
    33             - shutdown
    34  ```
    35  
    36  The Envoy container also has some configuration to implement the shutdown manager.
    37  First the `preStop` hook is configured to use the `/shutdown` endpoint which blocks the Envoy container from exiting.
    38  Finally, the pod's `terminationGracePeriodSeconds` is customized to extend the time in which Kubernetes will allow the pod to be in the `Terminating` state.
    39  The termination grace period defines an upper bound for long-lived sessions.
    40  If during shutdown, the connections aren't drained to the configured amount, the `terminationGracePeriodSeconds` will send a `SIGTERM` to the pod killing it.
    41  
    42  ![shutdown-manager overview][1]
    43  
    44  ### Shutdown Manager Config Options
    45  
    46  The `shutdown-manager` runs as another container in the Envoy pod.
    47  When the pod is requested to terminate, the `preStop` hook on the `shutdown-manager` executes the `contour envoy shutdown` command initiating the shutdown sequence.
    48  
    49  The shutdown manager has a single argument that can be passed to change how it behaves:
    50  
    51  | Name | Type | Default | Description |
    52  |------------|------|---------|-------------|
    53  | <nobr>serve-port</nobr> | integer | 8090 | Port to serve the http server on |
    54  | <nobr>ready-file</nobr> | string | /admin/ok | File to poll while waiting shutdown to be completed. |
    55  
    56  ### Shutdown Config Options
    57  
    58  The `shutdown` command does the work of draining connections from Envoy and polling for open connections.
    59  
    60  The shutdown command has a few arguments that can be passed to change how it behaves:
    61  
    62  | Name | Type | Default | Description |
    63  |------------|------|---------|-------------|
    64  | <nobr>check-interval</nobr> | duration | 5s | Time interval to poll Envoy for open connections. |
    65  | <nobr>check-delay</nobr> | duration | 0s | Time wait before polling Envoy for open connections. |
    66  | <nobr>drain-delay</nobr> | duration | 0s | Time wait before draining Envoy connections. |
    67  | <nobr>min-open-connections</nobr> | integer | 0 | Min number of open connections when polling Envoy. |
    68  | <nobr>admin-port (Deprecated)</nobr> | integer | 9001 | Deprecated: No longer used, Envoy admin interface runs as a unix socket.  |
    69  | <nobr>admin-address</nobr> | string | /admin/admin.sock | Path to Envoy admin unix domain socket. |
    70  | <nobr>ready-file</nobr> | string | /admin/ok | File to write when shutdown is completed. |
    71  
    72    [1]: ../img/shutdownmanager.png