🔐 Vault Sync Operator

📥 Installation

Add the Helm repository and install the operator:

# Add the repository
helm repo add vault-sync-operator https://danieldonoghue.github.io/vault-sync-operator/
helm repo update

# Install the operator
helm install vault-sync-operator vault-sync-operator/vault-sync-operator \
  --namespace vault-sync-operator-system \
  --create-namespace \
  --set vault.address="http://<vault-ip-address>:8200"

⚙️ Configuration Options

Required Configuration:

• vault.address - Your Vault server address (e.g., "http://vault.example.com:8200")

Optional Configuration:

• vault.role - Vault Kubernetes auth role (default: vault-sync-operator)
• vault.authPath - Vault auth path (default: kubernetes)
• controllerManager.metrics.enableAuth - Enable metrics authentication (default: true)
• controllerManager.leaderElection - Enable leader election (default: false)
• image.tag - Override the operator version
• resources - Container resource requests and limits
• clusterName - Optional cluster name for multi-cluster deployments

🚀 Alternative Installation Methods

The operator supports multiple deployment methods:

• Helm Chart (recommended): Use this repository
• Kustomize: kubectl apply -k config/default/
• Raw Manifests: Download from GitHub Releases

📝 Usage Examples

🔄 Auto-Discovery Mode (Recommended)

Automatically discovers all secrets referenced in your deployment:

metadata:
  annotations:
    vault-sync.io/path: "secret/data/my-app"
    # All secrets referenced in pod template will be synced

⚙️ Custom Configuration Mode

Specify exact secrets and keys to sync:

metadata:
  annotations:
    vault-sync.io/path: "secret/data/my-app"
    vault-sync.io/secrets: |
      [
        {
          "name": "my-app-secrets",
          "keys": ["username", "password"],
          "prefix": "app_"
        }
      ]

🚀 Advanced Features

metadata:
  annotations:
    vault-sync.io/path: "secret/data/my-app"
    vault-sync.io/preserve-on-delete: "true"  # Don't delete from Vault
    vault-sync.io/reconcile: "5m"            # Check every 5 minutes
    vault-sync.io/rotation-check: "enabled"  # Detect secret changes

📊 Monitoring & Observability

The operator provides comprehensive monitoring capabilities:

• Prometheus Metrics: Sync operations, errors, authentication attempts
• Health Checks: /healthz and /readyz endpoints
• Structured Logging: Detailed error messages with context
• Metrics Authentication: Secure metrics endpoint access

Access metrics (with authentication):

# Get service account token
TOKEN=$(kubectl create token vault-sync-operator-controller-manager -n vault-sync-operator-system)

# Access metrics
kubectl port-forward -n vault-sync-operator-system svc/vault-sync-operator-controller-manager-metrics-service 8080:8080
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/metrics

🔧 Troubleshooting

Common debugging commands:

# Check operator logs
kubectl logs -n vault-sync-operator-system deployment/vault-sync-operator-controller-manager

# Verify deployment annotations
kubectl get deployment <name> -o yaml | grep -A 10 annotations

# Check health endpoints
kubectl port-forward -n vault-sync-operator-system deployment/vault-sync-operator-controller-manager 8081:8081
curl http://localhost:8081/healthz
curl http://localhost:8081/readyz

📋 Quick Reference

Essential Links:

• 🏗️ Vault Setup Guide
• 🚀 Deployment Guide
• 🌐 Multi-Cluster Setup
• 📄 Basic Example
• 🔍 Auto-Discovery Example