A Pulumi component for deploying Valkey (Redis-compatible in-memory data structure store) with Docker.

• Python 3.11+
• Pulumi CLI
• Docker
• Recommended: mise for environment management

# Clone the repository
git clone https://github.com/daotl/valkey-pulumi.git
cd valkey-pulumi

# Install dependencies and set up environment
mise install

1. Create a basic Valkey deployment:

# __main__.py
from valkey_pulumi import create_standalone_valkey

# Simple deployment with default configuration
valkey = create_standalone_valkey("my-valkey")

2. Deploy with Pulumi:

pulumi stack init dev
pulumi up

3. Connect to your Valkey:

# Get connection details
pulumi stack output

# Connect with redis-cli
redis-cli -h $(pulumi stack output -j | jq -r '.my_valkey_host') \
         -p $(pulumi stack output -j | jq -r '.my_valkey_port')

Valkey deployments are configured using Pulumi.<stack>.yaml files. The configuration supports all Bitnami Valkey environment variables and features. See the complete Bitnami Valkey documentation for detailed information about:

• Configuration parameters
• Persistence and AOF settings
• Security and authentication
• Replication configuration
• Logging configuration
• TLS/SSL support

Our Pulumi configuration uses clean, readable parameter names that map to Bitnami Valkey environment variables. The following table shows all customizable environment variables from the Bitnami Valkey container:

Customizable Environment Variables:

The following configuration options are supported directly by Bitnami Valkey environment variables:

Important Note: For Valkey configuration directives not available as environment variables (such as appendfsync, client-output-buffer-limit, tcp-keepalive, etc.), provide a custom configuration file using the valkey_config_file parameter. See the Advanced Configuration section below for details.

Pulumi-only Settings:

These control how the Pulumi component provisions Docker resources and do not map to Bitnami environment variables.

For Valkey configuration directives that are not available as environment variables, provide a custom configuration file using the valkey_config_file parameter:

Common Advanced Settings:

• appendfsync - AOF fsync policy (always, everysec, no)
• maxmemory - Maximum memory limit (e.g., 2gb)
• maxmemory-policy - Memory eviction policy (e.g., allkeys-lru)
• timeout - Client timeout in seconds
• tcp-keepalive - TCP keepalive in seconds
• protected-mode - Enable/disable protected mode
• loglevel - Valkey log level (debug, verbose, notice, warning)
• databases - Number of databases
• client-output-buffer-limit - Client buffer limits
• tcp-keepalive - TCP keepalive settings

Example Setup:

# Pulumi.dev.yaml
config:
  valkey:
    # Standard settings via environment variables
    aof_enabled: true
    database: "valkey"
    disable_commands: ["FLUSHDB", "FLUSHALL"]

    # Advanced settings via custom config file
    valkey_config_file: "./config/valkey-advanced.conf"

# Create custom configuration file
mkdir -p config
cat > config/valkey-advanced.conf << EOF
# Advanced Valkey Configuration
appendfsync everysec
maxmemory 2gb
maxmemory-policy allkeys-lru
timeout 300
tcp-keepalive 60
protected-mode yes
loglevel notice
databases 16

# Client buffer limits
client-output-buffer-limit normal 0 0 0
client-output-buffer-limit replica 256mb 64mb 60
client-output-buffer-limit pubsub 32mb 8mb 60
EOF

Production Example:

cat > config/valkey-production.conf << EOF
# Production Valkey Configuration
appendfsync everysec
maxmemory 4gb
maxmemory-policy allkeys-lru
timeout 300
tcp-keepalive 60
protected-mode yes
loglevel notice
databases 16

# Production client buffer limits
client-output-buffer-limit normal 0 0 0
client-output-buffer-limit replica 512mb 128mb 120
client-output-buffer-limit pubsub 64mb 16mb 120
EOF

Note: The custom configuration file is mounted to /opt/bitnami/valkey/mounted-etc/valkey.conf in the container. If you provide this file, the Bitnami overrides file (valkey_overrides_file) is ignored—use one or the other. Keep your custom config aligned with any environment-variable-driven settings you still want applied.

Read-Only Environment Variables:

These variables provide path information and are used internally by the Bitnami container:

Note: For the complete list of supported Bitnami Valkey environment variables, refer to the official Bitnami Valkey Docker Hub page.

