Configure caching

Policy evaluation often requires retrieving attribute values from external sources using Attribute Connectors. Caching those values reduces the number of external calls and improves authorization response times.

ADS supports two caching modes:

• Local caching: attribute values are cached on the individual ADS instance.
• Distributed caching: attribute values are shared across a cluster of ADS instances.

Cache configuration is defined per attribute in domain.yaml under the attributeCache sub-section. If no attributeCache section exists in domain.yaml, ADS does not cache any attributes.

note

To cache an attribute, declare it in both the domain dictionary and the attributeCache configuration section of domain.yaml. This applies to custom attribute connectors as well.

tip

When ADS runs in ads_caq mode, both the ADS core service and CAQ share a single cache.

For more information on configuring attribute caching in your domain file, see the Authorization Domain Manager (ADM) documentationOpens in a new tab.

Distributed caching

Distributed caching shares cached attribute values across multiple ADS instances in a cluster. Enable it in deployment.yaml or through Helm during a Kubernetes deployment.

Enable distributed caching

Add the distributedCache section to deployment.yaml and set enabled to true:

distributedCache:
  enabled: true

  ## Optional properties ##
  port: 9091
  mode: "REPL_ASYNC"
  clusterName: "axio-cache-cluster"
  discoveryMethod: "multicast"
  ## If discoveryMethod is "dns": ##
  ## dnsQuery: <DNS service providing A/SRV records for ADS instances>

Distributed cache properties

Property	Description	Default
enabled	Set to true to enable distributed caching.	-
port	Port used for intra-cluster communication.	7800
mode	Replication mode. See Replication modes below.	REPL_ASYNC
clusterName	Unique name for the cache cluster. All ADS instances that share a cache must use the same clusterName.	axio-cache-cluster
discoveryMethod	Method used to discover other cluster members. multicast or dns.	multicast
dnsQuery	DNS query used to resolve cluster members. Required when discoveryMethod is dns.	-
cacheStateLocation	Absolute path for storing cluster state metadata on the local file system. See Cache state persistency.	-

Replication modes

The mode property controls how cache writes are replicated to other cluster nodes:

• REPL_ASYNC: Changes replicate in the background. Writes are fast, but cluster nodes may briefly see different cache states. Use this mode when write throughput matters more than strict consistency.
• REPL_SYNC: Changes replicate before the write completes. Cluster nodes are always consistent, but writes are slower. Use this mode in production environments where data consistency is critical.

Cluster discovery

ADS uses the discoveryMethod property to find other nodes in the cache cluster.

IP Multicast (default)

Multicast sends UDP messages to all nodes in the network. This is the default and requires no additional configuration. Be aware of potential network overhead with large numbers of nodes.

note

Multicast can work in Kubernetes but is generally less efficient due to network configuration constraints. Use DNS discovery for Kubernetes deployments.

DNS query

DNS discovery queries DNS Address (A) or Service (SRV) records to find cluster members. This is the recommended method for Kubernetes deployments, where headless services automatically generate the required DNS records.

distributedCache:
  enabled: true
  discoveryMethod: dns
  dnsQuery: <DNS service providing A/SRV records for ADS instances>

info

When using Axiomatics Helm charts, dnsQuery is generated automatically from the cluster name. You can override it by setting your own value.

caution

When enabled is set to false, do not set discoveryMethod or dnsQuery. Remove or comment out those properties.

Cache state persistency

Cache state persistency preserves the internal state of the distributed cache cluster across application restarts. When active, ADS stores cluster state metadata to the local file system, which reduces startup time and warm-up overhead.

Configure this feature using the cacheStateLocation property under distributedCache.

Kubernetes deployment: cacheStateLocation is enabled by default and set to an emptyDir on the pod. To use a custom path, set it to an absolute writable directory path. To disable the feature, remove cacheStateLocation from adscharts/configuration/deployment.yaml.

JAR deployment: The feature is only enabled when cacheStateLocation is explicitly set to a custom writable path. If the property is absent, the feature is disabled.

note

When cacheStateLocation is not set, ADS logs a WARN message at startup indicating the global cache has not been defined. This does not affect distributed cache functionality and can safely be ignored.

caution

The ADS process must have read and write permissions on the specified directory. Do not share this location among multiple ADS instances.

Encrypt cluster communication

Secure intra-cluster communication using TLS/SSL. To enable encryption, configure a tls subsection under distributedCache:

distributedCache:
  enabled: true
  port: 9091
  mode: "REPL_SYNC"
  clusterName: "axio-cache-cluster"
  discoveryMethod: "multicast"
  tls:
    keyStorePath: file:<path_to_file>/server_keystore.p12
    keyStorePassword: ${KEYSTORE_PASSWORD}
    keyStoreType: PKCS12

All three tls properties are required when TLS is enabled.

note

TLS for distributed cache communication is not supported in Kubernetes deployments.

Cache configuration override

Cache configuration override lets you override the attributeCache settings from domain.yaml without modifying the domain file. This is useful when promoting an identical domain configuration across different environments (dev, test, production), or when you want to temporarily disable caching during testing.

This feature is disabled by default. Enable it by adding the attributeConnectors.cacheOverride section to deployment.yaml:

attributeConnectors:
  cacheOverride:
    ttl: 2 seconds
    maxItems: 50

Cache override properties

Property	Description
ttl	Time To Live: maximum duration a cached item remains valid. Format: integer + time unit (s/second/seconds, m/min/minute/minutes, h/hour/hours, d/day/days).
maxItems	Maximum number of attribute values to cache per attribute. When full, the Least Recently Used (LRU) item is evicted. Minimum: 0.

note

Cache configuration override applies the same values to all attributes provided by all attribute connectors.

caution

When using distributed caching across multiple ADS instances, the cacheOverride configuration must be identical on all instances.

Common override patterns

Disable caching without changing the domain file:

attributeConnectors:
  cacheOverride:
    ttl: 0 seconds
    maxItems: 0

Enable caching without changing the domain file:

attributeConnectors:
  cacheOverride:
    ttl: 2 seconds
    maxItems: 50

Adjust existing cache values:

attributeConnectors:
  cacheOverride:
    ttl: 5 seconds
    maxItems: 100