DOCSEARCHbyAlgolia
Submit Docs

Vault Secrets Operator

repository·main·Indexed 19 days ago

https://github.com/hashicorp/vault-secrets-operator

The Vault Secrets Operator (VSO) enables Kubernetes Pods to consume Vault secrets natively by synchronizing Vault secret data into Kubernetes Secrets via Custom Resource Definitions (CRDs) such as VaultStaticSecret, VaultDynamicSecret, and VaultPKISecret. It supports all Vault secret engines, automatic secret rotation for specific Kubernetes resource types, and provides a CSI driver for mounting ephemeral volumes directly to containers.

Tokens
23K
Snippets
40
Records
72
Agent score
70%

What's inside Vault Secrets Operator

  1. Features of the Vault Secrets Operator

    main

    The Vault Secrets Operator supports the following capabilities:

    • Secret Engines: Support for all Vault secret engines.
    • Communication: TLS/mTLS communications with Vault.
    • Authentication: Uses the Kubernetes Auth Method, allowing the requesting Pod to authenticate via its ServiceAccount.
    • Synchronization: Syncing Vault Secrets to Kubernetes Secrets.
    • Rotation: Automatic secret rotation for Deployment, ReplicaSet, and StatefulSet Kubernetes resource types.
    • Monitoring: Prometheus instrumentation for monitoring the Operator.
    • Installation: Supported via Helm and Kustomize.

  2. How data flows in the Vault Secrets Operator

    main

    The Vault Secrets Operator facilitates the movement of secret material from Vault into Kubernetes. The data flow follows these steps:

    1. Authentication: The Operator sends authentication data (like Kubernetes service account tokens) to Vault and receives Vault tokens and secrets in return.
    2. Caching (Optional): The Operator can store and retrieve these Vault tokens and secrets in Kubernetes Secrets (the Client Cache) within its own namespace.
    3. Secret Retrieval & Storage: The Operator requests authentication data from the Kubernetes API Server and sends the retrieved Vault secrets back to the API Server to be stored as Kubernetes Secrets.
    4. Persistence: The API Server stores these secrets in etcd.
    5. Consumption: Workload pods consume the secrets by mounting them as files in an ephemeral volume, using them as environment variables, or querying the Kubernetes API directly.

  3. Top-level configuration stanzas for the Vault Secrets Operator

    main

    The Helm chart configuration is divided into several primary sections (stanzas). Use these keys in your values.yaml to configure the following components:

    • controller: Configuration for the main operator controller.
    • metricsService: Configuration for the metrics service used for observability.
    • defaultVaultConnection: Settings for the default connection to a Vault instance.
    • defaultAuthMethod: Settings for the default authentication method used by the operator.
    • tests: Configuration related to Helm chart tests.

  4. Use SecretTransformation to transform secret data

    main

    The SecretTransformation resource allows you to manipulate secret data before it is stored in a destination (like a CSI volume). It uses Go text templates.

    Key components:

    • templates: A map of template names to Template objects. These are always included in the rendered secret using the specified key.
    • sourceTemplates: A list of SourceTemplate objects used for common definitions. These are never included in the final rendered secret.
    • includes: A regex pattern array used to filter top-level source secret fields for inclusion. Applied after templating.
    • excludes: A regex pattern array used to filter top-level source secret fields for exclusion. Applied before inclusion patterns. Use [ ".*" ] to exclude all source data.

    Template Syntax: Templates use the Go text/template format and reference attributes from the source secret's data structure.

    apiVersion: secrets.hashicorp.com/v1beta1
kind: SecretTransformation
metadata:
  name: my-transform
spec:
  templates:
    my-key:
      text: "password={{ .data.password }}"
  excludes:
    - ".*"

  5. Configure rollout restarts for rotated secrets

    main

    If your application does not support dynamically reloading rotated secrets, you can use RolloutRestartTarget to trigger a rolling restart of your workloads whenever a Vault secret changes.

    The Operator performs this by patching the target resource's spec.template.metadata.annotations with the annotation vso.secrets.hashicorp.com/restartedAt set to the current timestamp.

    Supported resource kinds:

    • Deployment
    • DaemonSet
    • StatefulSet
    • argo.Rollout
    # Example configuration within a spec
