Vault Secrets Operator (VSO) Helm Chart

A Helm chart for automating the creation and management of HashiCorp Vault connections, authentication, and static secrets in Kubernetes clusters.

Overview

This Helm chart leverages the Vault Secrets Operator to automatically synchronize secrets from HashiCorp Vault into Kubernetes secrets. It supports multiple environments and clusters with environment-specific configurations.

The chart is automatically deployed via ArgoCD and manages secrets across staging, production, and blockchain clusters.

How to Add Secrets for Your Application

To add secrets for your application, you must modify the configuration in this repository:

👉 Vault Secrets Repository

1. Navigate to the vault-secrets repository
2. Choose the appropriate values file for your target cluster:
   • values-staging.yaml - For staging environment
   • values-production.yaml - For production environment
   • values-blockchain.yaml - For blockchain cluster
3. Add your secret configuration under the vault_secrets section (see examples below)
4. Create a merge request with your changes
5. Once merged, ArgoCD will automatically deploy the changes and create your Kubernetes secrets

Project Structure

VSO/
├── Chart.yaml                      # Helm chart metadata
├── templates/
│   ├── vault_auths.yaml           # Vault authentication configuration
│   ├── vault_connection.yaml      # Vault connection settings
│   └── vault_static_secret.yaml   # Static secret definitions
├── values-blockchain.yaml         # Configuration for blockchain cluster
├── values-production.yaml         # Configuration for production cluster
└── values-staging.yaml            # Configuration for staging cluster

Environment-Specific Values Files

The chart includes three pre-configured values files for different environments:

File	Purpose	Target Cluster
values-blockchain.yaml	Blockchain services	Blockchain Kubernetes cluster
values-production.yaml	Production workloads	Production Kubernetes cluster
values-staging.yaml	Development/testing	Staging Kubernetes cluster

Configuration

Global Settings

Each values file contains the following global configuration (⚠️ DO NOT MODIFY unless coordinated with DevOps team):

vault_address: https://<example-ip-address>:8200
vault_skip_tls_verify: true
vault_kubernetes_role_name: vault-secrets-operator-role
vault_kubernetes_mount_name: kubernetes

Adding Secrets

Users should ONLY modify the vault_secrets section to add new secret mappings.

Structure

vault_secrets:
  - namespace: <kubernetes-namespace>
    secrets:
      - name: <kubernetes-secret-name>
        mount: <vault-mount>
        path: <vault-path>

Field Descriptions

Field	Description	Example	Required
namespace	Kubernetes namespace where the secret will be created	blockchain-admin-staging	✅ Yes
name	Name of the Kubernetes secret to be created	vault-secret	✅ Yes
mount	Vault mount path (KV v2 engine)	blockchain, platform	✅ Yes
path	Path to the secret within the Vault mount	admin, shared	✅ Yes

Example Configuration

vault_secrets:
  - namespace: my-application-staging
    secrets:
      - name: app-credentials
        mount: platform
        path: my-app/credentials
      - name: database-secret
        mount: platform
        path: my-app/database

This configuration will create two Kubernetes secrets in the my-application-staging namespace:

• app-credentials → synced from platform/my-app/credentials in Vault
• database-secret → synced from platform/my-app/database in Vault

Important Guidelines

⚠️ Critical Rules

1. ONLY modify the vault_secrets section - Do not change global Vault connection or authentication settings
2. Consult DevOps team before using a new mount - Mount paths are pre-configured and environment-specific
3. Use existing namespaces - Ensure the Kubernetes namespace exists before adding secrets
4. Follow naming conventions - Use kebab-case for secret names (e.g., my-app-secret)

Vault Mount Reference

Common mount paths (consult DevOps team for complete list):

Mount	Purpose
blockchain	Blockchain services secrets
platform	Platform and infrastructure secrets
exchange	Exchange-related secrets

Path Resolution in Vault UI

The secret path in Vault UI is constructed as: <mount>/data/<path>

Example:

• Configuration: mount: blockchain, path: admin
• Vault UI path: blockchain/data/admin

Advanced Configuration (Optional)

The chart supports additional optional parameters for advanced use cases:

vault_secrets:
  - namespace: my-namespace
    refresh_after: 60s              # How often to refresh from Vault (default: 30s)
    type: kv-v2                     # Vault secret engine type (default: kv-v2)
    secrets:
      - name: my-secret
        mount: platform
        path: my-app/config
        destination:
          create: true              # Create secret if it doesn't exist (default: true)
          overwrite: false          # Overwrite existing secret (default: false)
          type: Opaque              # Kubernetes secret type (default: Opaque)
        rollout_restart_targets:    # Automatically restart deployments/statefulsets
          - kind: Deployment
            name: my-app

Troubleshooting

⚠️ Important: If the secret path does not exist in Vault, the Kubernetes secret will NOT be created at all.

Before adding a secret configuration, ensure:

1. The secret path exists in Vault UI at: <mount>/data/<path>
2. The Kubernetes namespace already exists in the target cluster
3. You have verified the correct mount path with the DevOps team

To verify your secret was created successfully:

# Check VaultStaticSecret resources
kubectl get vaultstaticsecret -n <your-namespace>

# Check Kubernetes secrets
kubectl get secrets -n <your-namespace>