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.