rolloutRestartTargets:
  - kind: Deployment
    name: my-app-deployment

  6. How the Vault Secrets Operator works

    main

    The Vault Secrets Operator (VSO) synchronizes Vault secrets into Kubernetes Secrets. It works by watching specific Custom Resource Definitions (CRDs) that define the requirements for synchronization.

    The Workflow:

    1. The Operator watches for changes to its supported CRDs.
    2. The Source is a secret stored in Vault.
    3. The Destination is a Kubernetes Secret.
    4. The Operator writes the source data directly to the destination, ensuring that any updates in Vault are replicated to the Kubernetes Secret.

    This allows applications to consume secrets natively using standard Kubernetes Secret mechanisms without needing direct access to Vault.

  7. Configure the Client Cache for Vault Tokens

    main

    The controller.manager.clientCache settings manage how the operator caches and persists Vault tokens. This is particularly useful for Dynamic Secrets to enable token reuse and renewal.

    Persistence Models (persistenceModel):

    • none: In-memory cache only. No tokens are persisted.
    • direct-unencrypted: In-memory cache is persisted unencrypted. NOT recommended for production.
    • direct-encrypted: In-memory cache is persisted encrypted using the Vault Transit engine. Recommended for production.

    Encryption Requirements: If using direct-encrypted, you must provide storageEncryption configuration, which requires a Vault Transit engine setup. You must specify the keyName, mount (for Transit), and the VaultAuthMethod details (namespace, role, etc.) used to access the Transit engine.

    controller:
  manager:
    clientCache:
      persistenceModel: "direct-encrypted"
      cacheSize: 10000
      storageEncryption:
        keyName: "my-transit-key"
        mount: "transit"
        role: "operator-transit-role"
        # ... other required auth fields

  8. Understand Vault Secrets Operator terminology

    main

    The following terms are used when discussing the Vault Secrets Operator ecosystem:

    • Operator: The Vault Secrets Operator itself.
    • Vault: The HashiCorp Vault server(s) communicating with the Operator.
    • Cluster: The Kubernetes cluster where the Operator and workloads reside.
    • Secret CR: Custom Resources that define which secrets to sync, specifically VaultStaticSecret, VaultDynamicSecret, or VaultPKISecret.
    • Client Cache: An optional feature where the Operator stores Vault tokens and secrets in Kubernetes Secrets to maintain leases across Operator restarts or rollouts.

  9. How VaultAuthGlobal resources work

    main

    A VaultAuthGlobal resource allows you to share common authentication configuration across multiple VaultAuth resources. This reduces duplication and centralizes management of authentication parameters like mount, namespace, params, and headers.

    Referencing Global Config

    In a VaultAuth resource, you use a VaultAuthGlobalRef to point to a VaultAuthGlobal resource.

    Search and Namespace Behavior

    When a VaultAuth resource references a VaultAuthGlobal:

    • If a namespace is provided in the reference, the search is constrained to that namespace.
    • If no namespace is provided, the search order is:
      1. The default VaultAuthGlobal resource in the referring VaultAuth resource's namespace.
      2. The default VaultAuthGlobal resource in the Operator's namespace.

    Merge Strategy

    The VaultAuthGlobalRef includes a mergeStrategy field which configures how HTTP headers and parameters from the global resource are merged with those defined in the local VaultAuth resource.

    Default Globals

    If allowDefault is set to true in the reference, the operator will use the default VaultAuthGlobal resource if no specific name is provided. This requires the operator's -global-vault-auth-options flag to have allow-default-globals enabled.

  10. Enable drift detection and automatic rollout restarts

    main

    To ensure data consistency and handle secret rotation for applications that cannot reload secrets dynamically, use the following settings:

    1. Enable HMAC computation: Set hmacSecretData: true (this is the default). The Operator computes an HMAC of the secret data and stores it in Status.SecretMac. This is used for drift detection and comparing incoming Vault secrets.
    2. Configure Rollout Restarts: If your application does not support dynamic reloading, define rolloutRestartTargets. The Operator will trigger a rollout-restart for each target whenever the Vault secret changes.

    Note: All rolloutRestartTargets will be ignored if hmacSecretData is set to false.

  11. Use TransformationRef to share templates

    main

    A TransformationRef allows you to reference template configurations from a SecretTransformation resource. This enables sharing transformation logic across multiple syncable secret custom resources.

    Fields:

    • namespace: The namespace of the SecretTransformation resource.
    • name: The name of the SecretTransformation resource.
    • templateRefs: An array of TemplateRef objects. If this array is empty, all templates from the referenced SecretTransformation will be rendered into the Kubernetes Secret.
    • ignoreIncludes: If true, the Includes data key filters from the SecretTransformation are ignored.
    • ignoreExcludes: If true, the Excludes data key filters from the SecretTransformation are ignored.