Deployment

Follow the instructions below to enable and configure the distributed cache feature.

Enable distributed cache

In the deployment configuration file, under distributedCache set the value of the enabled property to true.

distributedCache: 

  enabled: true  # Required
  
  ## Optional ##
  port: 9091     
  mode: "REPL_ASYNC" or "REPL_SYNC"     
  clusterName: "axio-cache-cluster" 
  discoveryMethod: "multicast" or "dns"
 ## if set to "dns" then: ##
 ## dnsQuery: <point to a DNS service that provides A/SRV records of the ADS instances>

Distributed caching sample.

Optional properties

This is a list of all configurable properties for the distributed caching feature in the deployment configuration file.

note

In case you don't configure one or more of the optional properties then their default values will be used.

Property	Description
port	Specifies the port number used for communication within the distributed cache cluster. The default is 7800.
mode	Determines the replication mode for the distributed cache. It can be set to either REPL_ASYNC for asynchronous replication or REPL_SYNC for synchronous replication. Synchronous mode is recommended for data consistency, while asynchronous mode can be used when prioritizing speed. The default is REPL_ASYNC.
clusterName	The unique identifier of your cache cluster. The default is axio-cache-cluster. NOTE: All ADS instances that participate in the same cache cluster should have the same clusterName.
cacheStateLocation	Manages the caching of cluster state metadata, enabling the storage of this data on each node and defining an absolute path in the local file system for storing that information. For more information refer to Cache state persistency.
discoveryMethod	Specifies the discovery method used for cache cluster formation. See Discovery method configuration below for details. The default is multicast. NOTE: The discoveryMethod property has replaced the stack property that was previously supported in ADS 1.13.0, with options tcp or kubernetes. However, stack property is still supported.

Discovery method configuration

The discoveryMethod configuration property specifies the underlying mechanism used by a node to identify other members of the cluster. ADS supports the following discoveryMethod options:

• multicast

  This is the combination of IP Multicast for cluster discovery and the TCP protocol for intra-cluster communication after cluster discovery.

• dns

  This is the combination of DNS query for cluster discovery and the TCP protocol for intra-cluster communication after cluster discovery. When the discoveryMethod property is set to dns, another configuration parameter called dnsQuery is also needed.

  info

  When using Helm charts provided by Axiomatics, dnsQuery value is generated by the cluster name. You can overwrite the provided value by setting your own.

See more information in the Final steps of the deployment using Kubernetes section.

important

In case that you disable the distributed cache feature, that is to set the enabled property to false, then make sure that the discoveryMethod and dnsQuery sub-properties are not set.

Cache state persistency

Cache state persistency is an optional feature that allows the internal state of the distributed cache cluster to be preserved, improving performance during application restarts.

This optional feature is activated by configuring the cacheStateLocation property under the distributedCache section and manages the caching of cluster state metadata, enabling the storage of this data on each node. Please note that the behavior the cacheStateLocation property varies based on your deployment, as detailed below.

note

When the cacheStateLocation property is disabled, the application will start with a WARN message indicating that the global cache has not been defined. This has no impact on the functionality within the ADS distributed cache topology and can therefore be ignored without any risk.

Kubernetes deployment:

For Kubernetes deployments, the cacheStateLocation is enabled by default and set to an emptyDir on the pod. This can be customized by specifying the absolute path to a writable directory for data storage.

You can disable this feature in Kubernetes by removing cacheStateLocation in the adscharts/configuration/deployment.yaml.

JAR deployment:

For JAR deployments, the cacheStateLocation feature is only enabled when the property is added in the deployment YAML and set to a custom location. If the cacheStateLocation property is not set, the feature is disabled. The custom location must be writable.

Important

The service should have both write and read permissions for the specified location and this location should not be shared among multiple instances.

Encrypt cluster communication

Optionally, you can use TLS (Transport Layer Security) or SSL (Secure Sockets Layer) encryption with distributed caching to significantly enhance the security of data exchanged between caching nodes and to further increase overall security. To use SSL/TLS encryption you have to configure a keystore that contains public and private keys.

note

The TLS option is not supported for Kubernetes deployments.

1. Create or import a keystore that contains your public and private keys.

   The keystore should be in a format that your system supports, such as PKCS#12 (Public Key Cryptography Standard #12).

2. In the distributedCache section of the ADS deployment file, create a new subsection named tls .

3. In the tls subsection, add the following properties and set their values accordingly:

   • keyStorePath
   • keyStorePassword
   • keyStoreType

distributedCache: 

  enabled: true
  port: 9091
  mode: "REPL_ASYNC" or "REPL_SYNC"
  clusterName: "axio-cache-cluster"
  discoveryMethod: "multicast"
  tls: 

    keyStorePath: file:<path_to_file>/server_keystore.p12
    keyStorePassword: <your_keystore_password>
    keyStoreType: PKCS12

Distributed caching with TLS enabled.

Important

While TLS is not required for distributed caching, all tls properties are required if you enable it.