Deviqon Labs
News08 Mar 2026

GitOps Secret Management with HashiCorp Vault, ESO, and ArgoCD

If you are using the ArgoCD Vault Plugin, your injected secrets are sitting unencrypted in a Redis cache. Here is the production-grade GitOps architecture using the External Secrets Operator to keep your values out of Git, and out of ArgoCD.

RR
Robert RotterDeviqon Labs
Share
GitOps Secret Management with HashiCorp Vault, ESO, and ArgoCD

If you're running ArgoCD and storing secrets in your Git repository, even encrypted ones, you're one compromised repo away from a bad day. This article walks through a production-grade approach to secret management using HashiCorp Vault and the External Secrets Operator (ESO), using Harbor (a container registry) with an external Redis HA cluster as a real-world example.


The Problem with Secrets in GitOps

GitOps is built on a simple premise: Git is the source of truth. Everything declarative, everything auditable, everything reproducible. That works beautifully, until secrets enter the picture.

The naive approach is to store secrets directly in Git. This is obviously wrong. The slightly less naive approach is to encrypt them with something like Sealed Secrets or SOPS. Better, but you've now introduced a new problem: the encryption key itself needs to be managed, rotated, and protected. You've moved the problem, not solved it.

The correct approach is to never store secret values in Git at all. Store only the references to secrets. The actual values live in a dedicated secret management system, in our case, HashiCorp Vault.


Why Not ArgoCD's Built-in Secret Injection?

ArgoCD has a plugin ecosystem, and the most popular option for Vault integration is argocd-vault-plugin (AVP). It works by replacing <placeholder> patterns in manifests at sync time with values pulled from Vault.

ArgoCD's own documentation explicitly cautions against this approach for three reasons:

Security: ArgoCD needs direct access to the secrets to inject them. More critically, ArgoCD stores generated manifests in plaintext in its Redis cache. That means your secrets are sitting in Redis, unencrypted.

Operational coupling: Secret updates are tied to ArgoCD sync operations. Rotating a secret means triggering a sync, which may also apply unrelated infrastructure changes at the same time.

Pattern incompatibility: AVP is incompatible with the Rendered Manifests pattern, which is increasingly becoming the standard for GitOps at scale.

The better architecture keeps ArgoCD completely out of the secrets business. ArgoCD syncs manifests. A separate operator (ESO) handles secret synchronization. They don't interfere with each other.


Architecture Overview

1Git Repository
2 └── ExternalSecret manifests (references only, no values)
3 └── ArgoCD Application manifests
4
5ArgoCD
6 └── Syncs ExternalSecret/ClusterExternalSecret CRDs to cluster
7
8External Secrets Operator (ESO)
9 └── Watches ExternalSecret resources
10 └── Authenticates to Vault via Kubernetes auth
11 └── Pulls secret values from Vault KV
12 └── Creates/updates Kubernetes Secrets
13
14HashiCorp Vault
15 └── infra/ KV v2 mount
16 ├── harbor/config
17 └── redis/config
18
19Applications (Harbor, etc.)
20 └── Reference Kubernetes Secrets normally
21 └── Never know Vault exists

The key insight: your application manifests reference ordinary Kubernetes Secrets. ESO is responsible for keeping those Secrets populated with current values from Vault. ArgoCD is responsible for keeping the ESO resources (ExternalSecret, ClusterExternalSecret) in sync with Git. Everyone does their job.


Prerequisites

  • A running Kubernetes cluster
  • ArgoCD installed and configured
  • HashiCorp Vault installed (in-cluster or external)
  • kubectl access to the cluster

Step 1: Deploy External Secrets Operator via ArgoCD

The official ESO Helm chart is published at https://charts.external-secrets.io. The ArtifactHub package to use is external-secrets/external-secrets-operator.

Deploy it as an ArgoCD Application:

1apiVersion: argoproj.io/v1alpha1
2kind: Application
3metadata:
4 name: external-secrets
5 namespace: argocd
6spec:
7 destination:
8 namespace: external-secrets
9 server: https://kubernetes.default.svc
10 project: deviqon
11 source:
12 chart: external-secrets
13 helm:
14 values: |-
15
16 repoURL: https://charts.external-secrets.io
17 targetRevision: '*'
18 syncPolicy:
19 automated:
20 prune: true
21 selfHeal: true
22 syncOptions:
23 - CreateNamespace=true

This installs ESO into the external-secrets namespace and creates the necessary CRDs, including ExternalSecret, ClusterExternalSecret, SecretStore, and ClusterSecretStore.


Step 2: Create a Dedicated KV Mount in Vault

Vault organizes secrets into mounts. Rather than dumping infrastructure secrets into an existing shared secret/ KV mount used by other teams, create a dedicated mount for infrastructure secrets.

This matters for three reasons: policy scoping is cleaner (you can write path "infra/*" instead of path "secret/data/infra/*"), mount-level settings (TTLs, audit) are independent, and you can nuke the entire mount cleanly if needed.

Via the Vault API:

1curl --header "X-Vault-Token: <your-token>" \
2 --request POST \
3 --data '{"type": "kv", "options": {"version": "2"}}' \
4 http://vault:8200/v1/sys/mounts/infra

Or via the Vault UI: Secrets → Enable new engine → KV → path: infra → Version 2.

Secret Path Structure

Mirror your ArgoCD application names exactly. This removes all ambiguity when mapping an ArgoCD app to its Vault path:

1infra/
2├── harbor/
3│ └── config # harborAdminPassword, s3 keys, etc.
4├── redis/
5│ └── config # password, sentinel credentials
6├── cert-manager/
7│ └── config
8└── ingress-nginx/
9 └── config

Key Naming Convention

Use camelCase key names that match the values.yaml keys of the Helm chart consuming them. This enables dataFrom: extract to pull all keys from a path without any explicit mapping, reducing boilerplate. For example, Harbor's Helm chart expects harborAdminPassword, so store it with that exact key in Vault.


Step 3: Configure Vault Kubernetes Auth Method

ESO authenticates to Vault using Kubernetes service account tokens. Vault verifies these tokens against the Kubernetes TokenReview API. This eliminates the need for any static credentials.

Enable and Configure the Auth Method

1# Enable Kubernetes auth (if not already enabled)
2vault auth enable kubernetes
3
4# Configure it, since Vault runs inside the cluster,
5# it can auto-discover the CA cert and service account token
6vault write auth/kubernetes/config \
7 kubernetes_host="https://kubernetes.default.svc"

Create a Vault Policy

The policy defines what ESO is allowed to read. Scope it tightly to the infra/ mount only:

1# eso-infra-policy.hcl
2path "infra/data/*" {
3 capabilities = ["read"]
4}
5
6path "infra/metadata/*" {
7 capabilities = ["read", "list"]
8}

