Configure caching¶

Caching is enabled by default using an in-memory, process-local backend. Enabling Valkey or external Redis changes where cached entries are stored; it does not enable a previously disabled cache.

Choose a backend¶

Keep the default in-memory cache for development, small deployments, or a single server process. It avoids an extra service and network round trips. Each worker has its own entries, which are lost when that process restarts.

Use Valkey or Redis when multiple workers or replicas repeatedly retrieve the same job packages or workflow metadata, or when you want those entries to survive server-process restarts for their remaining TTL. A shared backend can reduce duplicate GitLab reads and packaging work across server instances. It is an optimization, not a requirement for sharing job state: the application database already provides that state.

Consider the tradeoff before enabling a shared backend: it adds network latency, credentials, monitoring, and a service dependency. Cache connection errors can fail API requests; the server does not automatically fall back to in-memory caching when Redis is unavailable. Monitor cache availability and latency along with the server.

Configure a shared backend through Helm¶

Enable the chart's embedded Valkey with valkey.enabled: true, or use an existing Redis-compatible service. Replace the example hostname and Secret references with your service settings; the Secret must contain the named password key.

valkey:
  enabled: false
externalRedis:
  enabled: true
  host: redis.example.com
  port: 6379
  existingSecret: antflow-cache
  existingSecretPasswordKey: password
configs:
  cache:
    ttl: 60
  redis:
    db: 0
    timeout: 1
    pool_max_size: 10
    create_connection_timeout: 1

Choose one shared backend. The chart selects the Redis cache implementation and sets its endpoint automatically when either option is enabled. The timeout values are in seconds. Embedded Valkey authentication is disabled by default; restrict network access, and enable valkey.auth.enabled with valkey.auth.usersExistingSecret for password authentication. For ACL Secret keys and cache values, see the Helm chart reference.

What is cached¶

The server caches selected authentication data and derived workflow metadata to avoid repeated identity-provider requests, GitLab reads, and CWL packaging:

The default TTL is 60 seconds, so signing keys are cached for 1440 seconds (24 minutes). Workflow packages requested without a job ID are not cached by the package endpoint.

What is not cached¶

This cache is not the job queue or the authoritative application store:

• Job records, statuses, queue assignments, launcher registrations, and published project records remain in PostgreSQL. Database query results are not cached by this mechanism.
• Workflow outputs, logs, and static STAC files remain in object storage; the server cache does not store their contents.
• Project search results and project detail responses are not cached by the server's application cache.
• Workflow execution results are not reused to skip subsequent runs. This cache is not a runner-level execution cache.

Freshness and security¶

Increase configs.cache.ttl only when fewer upstream requests are worth slower refreshes of cached data. Personal token and secret changes can remain unseen until the relevant entries expire. Group claims also depend on the identity provider issuing a refreshed access token; expiring the server cache alone does not update those claims. Signing-key rotation may take the longer JWKS lifetime to be reflected.

Treat the cache as sensitive: entries can contain resolved GitLab tokens and launcher package environment values. Restrict access to trusted server instances, use authentication for shared backends, and do not expose the cache publicly. Cache storage is temporary and does not replace database, bucket, or encryption key backups.