When you run Tableau Bridge on Linux in containers or clusters, use the draining feature to finish active extract refreshes before stopping the client.

Draining is optional. Turn it on in the Bridge client configuration. When draining is enabled, stopping the container gracefully tells the client to complete current published data source extract work and then shut down, up to a time limit you set. A force stop (for example, docker kill or a SIGKILL) does not drain. It stops the process immediately.

When draining is enabled and you issue a graceful stop command, the client enters the draining state and immediately stops accepting, queuing, or scheduling any new extract refresh tasks. The client continues processing all published data source extract refreshes that are currently in progress or already sitting in the queue. If all running and queued refreshes finish before the timeout, the Bridge process exits right away. If the timeout is reached first, Bridge stops waiting and exits. The refreshes that were still running at that point do not complete, and Tableau Cloud shows them as failed so you can rerun them. To avoid incomplete refreshes at shutdown, set the timeout to be longer than your longest typical refresh.

For general information about managing Bridge clients and pools, see Manage Pools. For client issues, see Troubleshoot Tableau Bridge Client Issues.

Prerequisites

Draining a Bridge Linux client requires:

• Running the Bridge Linux client on the machine or container image.

• Having write access to the client configuration JSON file (TabBridgeClientConfiguration.txt, located in the client's Configuration folder).

• Stopping the container or pod via your container runtime or orchestrator (for example, docker stop, podman stop, or Kubernetes pod deletion or scale-down).

• Setting a container stop timeout (grace period) that exceeds your configured draining timeout. It is recommended to exceed the draining timeout by a few minutes to prevent interrupted refreshes. If the grace period is shorter than drainingTimeOutInSeconds, the runtime force-stops the container before draining finishes and any running refreshes are cancelled.

Drain the client

Step 1: Turn on draining and set a timeout

1. Open the Bridge Linux client configuration file (TabBridgeClientConfiguration.txt) for your deployment.

2. Add or edit a drainingSettings object.

   • Set enableDraining to true.

   • Set drainingTimeOutInSeconds to the maximum time in seconds that the client can spend draining before it exits. Allowed values are 60 through 14400 (1 minute through 4 hours). Values below 60 seconds are automatically adjusted to 60 seconds. Values above 14400 seconds (4 hours) are automatically adjusted to 14400 seconds. A warning is logged when this adjustment occurs.

3. Save the file.

4. Restart or redeploy the Bridge client.

Example

{
"drainingSettings": {
"enableDraining": true,
"drainingTimeOutInSeconds": 1800
}
}

Default value when the feature is not configured:

Setting	Default
enableDraining	false (draining off)
drainingTimeOutInSeconds	1,800 (30 minutes)

Step 2: Stop the client to start draining

Draining starts when the Bridge process receives a SIGTERM or SIGINT signal. Commands such as docker stop, podman stop, and Kubernetes pod deletion send SIGTERM for you. If you run Bridge directly on a host instead of in a container, send SIGTERM to the Bridge process directly to trigger draining.

Note: Forced terminations (such as docker kill, kill -9, or setting a grace period of 0) send a SIGKILL signal. SIGKILL cannot be handled by the application, which bypasses draining and immediately cancels running extract refreshes.

Default orchestrator grace periods are short, therefore, you must explicitly increase them to exceed your drainingTimeOutInSeconds. The recommendation is to increase by a few minutes to allow for clean exit after the last job finishes:

• Docker or Podman: Pass the --time <seconds> flag (default is 10 seconds).

• Kubernetes: Set terminationGracePeriodSeconds in the pod specification (default is 30 seconds).

Step 3: Verify draining execution

To verify that draining is successful, use one of these methods:

• Client Logs: Check TabBridgeClientConfiguration.txt log output for these entries:

  • enableDraining=true; beginning graceful drain: Confirms that draining started. If you see enableDraining=false instead, the setting was not applied and Bridge stopped immediately without draining.

  • BridgeDrainMetrics: outcome=natural: Indicates that every job finished before the timeout and the process exited cleanly.

  • BridgeDrainMetrics: outcome=wait_elapsed: Indicates that the timeout was reached before all jobs finished. Any refreshes still running at that point didn't complete.

  Also, check for any logged warnings about automatic timeout adjustments if your configured drainingTimeOutInSeconds was outside the allowed range.

• Bridge Status: Review the Jobs page or Bridge Extracts in Tableau Cloud to verify that in-flight jobs completed before the client shut down. Jobs that did not complete before exit appear as failed and can be rerun manually.

For troubleshooting draining, see Troubleshooting Draining Issues.