salt.cache.redis_cache module

Redis

Redis plugin for the Salt caching subsystem.

New in version 2017.7.0.

As Redis provides a simple mechanism for very fast key-value store, in order to privde the necessary features for the Salt caching subsystem, the following conventions are used:

  • a Redis key consists of the bank name and the cache key separated by /, e.g.:

$KEY_minions/alpha/stuff where minions/alpha is the bank name and stuff is the key name. - as the caching subsystem is organised as a tree, we need to store the caching path and identify the bank and its offspring. At the same time, Redis is linear and we need to avoid doing keys <pattern> which is very inefficient as it goes through all the keys on the remote Redis server. Instead, each bank hierarchy has a Redis SET associated which stores the list of sub-banks. By default, these keys begin with $BANK_. - in addition, each key name is stored in a separate SET of all the keys within a bank. By default, these SETs begin with $BANKEYS_.

For example, to store the key my-key under the bank root-bank/sub-bank/leaf-bank, the following hierarchy will be built:

127.0.0.1:6379> SMEMBERS $BANK_root-bank
1) "sub-bank"
127.0.0.1:6379> SMEMBERS $BANK_root-bank/sub-bank
1) "leaf-bank"
127.0.0.1:6379> SMEMBERS $BANKEYS_root-bank/sub-bank/leaf-bank
1) "my-key"
127.0.0.1:6379> GET $KEY_root-bank/sub-bank/leaf-bank/my-key
"my-value"

There are three types of keys stored:

  • $BANK_* is a Redis SET containing the list of banks under the current bank
  • $BANKEYS_* is a Redis SET containing the list of keys under the current bank
  • $KEY_* keeps the value of the key

These prefixes and the separator can be adjusted using the configuration options:

bank_prefix: $BANK
The prefix used for the name of the Redis key storing the list of sub-banks.
bank_keys_prefix: $BANKEYS
The prefix used for the name of the Redis keyt storing the list of keys under a certain bank.
key_prefix: $KEY
The prefix of the Redis keys having the value of the keys to be cached under a certain bank.
separator: _
The separator between the prefix and the key body.

The connection details can be specified using:

host: localhost
The hostname of the Redis server.
port: 6379
The Redis server port.
db: '0'

The database index.

Note

The database index must be specified as string not as integer value!

password:
Redis connection password.

Configuration Example:

salt.cache.redis_cache.contains(bank, key)

Checks if the specified bank contains the specified key.

salt.cache.redis_cache.fetch(bank, key)

Fetch data from the Redis cache.

salt.cache.redis_cache.flush(bank, key=None)

Remove the key from the cache bank with all the key content. If no key is specified, remove the entire bank with all keys and sub-banks inside. This function is using the Redis pipelining for best performance. However, when removing a whole bank, in order to re-create the tree, there are a couple of requests made. In total:

  • one for node in the hierarchy sub-tree, starting from the bank node
  • one pipelined request to get the keys under all banks in the sub-tree
  • one pipeline request to remove the corresponding keys

This is not quite optimal, as if we need to flush a bank having a very long list of sub-banks, the number of requests to build the sub-tree may grow quite big.

An improvement for this would be loading a custom Lua script in the Redis instance of the user (using the register_script feature) and call it whenever we flush. This script would only need to build this sub-tree causing problems. It can be added later and the behaviour should not change as the user needs to explicitely allow Salt inject scripts in their Redis instance.

salt.cache.redis_cache.list(bank)

Lists entries stored in the specified bank.

salt.cache.redis_cache.store(bank, key, data)

Store the data in a Redis key.