joakim/rick-infra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Valkey infrastructure role as Redis-compatible cache service

Browse Source 
- Implemented complete Valkey infrastructure role following PostgreSQL patterns
- Provides 100% Redis-compatible high-performance data structure store
- Configured for multi-application support with database isolation
- Security-focused: localhost-only binding, password auth, systemd hardening
- Arch Linux compatible: uses native Valkey package with Redis compatibility
- Database allocation strategy: DB 0 reserved, DB 1+ for applications
- Full systemd integration with security overrides and proper service management
- Redis client compatibility maintained for seamless application integration
- Ready for Authentik and future container workloads requiring cache services
This commit is contained in:
Joakim
2025-11-18 23:58:21 +01:00
parent ddbdefd27f
commit 3b062edeb6
10 changed files with 574 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
roles/valkey/README.md Normal file
View File

@@ -0,0 +1,163 @@
# Valkey Infrastructure Role
This role provides Valkey as shared infrastructure for the rick-infra project, following the same patterns established by the PostgreSQL role.
## Overview
**Valkey** is a high-performance data structure store used as a database, cache, and message broker. It's a Redis fork that maintains **100% Redis compatibility** while providing additional features and improvements.
Valkey is deployed as a host-level service that multiple applications can use for caching, sessions, and data storage. Each application configures its own Valkey database number and connection parameters.
## Why Valkey?
- **Redis-compatible**: Drop-in replacement for Redis with identical API
- **Open source**: Truly open source alternative to Redis
- **Performance**: Enhanced performance optimizations
- **Arch Linux default**: Arch Linux provides Valkey instead of Redis in the `redis` package
- **Future-proof**: Active development and community support
## Features
- **Security-focused**: Localhost-only binding, password authentication, disabled dangerous commands
- **Systemd integration**: Native systemd service management with security hardening
- **Multi-application support**: 16 databases available for different services
- **Performance optimized**: Conservative memory limits and persistence settings
- **Infrastructure pattern**: Matches PostgreSQL role architecture
- **Redis compatibility**: Applications can use standard Redis clients and commands
## Database Allocation
Applications should use different Valkey database numbers:
- **Database 0**: Reserved for system/testing use
- **Database 1**: Authentik (sessions, cache)
- **Database 2**: Nextcloud (sessions, file locking, cache)
- **Database 3+**: Available for additional services
## Configuration
### Required Variables
```yaml
vault_valkey_password: "your-secure-valkey-password"
```
### Optional Overrides
```yaml
# Service management
valkey_service_enabled: true
valkey_service_state: "started"
# Network configuration
valkey_bind: "127.0.0.1"
valkey_port: 6379
# Memory management
valkey_maxmemory: "256mb"
valkey_maxmemory_policy: "allkeys-lru"
# Security hardening
valkey_systemd_security: true
```
## Application Integration
Applications can connect to Valkey using either Valkey-specific or Redis-compatible patterns:
### Valkey Environment Variables (Recommended)
```yaml
VALKEY_HOST: "{{ ansible_default_ipv4.address }}"
VALKEY_PORT: "6379"
VALKEY_PASSWORD: "{{ vault_valkey_password }}"
VALKEY_DB: "1" # Unique database number per application
```
### Redis-Compatible Environment Variables (Also Supported)
```yaml
REDIS_HOST: "{{ ansible_default_ipv4.address }}"
REDIS_PORT: "6379"
REDIS_PASSWORD: "{{ vault_valkey_password }}"
REDIS_DB: "1" # Unique database number per application
```
### Connection Example
```bash
# Using redis-cli (Redis-compatible)
redis-cli -h 127.0.0.1 -p 6379 -a password -n 1
# Using valkey-cli (native Valkey client)
valkey-cli -h 127.0.0.1 -p 6379 -a password -n 1
```
## Redis Compatibility
Valkey maintains **100% Redis compatibility**:
- **Same commands**: All Redis commands work identically
- **Same protocols**: RESP (Redis Serialization Protocol) supported
- **Same client libraries**: All Redis client libraries work without modification
- **Same configuration format**: Configuration syntax identical to Redis
- **Same data types**: All Redis data types supported
## Security
- **Network isolation**: Binds only to localhost
- **Authentication**: Password protection required
- **Command restrictions**: Dangerous commands disabled
- **Systemd hardening**: Full security restrictions applied
- **File permissions**: Restrictive access to configuration and data
## Dependencies
This is an infrastructure role with no dependencies. Applications that need Valkey should declare this role as a dependency:
```yaml
# roles/your-app/meta/main.yml
dependencies:
- role: valkey
```
## Service Management
```bash
# Service status
sudo systemctl status valkey
# View logs
sudo journalctl -u valkey -f
# Test connectivity
redis-cli -h 127.0.0.1 -p 6379 -a password ping
```
## Monitoring
Valkey status is reported during deployment and can be monitored through:
- **systemctl**: Service health and status
- **journald**: Centralized logging
- **Redis CLI**: Direct connectivity testing using standard Redis tools
- **Application logs**: Connection status from applications
## File Locations
- **Configuration**: `/etc/valkey/valkey.conf`
- **Data directory**: `/var/lib/valkey`
- **Systemd override**: `/etc/systemd/system/valkey.service.d/override.conf`
- **Logs**: `journalctl -u valkey`
## Migration from Redis
If migrating from Redis:
1. **Data compatibility**: Valkey can read existing Redis data files
2. **Configuration**: Most Redis configurations work without changes
3. **Applications**: No application changes required due to protocol compatibility
4. **Monitoring**: Same Redis monitoring tools work with Valkey
## Notes
This role follows the rick-infra infrastructure pattern where foundational services (Valkey, PostgreSQL) are provided as host-level services, and applications configure their own usage patterns rather than managing separate instances.
**Arch Linux Integration**: The role automatically works with Arch Linux's package system, which provides Valkey as the `redis` package with full Redis compatibility.