config:
  valkey:
    # Basic settings
    image: "docker.io/bitnami/valkey:9.0"
    port: 6379
    password: ""  # Set with: pulumi config set --secret valkey:password "your_password"
    allow_empty_password: false

    # Core Valkey configuration
    aof_enabled: true
    aof_fsync_policy: "everysec"  # always, everysec, no
    maxmemory: null               # e.g., "2gb" for memory limit
    maxmemory_policy: "allkeys-lru"
    databases: 16
    timeout: 300
    tcp_keepalive: 60
    protected_mode: true

    # Security
    disable_commands:
      - "FLUSHDB"
      - "FLUSHALL"

    # Persistence and scaling
    persistence_enabled: true
    replica_count: 1

    # Advanced features (uncomment as needed)
    # tls_enabled: true
    # tls_cert_file: "/path/to/cert.pem"
    # tls_key_file: "/path/to/key.pem"
    # acl_file: "/path/to/acl.conf"

    # Use a host bind mount instead of a Docker volume
    # host_data_path: "/srv/valkey-data"
    # valkey_data_dir: "/bitnami/valkey/data"  # optional override of container path

# Set password securely
pulumi config set --secret valkey:password "your_secure_password"

# Set configuration values
pulumi config set valkey:maxmemory "2gb"
pulumi config set valkey:replica_count 3
pulumi config set valkey:aof_fsync_policy "always"

# Enable security features
pulumi config set valkey:tls_enabled true
pulumi config set valkey:tls_cert_file "/path/to/cert.pem"

The project includes several ready-to-run examples demonstrating different configurations (Standalone, Replica Set, ACL, TLS).

1. Configure Pulumi to run examples: Change work directory to src/valkey_pulumi/examples, change Pulumi.yaml to point to the examples entry point:

   main: ./__main__.py # acl_example.py,replica_set.py,standalone.py,tls_example.py

   The default value for the main parameter is the __main__.py in the current directory.

2. Run a specific example using the VALKEY_EXAMPLE environment variable:

   • Standalone (Default):

     pulumi up

   • Replica Set:

     VALKEY_EXAMPLE=replica_set pulumi up

   • Access Control List (ACL):

     VALKEY_EXAMPLE=acl pulumi up

   • TLS Encryption: (Requires valid certificates in /etc/ssl/certs and /etc/ssl/private)

     VALKEY_EXAMPLE=tls pulumi up

   Note: When switching between examples (especially from Standalone to Replica Set), it is recommended to run pulumi destroy first to avoid port or container name conflicts.

from valkey_pulumi import create_standalone_valkey

dev_valkey = create_standalone_valkey(
    "dev-valkey",
    password="dev_password",
    aof_enabled=True,
    maxmemory="1gb",
    maxmemory_policy="allkeys-lru",
    disable_commands=["FLUSHDB", "FLUSHALL"]
)

from valkey_pulumi import create_standalone_valkey

prod_valkey = create_standalone_valkey(
    "prod-valkey",
    password="secure_production_password",
    persistence_enabled=True,
    aof_enabled=True,
    aof_fsync_policy="everysec",
    maxmemory="4gb",
    maxmemory_policy="allkeys-lru",
    disable_commands=[
        "FLUSHDB", "FLUSHALL", "CONFIG", "DEBUG",
        "EVAL", "SCRIPT", "MODULE"
    ]
)

from valkey_pulumi import create_standalone_valkey

secure_valkey = create_standalone_valkey(
    "secure-valkey",
    password="super_secure_password",
    tls_enabled=True,
    tls_cert_file="/etc/ssl/certs/valkey.crt",
    tls_key_file="/etc/ssl/private/valkey.key",
    tls_ca_file="/etc/ssl/certs/valkey-ca.crt",
    maxmemory="2gb",
    disable_commands=["FLUSHDB", "FLUSHALL", "CONFIG"]
)

See the Bitnami Valkey replication documentation for complete details on replication configuration.

from valkey_pulumi import create_valkey_replica_set

replica_set = create_valkey_replica_set(
    "ha-valkey",
    replica_count=3,
    primary_config={
        "password": "replica_password",
        "persistence_enabled": True,
        "aof_enabled": True,
        "maxmemory": "4gb",
        "replica_announce_ip": "primary.example.com"
    },
    replica_config={
        "replica_announce_ip": "replica.example.com"
    }
)

from valkey_pulumi import create_standalone_valkey

# Create with ACL file for fine-grained access control
acl_valkey = create_standalone_valkey(
    "acl-valkey",
    password="admin_password",
    acl_file="/etc/valkey/acl.conf",
    maxmemory="2gb"
)

# Example ACL file content:
# user default on nopass ~* +@all
# user admin on >admin_password ~* +@all
# user readonly on >readonly_password ~* +@read

• ✅ Use strong passwords with pulumi config set --secret
• ✅ Enable TLS for network encryption
• ✅ Disable dangerous commands (CONFIG, DEBUG, EVAL, etc.)
• ✅ Configure memory limits to prevent OOM issues
• ✅ Use odd replica counts (3, 5) to avoid split-brain
• ✅ Set specific image versions instead of latest
• ✅ Use ACL files for fine-grained access control

