Database access

Everyone can access the Redis database with read-only privileges. The Redis user default (password is not important) can be used for this purpose.

To get write access a module must provide the Redis credentials stored in its agent.env file. The complete path is ~/.config/state/agent.env. Write access is restricted to Redis keys and channels with prefix module/{module_id}/*. The same credentials allow broad read access, also on private/agents/* namespace.

The above rules are already implemented by the Python agent module.

Access Redis in read-only:

import agent

rdb = agent.redis_connect(privileged=False)
somehash = rdb.hgetall('cluster/somehash')

Access Redis in read-write mode:

import agent

rdb = agent.redis_connect(privileged=True)
rdb.hset('module/myapp1/myhash', mapping={'myvar': 'myvalue'})

If Redis connection is required at service boot time, prefer connecting to the local replica. This avoids issues if the leader node is unreachable.

import agent

rdb = agent.redis_connect(use_replica=True)
cluster_network = rdb.get('cluster/network')

Any additional keyword argument supported by the installed Redis Python library’s redis.Redis() constructor can be passed to agent.redis_connect(). These arguments are forwarded to the Redis client and can configure options such as socket timeouts, retries, TLS, database selection, and response decoding.

rdb = agent.redis_connect(
    use_replica=True,
    socket_timeout=10,
    socket_connect_timeout=5,
)

decode_responses is one of these additional arguments. Redis responses are decoded from UTF-8 to strings by default. Consumers that need to validate or process each Redis bulk string independently can request the original bytes:

import agent

raw_rdb = agent.redis_connect(
    use_replica=True,
    decode_responses=False,
)
for key in raw_rdb.scan_iter('cluster/*'):
    raw_hash = raw_rdb.hgetall(key)
    # key, raw_hash field names, and raw_hash values are bytes