Database Query Timeout

KubeArchive can enforce a timeout on database read queries to prevent long-running statements from exhausting database connections. When a query exceeds the configured timeout the API returns HTTP 504 Gateway Timeout to the client and the database statement is cancelled.

The timeout is controlled by the KUBEARCHIVE_QUERY_TIMEOUT environment variable. If not set, the default value is 5 minutes.

The value must be parseable by time.ParseDuration (for example 30s, 2m, 10m). If the value is invalid or negative the API server logs a warning and falls back to the default.

To modify the timeout, perform the following steps:

  1. Edit or patch the kubearchive-api-server Deployment in the kubearchive namespace:

    ---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: kubearchive-api-server
        env:
        - name: KUBEARCHIVE_QUERY_TIMEOUT
          value: 10m

  2. Save the patch somewhere on disk and apply it:

    kubectl patch -n kubearchive deployment kubearchive-api-server --patch-file path/to/patch.yaml

Affected endpoints

The timeout applies to every database read issued by the API server:

  • Collection queries (GET /apis/…​/resourceType)

  • Single-resource queries by name (GET /apis/…​/resourceType/name)

  • Single-resource queries by UID (GET /apis/…​/resourceType/uid/uid)

  • Resource count queries (?count=true)

  • Log URL queries (GET …​/log)

For streaming responses (collection queries that return multiple resources), timeout covers both query execution and resource collection iteration time, this should be taken into account when configuring the timeout for namespaces which produce a large amounts of resources.

Disabling the timeout

Setting KUBEARCHIVE_QUERY_TIMEOUT to 0 disables the timeout entirely. In this configuration every query runs until it completes or the client disconnects.

Running without a query timeout is not recommended in production. Without a timeout, a single expensive query (for example a full table scan triggered by a broad label selector) can hold a database connection indefinitely, potentially exhausting the connection pool.

Error responses

When a query exceeds the timeout the API returns:

{"message": "context deadline exceeded: query timeout: context deadline exceeded"}

with HTTP status 504 Gateway Timeout. Clients can retry the request with narrower filters (namespace, label selector, timestamp range) to reduce query execution time.