# Copyright 2025 Chris Croome
#
# This file is part of the Webarchitects Valkey Ansible role.
#
# The Webarchitects Valkey Ansible role is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
#
# The Webarchitects Valkey Ansible role is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along with the Webarchitects Valkey Ansible role. If not, see <https://www.gnu.org/licenses/>.
---
argument_specs:
main:
author: Chris Croome
description: Ansible role for installing and configuring nftables on Debian.
short_description: The main entry point for the Valkey role.
options:
valkey:
type: bool
required: true
description: Run the tasks in this role.
valkey_apt_backports:
type: str
required: true
description: String that will be present in the apt cache policy when backports are enabled.
valkey_instances:
type: list
elements: dict
required: true
description: A list of Valkey instances and their configuration.
options:
name:
type: str
required: true
description: The Valkey instance name.
config_file:
type: str
required: true
description: The path to the valkey instance configuration file.
state:
type: str
required: true
choices:
- absent
- enabled
description: The state of the Valkey instance.
config:
type: dict
required: false
description: A dictionary of keys and values for the Valkey configuration.
options:
include:
type: list
elements: str
description: Include one or more other config files.
required: false
loadmodule:
type: list
elements: str
description: Load modules at startup.
required: false
bind:
type: str
required: false
description: One or more IP addresses that the instance should bind to, each address can be prefixed by "-", which means that the server will not fail to start if the address is not available.
bind_source_addr:
type: str
required: false
description: Configure a specific address to bind to.
protected_mode:
type: bool
required: false
description: When protected mode is on and the default user has no password, the server only accepts local connections from the IPv4 address (127.0.0.1), IPv6 address (::1) or Unix domain sockets.
tcp_backlog:
type: int
required: false
description: In high requests-per-second environments you need a high backlog in order to avoid slow clients connection issues.
enable_protected_configs:
type: str
choices:
- "local"
- "no"
- "yes"
required: false
description: Enable protected configs.
enable_debug_command:
type: str
choices:
- "local"
- "no"
- "yes"
required: false
description: Enable debug command.
enable_module_command:
type: str
choices:
- "local"
- "no"
- "yes"
required: false
description: Enable module command.
port:
type: list
elements: int
required: true
description: A list of port numbers to accept connections on, the default is 6379. If port 0 is specified the server will not listen on a TCP socket.
unixsocket:
type: str
required: false
description: The path for the Unix socket that will be used to listen for incoming connections. There is no default, so the server will not listen on a unix socket when not specified.
unixsocketgroup:
type: str
required: false
description: UNIX socket group.
unixsocketperm:
type: int
required: false
description: The Unix socket octal permissions, default 700.
socket_mark_id:
type: int
required: false
description: The ID represents a connection mark. The default value is 0, which implies no marking is required.
tls_port:
type: str
required: false
description: TLS port.
tls_cert_file:
type: str
required: false
description: TLS cert file.
tls_key_file:
type: str
required: false
description: TLS key file.
tls_key_file_pass:
type: str
required: false
description: TLS key file password.
tls_client_cert_file:
type: str
required: false
description: TLS client cert file.
tls_client_key_file:
type: str
required: false
description: TLS client key file.
tls_client_key_file_pass:
type: str
required: false
description: TLS client key file password.
tls_dh_params_file:
type: str
required: false
description: TLS DH params file.
tls_ca_cert_file:
type: str
required: false
description: TLS CA cert file.
tls_ca_cert_dir:
type: str
required: false
description: TLS CA cert dirextory.
tls_auth_clients:
type: str
choices:
- "no"
- "optional"
required: false
description: TLS auth clients.
tls_replication:
type: bool
required: false
description: TLS replications.
tls_cluster:
type: bool
required: false
description: TLS cluster.
tls_protocols:
type: str
required: false
description: TLS protocols.
tls_ciphers:
type: str
required: false
description: TLS ciphers.
tls_ciphersuites:
type: str
required: false
description: TLS cipher suites.
tls_prefer_server_ciphers:
type: bool
required: false
description: TLS prefer server ciphers.
tls_session_caching:
type: bool
required: false
description: TLS session caching.
tls_session_cache_size:
type: int
required: false
description: TLS session cache size.
tls_session_cache_timeout:
type: int
required: false
description: TLS session cache timeout.
timeout:
type: int
required: false
description: Close the connection after a client is idle for N seconds (0 to disable).
tcp_keepalive:
type: int
required: false
description: On Linux, the specified value (in seconds) is the period used to send ACKs.
daemonize:
type: bool
required: false
description: When the server is supervised by upstart or systemd, this parameter has no impact.
dbfilename:
type: str
required: false
description: The filename where to dump the DB.
loglevel:
type: str
choices:
- debug
- nothing
- notice
- verbose
- warning
required: false
description: The loglevel.
logfile:
type: str
required: false
description: The log file path.
syslog_enabled:
type: bool
required: false
description: Enable logging to the system logger.
syslog_ident:
type: str
required: false
description: The syslog identity.
syslog_facility:
type: str
choices:
- user
- local0
- local1
- local2
- local3
- local4
- local5
- local6
- local7
crash_log_enabled:
type: bool
required: false
description: Disable the built in crash log.
crash_memcheck_enabled:
type: bool
required: false
description: Disable the fast memory check that's run as part of the crash log.
databases:
type: int
required: false
description: Set the number of databases.
always_show_logo:
type: bool
required: false
description: Show a ASCII art logo in startup logs.
hide_user_data_from_log:
type: bool
required: false
description: Prevent sensitive user information, such as PII, from being recorded in the server log file.
set_proc_title:
type: bool
required: false
description: Leave the process name as executed.
proc_title_template:
type: str
required: false
description: Process title template.
locale_collate:
type: str
required: false
description: Set the local environment which is used for string comparison operations. Empty String indicates the locale is derived from the environment variables.
extended_redis_compatibility:
type: bool
required: false
description: Extended Redis OSS compatibility mode makes Valkey pretend to be Redis.
save:
type: str
required: false
description: Save the DB to disk.
stop_writes_on_bgsave_error:
type: bool
required: false
description: By default the server will stop accepting writes if RDB snapshots are enabled (at least one save point) and the latest background save failed.
rdbcompression:
type: bool
required: false
description: Compress string objects using LZF when dump .rdb databases?
rdbchecksum:
type: bool
required: false
description: Since version 5 of RDB a CRC64 checksum is placed at the end of the file.
sanitize_dump_payload:
type: str
choices:
- "clients"
- "no"
- "yes"
required: false
description: Enables or disables full sanitization checks for ziplist and listpack etc.
rdb_del_sync_files:
type: bool
required: false
description: Remove RDB files used by replication in instances without persistence enabled.
dir:
type: str
required: false
description: The DB will be written inside this directory, with the filename specified using the 'dbfilename' configuration directive.
replicaof:
type: str
required: false
description: Use replicaof to make a server a copy of another server.
primaryauth:
type: str
required: false
description: If the primary is password protected (using the "requirepass" configuration directive) it is possible to tell the replica to authenticate before starting the replication synchronization process, otherwise the primary will refuse the replica request.
primaryuser:
type: str
required: false
description: When primaryuser is specified, the replica will authenticate against its primary using the new AUTH form, AUTH <username> <password>.
replica_serve_stale_data:
type: bool
required: false
description: When a replica loses its connection with the primary, or when the replication is still in progress, the replica can act in two different ways.
replica_read_only:
type: bool
required: false
description: Read only replicas are not designed to be exposed to untrusted clients on the internet.
repl_diskless_sync:
type: bool
required: false
description: With slow disks and fast (large bandwidth) networks, diskless replication works better.
repl_diskless_load:
type: str
choices:
- disabled
- on-empty-db
- swapdb
required: false
description: Replica load mode.
dual_channel_replication_enabled:
type: bool
required: false
description: Dual channel replication sync.
repl_ping_replica_period:
type: int
required: false
description: Master send PINGs to its replicas in a predefined interval.
repl_timeout:
type: int
required: false
description: Replication timeout.
repl_disable_tcp_nodelay:
type: bool
required: false
description: Disable TCP_NODELAY on the replica socket after SYNC?
repl_backlog_size:
type: str
required: false
description: The replication backlog size.
repl_backlog_ttl:
type: int
required: false
description: The amount of seconds that need to elapse, starting from the time the last replica disconnected, for the backlog buffer to be freed.
replica_priority:
type: int
required: false
description: The replica priority is an integer number published by the server in the INFO output.
propagation_error_behavior:
type: str
choices:
- ignore
- panic
- panic-on-replicas
required: false
description: The propagation error behavior.
replica_announced:
type: bool
required: false
description: Exclude replica from Sentinel's announcements.
min_replicas_to_write:
type: int
required: false
description: By default min-replicas-to-write is set to 0 (feature disabled).
min_replicas_max_lag:
type: int
required: false
description: By default min-replicas-max-lag is set to 10.
replica_announce_ip:
type: str
required: false
description: IP address to be used by a replica for the "INFO replication" section and in the output of the "ROLE" command of a primary.
replica_announce_port:
type: int
required: false
description: Port to be used by a replica for the "INFO replication" section and in the output of the "ROLE" command of a primary.
tracking_table_max_keys:
type: int
required: false
description: If you set the value to 0, it means there are no limits, and the server will retain as many keys as needed in the invalidation table.
user:
type: list
elements: str
required: false
description: A list of ACL users and rules.
acllog_max_len:
type: int
required: false
description: Maximum entry length of the ACL Log.
aclfile:
type: str
required: false
description: External ACL file.
requirepass:
type: str
required: false
description: The instance default password.
acl_pubsub_default:
type: str
choices:
- allchannels
- resetchannels
required: false
description: Pub/Sub channels permission for new users.
rename_command:
type: list
elements: str
required: false
description: Deprecated option to change the name of dangerous commands.
maxclients:
type: int
required: false
description: The max number of connected clients at the same time, By default this limit is set to 10000 clients, however if the server is not able to configure the process file limit to allow for the specified limit the max number of allowed clients is set to the current file limit minus 32 (as the server reserves a few file descriptors for internal uses).
maxmemory:
type: int
required: false
description: Memory usage limit in bytes.
maxmemory_policy:
type: str
choices:
- allkeys-lfu
- allkeys-lru
- allkeys-random
- noeviction
- volatile-lfu
- volatile-lru
- volatile-random
- volatile-ttl
required: false
description: How the server will select what to remove when maxmemory is reached, the default is noeviction.
maxmemory_samples:
type: int
choices:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
required: false
description: The default of 5 produces good enough results. 10 Approximates very closely true LRU but costs more CPU. 3 is faster but not very accurate. The maximum value that can be set is 64.
maxmemory_eviction_tenacity:
type: int
choices:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
- 69
- 70
- 71
- 72
- 73
- 74
- 75
- 76
- 77
- 78
- 79
- 80
- 81
- 82
- 83
- 84
- 85
- 86
- 87
- 88
- 89
- 90
- 91
- 92
- 93
- 94
- 95
- 96
- 97
- 98
- 99
- 100
required: false
description: Default 10, If there is an unusually large amount of write traffic, this value may need to be increased.
replica_ignore_maxmemory:
type: bool
required: false
description: By default a replica will ignore its maxmemory setting.
active_expire_effort:
type: int
choices:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
required: false
description: It is possible to increase the expire effort that is normally set to 1, to a greater value, up to the value 10.
lazyfree_lazy_eviction:
type: bool
required: false
description: Lazyfree lazy eviction, the default value is yes.
lazyfree_lazy_expire:
type: bool
required: false
description: Lazyfree lazy expire, the default value is yes.
lazyfree_lazy_server_del:
type: bool
required: false
description: Lazyfree lazy server delete, the default value is yes.
replica_lazy_flush:
type: bool
required: false
description: Lazyfree lazy flush, the default value is yes.
lazyfree_lazy_user_del:
type: bool
required: false
description: Lazyfree lazy user delete, the default value is yes.
lazyfree_lazy_user_flush:
type: bool
required: false
description: Lazyfree lazy user flush, the default value is yes.
io_threads:
type: int
required: false
description: By default threading is disabled, enable only on machines that have at least 3 or more cores, leaving at least one spare core.
prefetch_batch_max_size:
type: int
required: false
description: The default batch size is 16, when set to 0, prefetching is disabled.
oom_score_adj:
type: str
choices:
- "no"
- "yes"
- absolute
- relative
required: false
description: The default is no, yes is the same as relative, with absolute oom-score-adj-values are written as is to the kernel.
oom_score_adj_values:
type: str
required: false
description: When oom-score-adj is used, this controls the specific values used for primary, replica and background child processes.
disable_thp:
type: bool
required: false
description: Usually the kernel Transparent Huge Pages control is set to madvise or or never by default, if you prefer to keep it enabled, you can set this config to no and the kernel global to always.
appendonly:
type: bool
required: false
description: The Append Only File is an alternative persistence mode that provides much better durability. Note that changing this value in a config file of an existing database and restarting the server can lead to data loss.
appendfilename:
type: str
required: false
description: The base name of the append only file. The default is appendonly.aof.
appenddirname:
type: str
required: false
description: The name of the directory for all persistent append-only files. Default appendonlydir.
appendfsync:
type: str
choices:
- always
- everysec
- "no"
description: The fsync() call tells the Operating System to actually write data on disk instead of waiting for more data in the output buffer. The default is everysec.
no_appendfsync_on_rewrite:
type: bool
required: false
description: When the AOF fsync policy is set to always or everysec, and a background saving process (a background save or AOF log background rewriting) is performing a lot of I/O against the disk, in some Linux configurations the server may block too long on the fsync() call. The default is no.
auto_aof_rewrite_percentage:
type: int
choices:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
- 69
- 70
- 71
- 72
- 73
- 74
- 75
- 76
- 77
- 78
- 79
- 80
- 81
- 82
- 83
- 84
- 85
- 86
- 87
- 88
- 89
- 90
- 91
- 92
- 93
- 94
- 95
- 96
- 97
- 98
- 99
- 100
required: false
description: The server is able to automatically rewrite the log file implicitly calling BGREWRITEAOF when the AOF log size grows by the specified percentage. Specify a percentage of zero in order to disable the automatic AOF rewrite feature.
auto_aof_rewrite_min_size:
type: str
required: false
description: A minimal size for the AOF file to be rewritten, this is useful to avoid rewriting the AOF file even if the percentage increase is reached but it is still pretty small.
aof_load_truncated:
type: bool
required: false
description: An AOF file may be found to be truncated at the end during the server startup process, either exit with an error when this happens, or load as much data as possible, The default is yes.
aof_use_rdb_preamble:
type: bool
required: false
description: The server can create append-only base files in either RDB or AOF formats. Using the RDB format is always faster and more efficient, the default is yes.
aof_timestamp_enabled:
type: bool
required: false
description: The server supports recording timestamp annotations in the AOF to support restoring the data from a specific point-in-time. However, using this capability changes the AOF format in a way that may not be compatible with existing AOF parsers. The default is no.
shutdown_timeout:
type: int
required: false
description: Maximum time to wait for replicas when shutting down, in seconds.
shutdown_on_sigint:
type: str
required: false
description: When the server receives a SIGINT shutdown is initiated. Options are Any combination of 'default', 'save', 'nosave', 'now' and 'force' as long as 'save' and 'nosave' are not set simultaneously.
shutdown_on_sigterm:
type: str
required: false
description: When the server receives a SIGTERM shutdown is initiated. Options are any combination of 'default', 'save', 'nosave', 'now' and 'force' as long as 'save' and 'nosave' are not set simultaneously.
lua_time_limit:
type: int
required: false
description: Maximum time in milliseconds for EVAL scripts, default 5000, set it to 0 to disable this mechanism (uninterrupted execution).
busy_reply_threshold:
type: int
required: false
description: Alias for lua-time-limit.
cluster_enabled:
type: bool
required: false
description: Normal server instances can't be part of a cluster; only nodes that are started as cluster nodes can. The default is false.
cluster_config_file:
type: str
required: false
description: Every cluster node has a cluster configuration file. Every cluster node requires a different cluster configuration file. Make sure that instances running in the same system do not have overlapping cluster configuration file names.
cluster_node_timeout:
type: int
required: false
description: Cluster node timeout is the amount of milliseconds a node must be unreachable for it to be considered in failure state.
cluster_port:
type: int
required: false
description: The cluster port is the port that the cluster bus will listen for inbound connections on. When set to the default value, 0, it will be bound to the command port + 10000. Setting this value requires you to specify the cluster bus port when executing cluster meet.
cluster_replica_validity_factor:
type: int
required: false
description: A replica of a failing primary will avoid to start a failover if its data looks too old. The default is 10.
cluster_migration_barrier:
type: int
required: false
description: Default is 1 (replicas migrate only if their primaries remain with at least one replica). To disable migration just set it to a very large value or set cluster-allow-replica-migration to 'no'. A value of 0 can be set but is useful only for debugging and dangerous in production.
cluster_allow_replica_migration:
type: bool
required: false
description: Turning off this option allows to use less automatic cluster configuration. Default is true (allow automatic migrations).
cluster_require_full_coverage:
type: bool
required: false
description: By default cluster nodes stop accepting queries if they detect there is at least a hash slot uncovered (no available node is serving it). The default id true.
cluster_replica_no_failover:
type: bool
required: false
description: This option, when set to true, prevents replicas from trying to failover its primary during primary failures. The default is false.
cluster_allow_reads_when_down:
type: bool
required: false
description: This is useful for two cases. The first case is for when an application doesn't require consistency of data during node failures or network partitions. The second use case is for configurations that don't meet the recommended three shards but want to enable cluster mode and scale later. The default is false.
cluster_allow_pubsubshard_when_down:
type: bool
required: false
description: This option, when set to true, allows nodes to serve pubsub shard traffic while the cluster is in a down state, as long as it believes it owns the slots. The default is true.
cluster_link_sendbuf_limit:
type: int
required: false
description: Cluster link send buffer limit is the limit on the memory usage of an individual cluster bus link's send buffer in bytes. This limit is disabled by default, set to a number greater than 0 to enable it.
cluster_announce_hostname:
type: int
required: false
description: Clusters can configure their announced hostname using this config. By default it is set to an empty string.
cluster_preferred_endpoint_type:
type: str
choices:
- hostname
- ip
- unknown-endpoint
required: false
description: Clusters can advertise how clients should connect to them using either their IP address, a user defined hostname, or by declaring they have no endpoint.
cluster_blacklist_ttl:
type: int
required: false
description: The blacklist TTL is 60 seconds by default, which should be sufficient for most clusters, but you may considering increasing this if you see nodes getting re-added while using CLUSTER FORGET.
cluster_slot_stats_enabled:
type: bool
required: false
description: By default, the 'cluster-slot-stats-enabled' is disabled, and only 'key-count' is captured. By enabling the 'cluster-slot-stats-enabled' config, the cluster will begin to capture advanced statistics.
cluster_announce_ip:
type: str
required: false
description: Cluster Docker / NAT setting. If cluster-announce-client-ipv4 and cluster-announce-client-ipv6 are omitted, then cluster-announce-ip is exposed to clients.
cluster_announce_client_ipv4:
type: str
required: false
description: Cluster Docker / NAT setting. Public IPv4 address.
cluster_announce_client_ipv6:
type: str
required: false
description: Cluster Docker / NAT setting. Public IPv6 address.
cluster_announce_tls_port:
type: int
required: false
description: Cluster Docker / NAT setting. If tls-cluster is set to yes and cluster-announce-tls-port is omitted or set to zero, then cluster-announce-port refers to the TLS port. Note also that cluster-announce-tls-port has no effect if tls-cluster is set to no.
cluster_announce_port:
type: int
required: false
description: Cluster Docker / NAT setting for cluster announce port.
cluster_announce_bus_port:
type: int
required: false
description: Cluster Docker / NAT setting. For cluster announce bus port.
slowlog_log_slower_than:
type: int
required: false
description: The server Slow Log is a system to log queries that exceeded a specified execution time. time is expressed in microseconds, so 1000000 is equivalent to one second. The default is 10000. Note that a negative number disables the slow log, while a value of zero forces the logging of every command.
# TODO line 1890 ish onwards...
pidfile:
type: str
required: false
description: Path to the pid file.
valkey_enabled:
type: bool
required: true
description: Enable and start Valkey.
valkey_jpq:
type: dict
required: true
description: A dictionary of JMESPath query strings.
options:
pkgs_absent:
type: str
required: true
description: JMESPath query string for the packages absent.
pkgs_present:
type: str
required: true
description: JMESPath query string for the packages present.
pkgs_present_backports:
type: str
required: true
description: JMESPath query string for the backports packages present.
service:
type: str
required: true
description: JMESPath query string for the Valkey service.
valkey_pkgs:
type: list
elements: dict
required: true
description: A list of distros and deb packages that should be absent and present.
options:
name:
type: str
required: true
description: The Linux distro name.
choices:
- bookworm
- noble
- trixie
pkgs_absent:
type: list
required: false
description: A list of deb packages that should be absent.
pkgs_present:
type: list
required: false
description: A list of deb packages that should be present.
pkgs_present_backports:
type: list
required: true
description: A list of deb packages that should be present from backports.
valkey_protected_configs:
type: list
required: false
description: A list of Valkey config to be editing using lineinfile.
valkey_verify:
type: bool
required: true
description: Use the argument specification to verify the variables that start with valkey_.
...