|
| 1 | +# Redis Password Configuration Options |
| 2 | + |
| 3 | +ArgoCD supports two methods for configuring Redis password authentication. Choose the option that best fits your deployment needs. |
| 4 | + |
| 5 | +## Option 1: Environment Variable (Default) |
| 6 | + |
| 7 | +**Location**: `manifests/base/` |
| 8 | +**Use case**: Standard deployments, existing installations |
| 9 | +**Setup effort**: None (default behavior) |
| 10 | + |
| 11 | +### Description |
| 12 | +Uses the traditional `REDIS_PASSWORD` environment variable approach where the password is read from the `argocd-redis` Kubernetes secret. |
| 13 | + |
| 14 | +### Usage |
| 15 | +```bash |
| 16 | +# Apply base manifests (default behavior) |
| 17 | +kubectl apply -k manifests/base/ |
| 18 | + |
| 19 | +# Verify Redis secret exists |
| 20 | +kubectl get secret argocd-redis -o jsonpath='{.data.auth}' | base64 -d |
| 21 | +``` |
| 22 | + |
| 23 | +**✅ This is the recommended approach for most users** |
| 24 | + |
| 25 | +## Option 2: File Mount (Advanced) |
| 26 | + |
| 27 | +**Location**: `manifests/overlays/file-mount/` |
| 28 | +**Use case**: External secret management, advanced security requirements |
| 29 | +**Setup effort**: Moderate (requires credential files) |
| 30 | + |
| 31 | +### Description |
| 32 | +Uses file-based credentials mounted into the Redis container. Supports external secret management systems like Vault, AWS Secrets Manager, etc. |
| 33 | + |
| 34 | +### Usage |
| 35 | + |
| 36 | +#### Step 1: Apply the file-mount overlay |
| 37 | +```bash |
| 38 | +# Apply the file-mount variant |
| 39 | +kubectl apply -k manifests/overlays/file-mount/ |
| 40 | +``` |
| 41 | + |
| 42 | +#### Step 2: Create your credential secret |
| 43 | +```bash |
| 44 | +# Create secret with credential files |
| 45 | +kubectl create secret generic my-redis-creds \ |
| 46 | + --from-literal=auth=mypassword \ |
| 47 | + --from-literal=auth_username=myuser |
| 48 | +``` |
| 49 | + |
| 50 | +#### Step 3: Update Redis to use your secret |
| 51 | +```bash |
| 52 | +# Patch the Redis deployment to use your secret |
| 53 | +kubectl patch deployment argocd-redis -p '{ |
| 54 | + "spec": { |
| 55 | + "template": { |
| 56 | + "spec": { |
| 57 | + "volumes": [{ |
| 58 | + "name": "redis-creds", |
| 59 | + "secret": { |
| 60 | + "secretName": "my-redis-creds", |
| 61 | + "optional": false |
| 62 | + } |
| 63 | + }] |
| 64 | + } |
| 65 | + } |
| 66 | + } |
| 67 | +}' |
| 68 | +``` |
| 69 | + |
| 70 | +## What's Included in File-Mount Overlay |
| 71 | + |
| 72 | +### New Components |
| 73 | +- **Redis ConfigMap**: Contains Redis configuration template and setup script |
| 74 | +- **Init Container**: Processes credential files and generates Redis configuration |
| 75 | + |
| 76 | +### Patches Applied |
| 77 | +- **Redis Deployment**: Adds init container, volumes, and file-mount support |
| 78 | +- **Server Deployment**: Adds `REDIS_CREDS_FILE_PATH` environment variable |
| 79 | +- **Repo Server Deployment**: Adds `REDIS_CREDS_FILE_PATH` environment variable |
| 80 | +- **Application Controller**: Adds `REDIS_CREDS_FILE_PATH` environment variable |
| 81 | +- **Application Controller StatefulSet**: Adds `REDIS_CREDS_FILE_PATH` environment variable |
| 82 | + |
| 83 | +## Credential File Structure |
| 84 | + |
| 85 | +When using file-mount, the following files can be provided: |
| 86 | + |
| 87 | +| File Name | Description | Required | |
| 88 | +|-----------|-------------|----------| |
| 89 | +| `auth` | Redis password | Yes | |
| 90 | +| `auth_username` | Redis username | No | |
| 91 | +| `sentinel_username` | Sentinel username | No | |
| 92 | +| `sentinel_auth` | Sentinel password | No | |
| 93 | + |
| 94 | +## Configuration Priority |
| 95 | + |
| 96 | +The file-mount overlay follows this priority order: |
| 97 | +1. **File-based credentials** (if files exist and are readable) |
| 98 | +2. **Environment variables** (fallback if files not found) |
| 99 | +3. **No authentication** (if neither source is available) |
| 100 | + |
| 101 | +## Switching Between Options |
| 102 | + |
| 103 | +### From Environment Variable to File Mount |
| 104 | +```bash |
| 105 | +# Apply the file-mount overlay |
| 106 | +kubectl apply -k manifests/overlays/file-mount/ |
| 107 | + |
| 108 | +# Create your credential secret (see Step 2 above) |
| 109 | +kubectl create secret generic my-redis-creds --from-literal=auth=mypassword |
| 110 | + |
| 111 | +# Update Redis deployment (see Step 3 above) |
| 112 | +``` |
| 113 | + |
| 114 | +### From File Mount to Environment Variable |
| 115 | +```bash |
| 116 | +# Apply base manifests |
| 117 | +kubectl apply -k manifests/base/ |
| 118 | + |
| 119 | +# Ensure the argocd-redis secret exists |
| 120 | +kubectl get secret argocd-redis |
| 121 | +``` |
| 122 | + |
| 123 | +## Verification |
| 124 | + |
| 125 | +### Check which method is active |
| 126 | +```bash |
| 127 | +# Check init container logs |
| 128 | +kubectl logs deployment/argocd-redis -c redis-config-init |
| 129 | + |
| 130 | +# Expected output for file-mount: |
| 131 | +# "Using password from file: /redis-creds/auth" |
| 132 | + |
| 133 | +# Expected output for environment variable: |
| 134 | +# "Using password from environment variable" |
| 135 | +``` |
| 136 | + |
| 137 | +### Verify Redis configuration |
| 138 | +```bash |
| 139 | +# Check generated Redis config |
| 140 | +kubectl exec deployment/argocd-redis -- cat /data/redis.conf | grep requirepass |
| 141 | + |
| 142 | +# Test Redis connection |
| 143 | +kubectl exec deployment/argocd-redis -- redis-cli ping |
| 144 | +``` |
| 145 | + |
| 146 | +## Integration with External Secret Management |
| 147 | + |
| 148 | +### Example: Using External Secrets Operator |
| 149 | +```yaml |
| 150 | +apiVersion: external-secrets.io/v1beta1 |
| 151 | +kind: SecretStore |
| 152 | +metadata: |
| 153 | + name: vault-backend |
| 154 | +spec: |
| 155 | + provider: |
| 156 | + vault: |
| 157 | + server: "https://vault.example.com" |
| 158 | + path: "secret" |
| 159 | + version: "v2" |
| 160 | + auth: |
| 161 | + kubernetes: |
| 162 | + mountPath: "kubernetes" |
| 163 | + role: "argocd" |
| 164 | +--- |
| 165 | +apiVersion: external-secrets.io/v1beta1 |
| 166 | +kind: ExternalSecret |
| 167 | +metadata: |
| 168 | + name: redis-credentials |
| 169 | +spec: |
| 170 | + refreshInterval: 1h |
| 171 | + secretStoreRef: |
| 172 | + name: vault-backend |
| 173 | + kind: SecretStore |
| 174 | + target: |
| 175 | + name: my-redis-creds |
| 176 | + creationPolicy: Owner |
| 177 | + data: |
| 178 | + - secretKey: auth |
| 179 | + remoteRef: |
| 180 | + key: redis |
| 181 | + property: password |
| 182 | +``` |
| 183 | +
|
| 184 | +## Troubleshooting |
| 185 | +
|
| 186 | +### File mount not working |
| 187 | +```bash |
| 188 | +# Check if files are mounted correctly |
| 189 | +kubectl exec deployment/argocd-redis -- ls -la /redis-creds/ |
| 190 | + |
| 191 | +# Check init container logs |
| 192 | +kubectl logs deployment/argocd-redis -c redis-config-init |
| 193 | + |
| 194 | +# Verify secret contents |
| 195 | +kubectl get secret my-redis-creds -o yaml |
| 196 | +``` |
| 197 | + |
| 198 | +### Environment variable not working |
| 199 | +```bash |
| 200 | +# Check if argocd-redis secret exists |
| 201 | +kubectl get secret argocd-redis |
| 202 | + |
| 203 | +# Check environment variables in container |
| 204 | +kubectl exec deployment/argocd-redis -- env | grep REDIS_PASSWORD |
| 205 | +``` |
| 206 | + |
| 207 | +### Connection issues |
| 208 | +```bash |
| 209 | +# Test Redis connectivity |
| 210 | +kubectl exec deployment/argocd-redis -- redis-cli ping |
| 211 | + |
| 212 | +# Check Redis logs |
| 213 | +kubectl logs deployment/argocd-redis -c redis |
| 214 | + |
| 215 | +# Verify ArgoCD components can connect |
| 216 | +kubectl logs deployment/argocd-server | grep -i redis |
| 217 | +``` |
| 218 | + |
| 219 | +## Best Practices |
| 220 | + |
| 221 | +1. **Start with Environment Variable**: Use the default approach unless you have specific requirements |
| 222 | +2. **Secure File Permissions**: Ensure credential files have appropriate permissions (600/400) |
| 223 | +3. **Regular Rotation**: Implement credential rotation for enhanced security |
| 224 | +4. **Monitor Access**: Log and monitor access to credential files |
| 225 | +5. **Backup Strategies**: Include credential management in your backup/recovery procedures |
0 commit comments