How hashicorp/vault-secrets-operator works
Project Type and Purpose
• This is a Kubernetes operator – the Vault Secrets Operator – whose purpose is to monitor a set of Custom Resource Definitions (CRDs) (defined under the “api/v1beta1” directory and in configuration files under “config/crd” and “chart/crds”) to synchronize secrets from an external Vault secrets engine to Kubernetes Secrets.
• The operator supports various authentication methods, secret types (static and dynamic), credential integrations (AWS, GCP, Azure, HCP), and secret rotation capabilities.
Main Components
a. Kubernetes Cluster: Show the overall K8s environment where the operator runs.
b. Operator Pod: The central component that includes the operator’s main business logic. This encapsulates several sub-components:
• CRD Watchers & Controllers – the reconciliation loops implemented in the “controllers” directory (for example, hcpauth_controller, hcpvaultsecretsapp_controller, vaultauth_controller, etc.)
• API Definitions – found in the “api/v1beta1” directory to define the CRDs.
• Vault Client & Vault Integration – the “vault” package and related helper modules manage communication with Vault.
• Credentials Management – sub-modules under “credentials” that provide management and validation for various auth providers (e.g., Kubernetes, HCP, Vault’s AWS, GCP, Azure auth).
• Utilities and Helpers – the “helpers”, “common”, “consts”, and “internal” directories which provide shared functionality (logging, metrics, configuration, etc.).
d. Kubernetes Secrets: Display Kubernetes Secrets as the ultimate destination for the synchronized data.
e. Deployment & Configuration Resources: Show artifacts like Helm charts (in “chart”), Kustomize configurations (in “config”), and manifests that are used for deployment and customization.
f. Monitoring and Logging: Include Prometheus instrumentation (seen in RBAC setup and metrics-related templates) and logging components for tracking the operator’s activity.
Relationships and Data Flow
• That when a relevant CRD (for example, VaultStaticSecret, VaultDynamicSecret, VaultAuth, etc.) is created/modified, the operator’s controllers are triggered.
• How controllers use the API definitions to understand the desired state and then interact with the external Vault service via authenticated calls (using credentials patterns detailed under “credentials/vault”).
• Flow where data fetched from Vault is written into Kubernetes Secrets.
• Optionally, illustrate bidirectional feedback: The operator may adjust auxillary resources or update metrics/logs that are then collected by Prometheus and other monitoring tools.
Architectural Patterns and Design Principles
• Operator Pattern with a reconciliation loop that periodically checks the state of both Vault and Kubernetes.
• Usage of CRDs to extend Kubernetes’ API and support declarative management.
• Separation of concerns by grouping functionalities into distinct modules (controllers for business logic, credentials management for external auth integrations, and utility packages for common operations).