Note the infra/data/* path, KV v2 always stores values under a /data/ prefix internally, even though the CLI and UI hide this from you. ESO talks to the raw API, so the policy must include it.

1vault policy write eso-infra-policy eso-infra-policy.hcl

Create a Kubernetes Auth Role

The role binds a Kubernetes service account to a Vault policy:

1vault write auth/kubernetes/role/eso-infra-role \
2 bound_service_account_names="external-secrets" \
3 bound_service_account_namespaces="external-secrets" \
4 policies="eso-infra-policy" \
5 ttl="1h"

This says: if a request comes from the external-secrets service account in the external-secrets namespace, issue a Vault token with eso-infra-policy attached.

The Auth Flow

1ESO Pod (SA: external-secrets, NS: external-secrets)
2 │
3 │ presents Kubernetes JWT token + role name
4 ▼
5Vault Kubernetes Auth Method
6 │ verifies JWT against Kubernetes TokenReview API
7 │ matches SA + namespace to eso-infra-role
8 │ attaches eso-infra-policy
9 ▼
10Vault Token issued to ESO
11 │
12 ▼
13ESO reads infra/* paths
14 │
15 ▼
16Kubernetes Secrets created in target namespaces

Step 4: Deploy the ClusterSecretStore

The ClusterSecretStore is a cluster-scoped resource that tells ESO how to connect to and authenticate with Vault. It's the bridge between ESO and Vault, referenced by all ExternalSecret and ClusterExternalSecret resources.

1apiVersion: external-secrets.io/v1
2kind: ClusterSecretStore
3metadata:
4 name: vault-infra
5spec:
6 provider:
7 vault:
8 server: "http://vault.vault.svc.cluster.local:8200"
9 path: "infra"
10 version: "v2"
11 auth:
12 kubernetes:
13 mountPath: kubernetes
14 role: eso-infra-role
15 serviceAccountRef:
16 name: external-secrets
17 namespace: external-secrets
18 audiences:
19 - vault

A few things worth noting here:

server: Use the full cluster-internal DNS name (vault.vault.svc.cluster.local). Using just vault:8200 only works if ESO and Vault are in the same namespace, they're not.

path: This is your KV mount name (infra), not a full secret path.

namespace on serviceAccountRef: Required when using ClusterSecretStore because it's cluster-scoped and has no implicit namespace. Without it, ESO won't know where to find the service account.

audiences: If set, ESO will request a Kubernetes token with this audience claim. The Vault role must be configured with the matching audience. If you're not enforcing audience validation, omit this field entirely.

status.capabilities: ReadWrite: You'll see this in the resource status. It's informational, it means ESO could write to Vault if asked (via PushSecret). Your actual permissions are enforced by the Vault policy, not this field.


Step 5: Store Secrets in Vault

Before creating ExternalSecrets, populate Vault with the actual values.

For Harbor:

1Path: infra/harbor/config
2Keys:
3 harborAdminPassword = <your-admin-password>

For Redis:

1Path: infra/redis/config
2Keys:
3 password = <your-redis-password>

Step 6: Create ExternalSecret Resources

Harbor-Specific Secrets

Harbor's admin password belongs to Harbor. Nothing else needs it. Use a standard namespaced ExternalSecret:

1apiVersion: external-secrets.io/v1
2kind: ExternalSecret
3metadata:
4 name: harbor-secrets
5 namespace: harbor
6spec:
7 refreshInterval: 1h
8 secretStoreRef:
9 name: vault-infra
10 kind: ClusterSecretStore
11 target:
12 name: harbor-secrets
13 dataFrom:
14 - extract:
15 key: harbor/config

dataFrom: extract pulls all key/value pairs from infra/harbor/config and creates them as keys in the resulting Kubernetes Secret. No explicit field mapping needed when key names match what the Helm chart expects.

Shared Redis Credentials

Redis credentials are used by multiple applications, Harbor, and potentially others. The right resource here is ClusterExternalSecret, which creates the same secret in multiple namespaces from a single definition:

1apiVersion: external-secrets.io/v1
2kind: ClusterExternalSecret
3metadata:
4 name: redis-secrets
5spec:
6 namespaces:
7 - harbor
8 - redis
9 refreshTime: 1m
10 externalSecretSpec:
11 refreshInterval: 1h
12 secretStoreRef:
13 name: vault-infra
14 kind: ClusterSecretStore
15 target:
16 name: redis-secrets
17 dataFrom:
18 - extract:
19 key: redis/config

refreshTime (on ClusterExternalSecret): How often ESO checks that the ExternalSecret objects exist in the listed namespaces. Keep this short (1m).

refreshInterval (inside externalSecretSpec): How often the secret value is actually fetched from Vault. Set this based on your rotation frequency, 1h is a reasonable default.

When you add a new application that needs Redis, add its namespace to the list. One Vault path, one ClusterExternalSecret, N namespaces.


Step 7: Update Harbor ArgoCD Application

With ESO creating the secrets, update the Harbor ArgoCD Application to reference them by name instead of embedding values:

1apiVersion: argoproj.io/v1alpha1
2kind: Application
3metadata:
4 name: harbor
5 namespace: argocd
6spec:
7 destination:
8 namespace: harbor
9 server: https://kubernetes.default.svc
10 project: default
11 source:
12 chart: harbor
13 helm:
14 values: |-
15 existingSecretAdminPassword: "harbor-secrets"
16 existingSecretAdminPasswordKey: harborAdminPassword
17
18 persistence:
19 enabled: true
20 persistentVolumeClaim:
21 registry:
22 existingClaim: "harbor-registry-pvc"
23 jobservice:
24 jobLog:
25 existingClaim: "harbor-jobservice-pvc"
26 database:
27 existingClaim: "harbor-database-pvc"
28 trivy:
29 existingClaim: "harbor-trivy-pvc"
30
31 database:
32 internal:
33 livenessProbe:
34 timeoutSeconds: 10
35 readinessProbe:
36 timeoutSeconds: 10
37
38 expose:
39 type: ingress
40 tls:
41 enabled: true
42 certSource: secret
43 secret:
44 secretName: "harbor.example.com-tls"
45 ingress:
46 hosts:
47 core: harbor.example.com
48 className: "internal-nginx"
49 annotations:
50 forecastle.stakater.com/expose: "true"
51 forecastle.stakater.com/group: "myorg"
52 cert-manager.io/cluster-issuer: example-com-issuer
53 kubernetes.io/tls-acme: "true"
54 nginx.ingress.kubernetes.io/ssl-passthrough: "false"
55 nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
56 labels: {}
57 externalURL: https://harbor.example.com
58
59 redis:
60 type: external
61 external:
62 addr: "redis-ha-server-0.redis-ha.redis.svc.cluster.local:26379,redis-ha-server-1.redis-ha.redis.svc.cluster.local:26379,redis-ha-server-2.redis-ha.redis.svc.cluster.local:26379"
63 sentinelMasterSet: "mymaster"
64 coreDatabaseIndex: "10"
65 jobserviceDatabaseIndex: "11"
66 registryDatabaseIndex: "12"
67 trivyAdapterIndex: "13"
68 harborDatabaseIndex: "14"
69 cacheLayerDatabaseIndex: "15"
70 existingSecret: "redis-secrets"
71
72 repoURL: https://helm.goharbor.io
73 targetRevision: '*'
74 syncPolicy:
75 automated:
76 prune: true
77 selfHeal: true
78 syncOptions:
79 - CreateNamespace=true

Harbor reads existingSecretAdminPassword: "harbor-secrets" and looks for a Kubernetes Secret named harbor-secrets in its namespace. ESO created that secret from Vault. Harbor never knows where the value came from.


Common Pitfalls

These are real errors encountered during this setup, in the order they appeared.

1. ServiceAccount Not Found

1error: cannot get Kubernetes service account "external-secrets":
2ServiceAccount "external-secrets" not found

Cause: ClusterSecretStore is cluster-scoped and has no implicit namespace. The serviceAccountRef field needs an explicit namespace.

Fix: Add namespace: external-secrets to serviceAccountRef:

1serviceAccountRef:
2 name: external-secrets
3 namespace: external-secrets # required for ClusterSecretStore

2. InvalidProviderConfig / Store Not Ready

1StatusInvalidProviderConfig
2Ready: False

Cause: ESO validated the ClusterSecretStore config before Kubernetes auth was fully configured in Vault, or the serviceAccountRef namespace was missing (see above).

Fix: Ensure the Vault Kubernetes auth method is configured and the role exists before applying the ClusterSecretStore. After fixing config, delete and reapply the resource to force revalidation.

3. Vault Returns 500: Could Not Load Backend Configuration

1unable to log in with Kubernetes auth: Code: 500
2* could not load backend configuration

Cause: The Kubernetes auth method was enabled in Vault but never configured. vault auth enable kubernetes alone is not enough, you must also run vault write auth/kubernetes/config.

Fix:

1kubectl exec -it vault-0 -n vault -- vault write auth/kubernetes/config \
2 kubernetes_host="https://kubernetes.default.svc"

Since Vault runs inside the cluster, it auto-discovers the CA cert and service account token. You only need to provide kubernetes_host.

4. Wrong Vault Server URL

Using http://vault:8200 in the ClusterSecretStore server field only works if ESO and Vault are in the same namespace. They aren't, ESO runs in external-secrets, Vault in vault.

Fix: Use the full cluster DNS name:

1server: "http://vault.vault.svc.cluster.local:8200"

Format: http://<service-name>.<namespace>.svc.cluster.local:<port>

5. CRDs Not Ready at Startup

1no matches for kind "ClusterSecretStore" in version "external-secrets.io/v1"

Cause: ESO pods started before the CRDs were fully registered. This is a race condition that happens on fresh installs.

Fix: This is transient. ESO will retry automatically every 10 seconds until the CRDs are available. No action needed, it resolves itself within a minute.

6. Audience Mismatch

If you configure audiences: ["vault"] in the ClusterSecretStore but the Vault role doesn't have a matching audience set, authentication will silently fail during store validation.

Fix: Either remove audiences entirely (simplest), or set the matching audience on the Vault role:

1vault write auth/kubernetes/role/eso-infra-role \
2 bound_service_account_names="external-secrets" \
3 bound_service_account_namespaces="external-secrets" \
4 policies="eso-infra-policy" \
5 audience="vault" \
6 ttl="1h"

7. KV v2 Policy Path

Vault KV v2 stores data under a hidden /data/ path prefix. If your policy uses path "infra/*" instead of path "infra/data/*", reads will be denied even though the path looks correct.

Fix: Always include /data/ and /metadata/ in KV v2 policies:

1path "infra/data/*" {
2 capabilities = ["read"]
3}
4
5path "infra/metadata/*" {
6 capabilities = ["read", "list"]
7}

Secret Ownership Model

A pattern worth establishing early: secrets are owned by the service that defines them, not the service that consumes them.

  • infra/redis/config is owned by Redis. Harbor consumes it via ClusterExternalSecret.
  • infra/harbor/config is owned by Harbor. Nothing else touches it.

This maps cleanly to the ESO resource types:

Secret typeESO resourceExample

App-specific

ExternalSecret (namespaced)

Harbor admin password

Shared across apps

ClusterExternalSecret

Redis password

When you need to add a 9th app that uses Redis, you add its namespace to the ClusterExternalSecret. You do not create a new secret path in Vault. One source of truth, one rotation point.


What's in Git vs What's in Vault

1Git (safe to commit, no secret values):
2 ├── ArgoCD Application manifests
3 ├── ClusterSecretStore
4 ├── ExternalSecret manifests
5 └── ClusterExternalSecret manifests
6
7Vault (never in Git):
8 ├── infra/harbor/config → harborAdminPassword = <value>
9 └── infra/redis/config → password = <value>

If your Git repository was fully public tomorrow, nothing sensitive would be exposed.


Conclusion

The setup involves more moving parts than hardcoding secrets into Helm values, but the operational benefits are significant: no secrets in Git history, centralized rotation, fine-grained access policies, and a clean separation between ArgoCD (delivery) and ESO (secret lifecycle).

The ArgoCD vault plugin is the easier path initially, but the Redis cache exposure alone makes it a non-starter for production. ESO with Vault KV gives you the same developer experience, reference a secret by name in your Helm values, without the security tradeoffs.

Once the ClusterSecretStore is wired up and working, adding secrets for a new application is three steps: write the value to Vault, create an ExternalSecret manifest, commit it to Git. ArgoCD picks it up, ESO creates the Kubernetes Secret, your app gets its credentials. No plaintext anywhere.

From Theory to Practice

By implementing these Vault configurations and adhering to the External Secrets Operator lifecycle, you ensure your GitOps infrastructure operates exactly as securely as designed, with zero plaintext exposure. If your project faces a unique architectural challenge, our senior specialists are ready to help.

Contact us to discuss your project.