config:
  valkey:
    image: "docker.io/bitnami/valkey:9.0.2"  # Use specific version
    password: ""  # Set with --secret
    allow_empty_password: false

    # Enhanced security
    disable_commands:
      - "FLUSHDB"
      - "FLUSHALL"
      - "CONFIG"
      - "DEBUG"
      - "EVAL"
      - "SCRIPT"
      - "MODULE"
      - "SAVE"
      - "BGSAVE"

    # Production-optimized settings
    aof_enabled: true
    aof_fsync_policy: "everysec"
    maxmemory: "4gb"
    maxmemory_policy: "allkeys-lru"
    replica_count: 3  # High availability

    # TLS security
    tls_enabled: true
    tls_cert_file: "/etc/ssl/certs/valkey.crt"
    tls_key_file: "/etc/ssl/private/valkey.key"

config:
  valkey:
    image: "docker.io/bitnami/valkey:9.0"
    password: ""  # Set with dev password
    allow_empty_password: false
    persistence_enabled: true
    replica_count: 1

    # Relaxed dev settings
    aof_enabled: true
    maxmemory: null  # No memory limit for dev
    maxmemory_policy: "allkeys-lru"

    # Basic security
    disable_commands:
      - "FLUSHDB"
      - "FLUSHALL"

config:
  valkey:
    image: "docker.io/bitnami/valkey:9.0.2"
    password: ""  # Set with strong production password
    allow_empty_password: false
    persistence_enabled: true
    replica_count: 3

    # Production-optimized
    aof_enabled: true
    aof_fsync_policy: "everysec"
    maxmemory: "4gb"
    maxmemory_policy: "allkeys-lru"

    # Enhanced security
    disable_commands:
      - "FLUSHDB"
      - "FLUSHALL"
      - "CONFIG"
      - "DEBUG"
      - "EVAL"
      - "SCRIPT"
      - "MODULE"

    # TLS enabled
    tls_enabled: true
    tls_cert_file: "/etc/ssl/certs/valkey.crt"
    tls_key_file: "/etc/ssl/private/valkey.key"

# Install tools and create environment
mise install

# Set up development environment
invoke setup-dev

# Run all checks (format, lint, test)
invoke check

# Format code
invoke format

# Run linting with auto-fix
invoke lint --fix

# Run tests
invoke test

# Build and serve documentation locally
invoke docs --build --open-browser

# Clean all generated files
invoke clean --all

# See all available tasks
invoke --list

The configuration sections below follow the same structure as the official Bitnami Valkey documentation.

See the Bitnami Valkey documentation on disabling commands for more details.

For security reasons, you may want to disable some commands. Configure the commands to disable:

config:
  valkey:
    disable_commands: ["FLUSHDB", "FLUSHALL", "CONFIG", "DEBUG"]

Pulumi Parameter:

See the Bitnami Valkey documentation on passing extra flags for more details.

Pass additional flags to the valkey-server startup:

config:
  valkey:
    extra_flags: "--maxmemory 100mb --tcp-keepalive 300"

Pulumi Parameter:

See the Bitnami Valkey documentation on setting passwords for more details.

Configure authentication for your Valkey deployment:

config:
  valkey:
    password: "your_secure_password"  # Use --secret when setting
    allow_empty_password: false

Pulumi Parameters:

See the Bitnami Valkey documentation on allowing empty passwords for more details.

For development environments, you can allow empty passwords:

config:
  valkey:
    allow_empty_password: true

Warning: This is recommended only for testing or development. Always set a strong password in production.

See the Bitnami Valkey documentation on disabling AOF persistence for more details.

Control AOF (Append Only File) persistence:

config:
  valkey:
    aof_enabled: false

Pulumi Parameters:

See the Bitnami Valkey documentation on ACL for more details.

Configure fine-grained access control:

config:
  valkey:
    acl_file: "/opt/bitnami/valkey/mounted-etc/users.acl"

Pulumi Parameter:

See the Bitnami Valkey documentation on standalone instances for more details.

Configure basic standalone Valkey deployment:

config:
  valkey:
    port: 6379
    database: "valkey"
    valkey_data_dir: "/bitnami/valkey/data"

Pulumi Parameters:

See the Bitnami Valkey documentation on replication for more details.

Configure primary/replica replication:

config:
  valkey:
    replication_mode: "primary"  # or "replica"
    primary_host: "valkey-primary"  # for replicas
    primary_port_number: 6379
    replica_ip: "10.0.1.100"  # optional
    replica_port: 6379  # optional

Pulumi Parameters:

See the Bitnami Valkey documentation on TLS/SSL for more details.

Enable TLS encryption for Valkey traffic:

config:
  valkey:
    tls_enabled: true
    tls_port_number: 6380
    tls_cert_file: "/opt/bitnami/valkey/certs/valkey.crt"
    tls_key_file: "/opt/bitnami/valkey/certs/valkey.key"
    tls_ca_file: "/opt/bitnami/valkey/certs/valkeyCA.crt"
    tls_auth_clients: true

TLS/SSL Parameters:

See the Bitnami Valkey documentation on configuration files and overriding configuration for more details.

Use custom configuration files:

config:
  valkey:
    valkey_config_file: "/path/to/custom-valkey.conf"
    # or use overrides file
    valkey_overrides_file: "/opt/bitnami/valkey/mounted-etc/overrides.conf"

Configuration File Parameters:

See the Bitnami Valkey documentation on RDB persistence for more details.

Configure RDB snapshot persistence:

config:
  valkey:
    rdb_policy_disabled: false
    rdb_policy: "900#1 600#5 300#10 120#50 60#1000 30#10000"

RDB Persistence Parameters:

Configure performance tuning and advanced settings:

config:
  valkey:
    # Memory management
    maxmemory: "2gb"
    maxmemory_policy: "allkeys-lru"

    # Connection settings
    timeout: 300
    tcp_keepalive: 60

    # Logging
    valkey_log_level: "notice"

    # Performance
    io_threads: 4
    io_threads_do_reads: true

    # Client buffer limits
    client_output_buffer_limit_normal: "0 0 0"
    client_output_buffer_limit_slave: "256mb 64mb 60"
    client_output_buffer_limit_pubsub: "32mb 8mb 60"

Advanced Parameters:

# Test connection from application server
redis-cli -h <valkey_host> -p 6379 -a <password> ping

# Verify replica status
redis-cli -h <valkey_host> -p 6379 -a <password> info replication

# Check configuration
redis-cli -h <valkey_host> -p 6379 -a <password> config get save

Monitor these key metrics:

• Memory usage
• CPU utilization
• Connected clients
• Command statistics
• Replication lag
• Error rates

Alert Thresholds:

• Memory > 80%
• CPU > 75%
• Replication lag > 5 seconds
• Connection errors > 1% of requests

For replica sets, test failover scenarios:

# Check replica status
redis-cli -h <replica_host> -p <replica_port> -a <password> info replication

# Test manual failover (if using Redis Sentinel)
redis-cli -h <sentinel_host> -p <sentinel_port> sentinel failover <master_name>

1. Out of Memory

   # Check memory usage
   redis-cli -h <host> -p 6379 -a <password> info memory
   
   # Check maxmemory policy
   redis-cli -h <host> -p 6379 -a <password> config get maxmemory-policy

2. Replication Lag

   # Check replication status
   redis-cli -h <host> -p 6379 -a <password> info replication
   
   # Check network connectivity between primary and replicas

3. Connection Refused

   # Check if container is running
   docker ps | grep valkey
   
   # Check port configuration and firewall rules
   netstat -tlnp | grep 6379

4. Authentication Issues

   # Verify password is set correctly
   redis-cli -h <host> -p 6379 -a <password> ping
   
   # Check if password is required
   redis-cli -h <host> -p 6379 ping  # Should return NOAUTH Authentication required

1. Data Recovery - Use AOF files for point-in-time recovery
2. Failover - Manually promote replica if primary fails
3. Password Reset - Update configuration and restart containers

Regular Tasks:

• Security updates: Update Docker image monthly
• Backup verification: Test restore procedures quarterly
• Performance tuning: Adjust memory policies based on usage
• Log review: Check for errors or unusual activity

Scaling:

• Add more replicas for read scaling
• Upgrade instance size for memory/CPU needs
• Consider sharding for very large datasets

# Initialize stack
pulumi stack init dev

# Preview deployment
pulumi preview

# Deploy
pulumi up

# Get outputs
pulumi stack output

# Use production stack
pulumi stack select prod

# Set production password
pulumi config set --secret valkey:password "strong_production_password"

# Set production-specific settings
pulumi config set valkey:maxmemory "4gb"
pulumi config set valkey:replica_count 3
pulumi config set valkey:tls_enabled true

# Deploy to production
pulumi up

This Pulumi component is based on the official Bitnami Valkey container. Key sections:

• Main Documentation - Complete reference
• Configuration - All environment variables
• Persistence - AOF and RDB settings
• Security - Authentication and access control
• Replication - Primary-replica setup
• Logging - Log configuration
• TLS/SSL - Encryption setup

For detailed documentation about this Pulumi component, see the docs/ directory:

• API Documentation - Complete API reference
• Development Guide - Contributing and development setup
• Contributing Guide - How to contribute to the project

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (invoke check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Issues: GitHub Issues
• Documentation: Project Documentation
• Questions: Feel free to open an issue for questions