feat: Add External Secret Manager Support to Hyperswitch Helm Charts

[inventvenkat]

Problem Statement / Feature Requirement

The Hyperswitch Helm charts currently embed all secrets directly in values.yaml files across all charts (hyperswitch-app, hyperswitch-card-vault, hyperswitch-keymanager). This approach creates significant security and operational challenges for production deployments:

• Secrets are stored in plain text in version control systems
• No centralized secret rotation capabilities
• Limited audit trails for secret access
• Difficult compliance with security frameworks (SOC2, PCI-DSS)
• Manual secret management across multiple environments

Context and Background

Currently, the Hyperswitch stack manages 50+ secrets across three main charts:

• hyperswitch-app: Database credentials, API keys, JWT secrets, encryption keys
• hyperswitch-card-vault: PCI-compliant card storage credentials and encryption keys
• hyperswitch-keymanager: Key encryption keys and service credentials

Production deployments require integration with enterprise secret management solutions like AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, and GCP Secret Manager.

Acceptance Criteria

Core Implementation

• Implement External Secrets Operator (ESO) integration as the primary approach
• Support multiple secret providers: AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, GCP Secret Manager
• Maintain full backward compatibility with existing native Kubernetes secret approach
• Implement feature flag (externalSecrets.enabled) to control secret management method

Chart-Specific Implementation

• Phase 1: Implement external secrets support in hyperswitch-app chart (50+ secrets)
• Phase 2: Add support to hyperswitch-card-vault chart
• Phase 3: Add support to hyperswitch-keymanager chart

Security and RBAC

• Create RBAC templates for External Secrets Operator
• Add service account annotations for cloud provider authentication
• Implement proper secret scoping and access controls
• Support namespace-scoped and cluster-scoped secret stores

Configuration Management

• Implement the proposed configuration format with sensible defaults
• Support custom refresh intervals per secret
• Allow override of target secret names and keys
• Support secret transformation and templating

Documentation and Migration

• Create comprehensive ESO setup guide
• Provide configuration examples for each supported secret provider
• Create step-by-step migration guide from current approach
• Document security best practices and compliance considerations

Technical Considerations

Configuration Structure

externalSecrets:
  enabled: false
  provider: external-secrets-operator
  secretStore:
    name: hyperswitch-secret-store
    kind: SecretStore  # or ClusterSecretStore
    namespace: hyperswitch
  refreshInterval: 1h
  
  # Global settings
  target:
    creationPolicy: Owner
    deletionPolicy: Retain
  
  # Per-chart secret mappings
  secrets:
    hyperswitch-secrets:
      secretStore: hyperswitch-secret-store
      target:
        name: hyperswitch-secrets
        namespace: hyperswitch
      refreshInterval: 30m
      data:
        - secretKey: admin_api_key
          remoteRef:
            key: hyperswitch/admin-api-key
            property: value
        - secretKey: jwt_secret
          remoteRef:
            key: hyperswitch/jwt-secret
    
    database-secrets:
      secretStore: hyperswitch-secret-store
      target:
        name: hyperswitch-db-secrets
      data:
        - secretKey: database_url
          remoteRef:
            key: hyperswitch/database-url
        - secretKey: redis_url
          remoteRef:
            key: hyperswitch/redis-url

Provider-Specific Examples

Support configuration templates for:

• AWS Secrets Manager: IAM roles, cross-account access
• HashiCorp Vault: Authentication methods (JWT, Kubernetes auth)
• Azure Key Vault: Managed Identity, Service Principal auth
• GCP Secret Manager: Workload Identity, Service Account keys

Backward Compatibility Strategy

• Default externalSecrets.enabled: false maintains current behavior
• Existing values.yaml secret configurations remain functional
• Conditional templating ensures no resource conflicts
• Clear migration path with validation checks

Potential Implementation Approach

Phase 1: Core Infrastructure (hyperswitch-app)

1. Add External Secrets CRDs as optional dependencies

   • Update Chart.yaml with conditional ESO dependency
   • Create values schema for external secrets configuration

2. Implement SecretStore templates

   • Create configurable SecretStore/ClusterSecretStore templates
   • Support multiple provider backends with authentication

3. Create ExternalSecret templates

   • Map existing secret keys to external secret references
   • Implement conditional rendering based on feature flag

4. Update existing secret references

   • Modify deployment templates to reference external secrets when enabled
   • Maintain backward compatibility with existing secret names

Phase 2: RBAC and Security

1. Create RBAC templates

   • ServiceAccount with proper annotations
   • Role/ClusterRole for ESO permissions
   • RoleBinding/ClusterRoleBinding

2. Implement security validations

   • Helm tests for secret accessibility
   • Chart validation for required configurations

Phase 3: Documentation and Examples

1. Provider setup guides

   • Step-by-step configuration for each provider
   • Authentication setup examples
   • Troubleshooting guides

2. Migration documentation

   • Current state analysis
   • Migration steps and validation
   • Rollback procedures

Phase 4: Extension to Other Charts

1. hyperswitch-card-vault integration

   • PCI-compliance considerations
   • Encrypted secret handling

2. hyperswitch-keymanager integration

   • Key rotation strategies
   • High-security secret management

Additional Information

Related External Secrets Operator Resources

• External Secrets Operator Documentation
• AWS Provider Guide
• Vault Provider Guide
• Azure Provider Guide

Security Compliance Benefits

• SOC2 Type II compliance support
• PCI-DSS Level 1 requirements adherence
• GDPR data protection improvements
• Enterprise audit trail capabilities

Performance Considerations

• Configurable refresh intervals to balance security and performance
• Efficient secret caching strategies
• Minimal impact on chart installation time

Testing Strategy

• Unit tests for template rendering with external secrets enabled/disabled
• Integration tests with mock secret providers
• End-to-end tests with actual secret manager services
• Performance benchmarks for secret retrieval

Labels: feature, security, enhancement, documentation
Priority: high
Complexity: large
Dependencies: External Secrets Operator