External caches may be defined and used with the orchestrator to enable high availability.

Caches configuration options

Orchestrator only supports Redis 6.0 or greater.

Name

name defines how the cache is identified.

Type

type specifies which backend system the cache will use for storage, and determines the cache configuration options. Currently only caches of type redis are supported.

Keys

keys is the configuration block for controlling how cache keys are formatted.

DisablePrefix

disablePrefix is an optional boolean flag that can be set to true to disable the feature-specific prefix typically prepended to cache keys. This should be enabled when using Service Extensions to read and write data in a cache where the data is not owned by the Orchestrator. When disabled (default), cache keys are prefixed with the feature namespace (e.g., /app/oidc:abc123). When enabled, keys are stored without the prefix (e.g., abc123).

Encryption

encryption is the configuration block which defines the keys used for encrypting and decrypting the cache data. By default, the cache assumes that encryption will be used.

Disabled

disabled is a boolean flag which can be set to true to disable encrypting the cache data.

Keys

keys is the configuration block which defines the actively used encryption keys. The keys must be 32 bytes in hexadecimal format. They can be created using openssl like: openssl rand -hex 32.

Current

current defines the key which is actively being used to encrypt data to the cache.

Old

old defines an array of keys which were previously used in current, they allow non-current keys to still decrypt data from the cache which may have been encrypted while they were current.

Hashing

hashing is the configuration block used for controlling if certain data is hashed before being added to the cache. Presently, only hashing of the keys is done, and it is turned on by default.

Keys

keys is the configuration block for configuring if keys are hashed or not.

Disabled
`disabled` is an optional boolean flag which can be set to `true` to disable hashing the cache key. This can be useful for debugging.

Redis cache configuration options

Addresses

addresses a list of host:port addresses of cluster nodes.

TLS

tls is the name of the TLS configuration to use. Refer to the documentation about transport security to learn more.

Username

username is the username used to authenticate against Redis. The username must be generated via access control list (ACL) in Redis. This field is optional.

Password

password the user password used to authenticate against Redis. The password must be generated via access control list (ACL) in Redis. This field is optional.

Example Redis cache configuration


caches:
  - name: maverics-redis-cache
    type: redis
    redis:
      tls: redis-ca
      addresses:
        - redis1.example.com:6379
      username: redis-username
      password: <cache-redis-password>
    encryption:
      keys:
        current: '{{ env.CACHE_REDIS_ENCRYPTION_KEY_CURRENT }}'
        old:
          - '{{ env.CACHE_REDIS_ENCRYPTION_KEY_2022 }}'
          - '{{ env.CACHE_REDIS_ENCRYPTION_KEY_2021 }}'

Shared Redis Cache for External Data Integration

Use a shared Redis cache where data is written by an external system and consumed by the Orchestrator


caches:
  # Notice that `keys.disablePrefix` is set to true and `encryption.disabled` and `hashing.keys.disabled` are 
  # set true. This is required when reading data from a shared cache, since the data being written by the 
  # external system doesn't use the same key hashing or data encryption.
  - name: shared-redis
    type: redis
    redis:
      addresses:
        - redis1.example.com:6379
      username: redis-username
      password: <cache-redis-password>
    keys:
      disablePrefix: true
    encryption:
      disabled: true
    hashing:
      keys:
        disabled: true

Then in a Service Extension get the cache by the name you provided in the config and use the cache APIs for retrieving and setting data.


// Get the cache by the name you set in the config (e.g., "shared-redis").
cache, err := api.Cache("", cache.WithName("shared-redis"))
if err != nil {
	logger.Error("se", "unable to retrieve cache", "error", err.Error())
	return nil, err
}

// Get the raw data from the cache using the unique key.
data, err := cache.GetBytes(context.Background(), "my-unique-key")

// At this point, you'll typically unmarshal the data to a struct using JSON or whatever encoding your external 
// system used when writing to the cache.

v2025.11.1

New Features