Rate Limiting

KubeArchive protects the API server from overload using per-user rate limiting middleware. The middleware applies token-bucket limiters to control traffic:

  • Per-user overall rate limiter: token-bucket limiter applied to all API requests. Each user (identified by Impersonate-User header, Bearer token, or client IP) gets their own bucket with configurable requests-per-second (RPS) and burst capacity.

  • Per-user log rate limiter: token-bucket limiter applied only to log endpoints (/log). Each user gets their own bucket with tighter limits, since log retrieval is more resource-intensive.

When any limit is exceeded, the API server returns HTTP 429 (Too Many Requests) with a Retry-After header indicating when the client should retry.

There are four environment variables that control rate limiting behavior:

  • API_RATE_LIMIT_OVERALL_RPS: per-user overall requests per second (token refill rate). If not set, the default value is 100.

  • API_RATE_LIMIT_LOG_RPS: per-user log endpoint requests per second. If not set, the default value is 10.

  • API_RATE_LIMIT_OVERALL_BURST: per-user overall burst capacity (maximum tokens in bucket). If not set, the default value is 300.

  • API_RATE_LIMIT_LOG_BURST: per-user log endpoint burst capacity. If not set, the default value is 30.

All rate limiting values must be positive numbers. The RPS values can be decimal (e.g., 10.5). The burst values must be integers.

To modify rate limiting settings, perform the following steps:

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

    ---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: kubearchive-api-server
        env:
        - name: API_RATE_LIMIT_OVERALL_RPS
          value: "200"
        - name: API_RATE_LIMIT_LOG_RPS
          value: "20"
        - name: API_RATE_LIMIT_OVERALL_BURST
          value: "600"
        - name: API_RATE_LIMIT_LOG_BURST
          value: "60"

    If any value is not a positive number, the Deployment fails and does not start.

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

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