> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qodo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use HashiCorp Vault

> Connect External Secrets Operator to a HashiCorp Vault KV version 2 secrets engine with Kubernetes authentication.

On-premises

* **Configuration reference**: The `external-secrets.io/v1` API.
* **Live validation**: ESO `0.16.2` and Vault `2.2.2` on a local kind cluster, covering Kubernetes authentication, KV version 2 synchronization, private CA trust, force-sync rotation, and the Helm values path.

Use this page to create the `qodo-secrets` store consumed by the shared Qodo
Secret examples. ESO signs in to Vault with a short-lived Kubernetes service
account token. Qodo application Pods continue to read Kubernetes Secrets and
do not need Vault tokens, Vault Agent, or the Vault Secrets Operator. For more
information, see [Manage Qodo secrets with External Secrets Operator](https://docs.qodo.ai/on-prem/external-secrets.md).

## Before you begin

Complete the common ESO controller, webhook, CRD, namespace, and permission
checks first. For more information, see [Before you begin](https://docs.qodo.ai/on-prem/external-secrets.md#before-you-begin).

Prepare:

* A Vault server that ESO can reach over HTTPS, and its CA certificate if Vault uses a private certificate authority.
* A KV version 2 secrets engine. These examples use the mount path `secret`.
* The Kubernetes auth method enabled and configured for this cluster. These examples use the mount path `kubernetes`.
* A Vault administrator who can create a policy and a Kubernetes auth role.
* For Vault Enterprise or HCP Vault Dedicated: The Vault namespace that contains the KV mount, and the auth method's namespace if it differs.
* ESO permission to request tokens for the referenced Kubernetes service account.

Vault validates each service account token through the Kubernetes TokenReview
API. Configure the auth method with your cluster's API server address and a
token reviewer identity that has the `system:auth-delegator` ClusterRole. When
Vault runs inside this cluster, it can use its own Pod's service account token
and CA certificate. Otherwise, also configure the cluster's CA certificate and
a reviewer token. For other reviewer options, see
[How to work with short-lived Kubernetes tokens](https://developer.hashicorp.com/vault/docs/auth/kubernetes#how-to-work-with-short-lived-kubernetes-tokens).

This example references a dedicated Kubernetes service account. ESO requests a
short-lived token for it on each sign-in, so the cluster stores no long-lived
Vault token or AppRole secret ID. If you already have an approved store, reuse
it and update the shared `ExternalSecret`'s `secretStoreRef` instead of
creating another identity. For more information, see [Kubernetes authentication](https://external-secrets.io/latest/provider/hashicorp-vault/#kubernetes-authentication).

These examples use namespace `qodo`. Select your context and replace the
namespace consistently:

```bash theme={null}
KUBE_CONTEXT="REPLACE_WITH_YOUR_CONTEXT"
NAMESPACE=qodo
```

## 1. Prepare the source secret and permissions

Using your approved secret-management process, create KV secret
`qodo-database` on the `secret` mount. It must contain the key
`POSTGRES_PASSWORD` with the existing database password. Each key in a KV
secret is a property that an `ExternalSecret` can select. Keep the value out of
Git, Helm values, shell arguments, and chat.

Save this read-only policy as `qodo-secrets-read.hcl`:

```hcl qodo-secrets-read.hcl theme={null}
# Read the current version of each Qodo source secret on KV v2 mount "secret".
path "secret/data/qodo-database" {
  capabilities = ["read"]
}
```

Add a `path` block for each additional source secret your ExternalSecrets read,
such as `qodo-bedrock`, `qodo-embeddings`, or `qodo-image-pull`. KV version 2
policy paths include the `data/` segment. ExternalSecret keys do not. For more
information, see [Update ACL rules](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2/upgrade#step-1-update-acl-rules).

Have your Vault administrator create the policy and a role bound to the
service account used in the next step. `NAMESPACE` is your Helm release
namespace, set in [Before you begin](#before-you-begin):

```bash theme={null}
vault policy write qodo-secrets-read qodo-secrets-read.hcl

vault write auth/kubernetes/role/qodo-secrets \
  bound_service_account_names=qodo-secrets-reader \
  bound_service_account_namespaces="$NAMESPACE" \
  audience=vault \
  token_policies=qodo-secrets-read \
  token_ttl=20m
```

For Vault Enterprise or HCP Vault Dedicated, run these commands in the
namespace that contains the Kubernetes auth method, for example by setting
`VAULT_NAMESPACE`. ESO signs in to the store's `auth.namespace`, or to its
`namespace` when `auth.namespace` is not set. These examples assume the auth
method and the KV mount share one namespace. If they don't, have your Vault
administrator grant the role's tokens read access to the KV namespace. For more
information, see [Vault CLI namespace](https://developer.hashicorp.com/vault/docs/commands#global-namespace)
and [Vault namespaces](https://developer.hashicorp.com/vault/docs/enterprise/namespaces).

| Role setting | Value |
| - | - |
| `bound_service_account_names` and `bound_service_account_namespaces` | The service account `qodo-secrets-reader` in your Helm release namespace |
| `audience` | `vault`, matching the store's `serviceAccountRef.audiences`. Vault then accepts only tokens whose audience claim includes it. See [Kubernetes auth role audience](https://developer.hashicorp.com/vault/api-docs/auth/kubernetes#audience). |
| `token_policies` | The read-only policy above |
| `token_ttl` | A short lifetime. ESO revokes its Vault token after each reconciliation unless the ESO controller runs with `--experimental-enable-vault-token-cache`. See [ESO Vault client](https://github.com/external-secrets/external-secrets/blob/v0.16.2/pkg/provider/vault/client.go#L120-L130). |

If Argo CD manages an installation that uses component namespaces, each
namespace that needs a Secret also needs a store that Vault accepts. Either
create the service account and store in each of those namespaces and list them
all in `bound_service_account_namespaces`, separated by commas, or use an
approved `ClusterSecretStore`. For more information, see [Manage Qodo secrets with External Secrets Operator](https://docs.qodo.ai/on-prem/external-secrets.md#before-you-begin).

Keep Vault's `default` policy attached to the role's tokens. Do not set
`token_no_default_policy=true`: ESO checks the store by looking up its own
token, and the `default` policy grants that lookup. For more information, see
[ESO Vault store validation](https://github.com/external-secrets/external-secrets/blob/v0.16.2/pkg/provider/vault/validate.go#L166-L177)
and [Default policy](https://developer.hashicorp.com/vault/docs/concepts/policies#default-policy).
If your auth method uses a mount path other than `kubernetes`, use it in both
the role path and the store.

## 2. Configure the service account and store

Replace the Vault address before applying. The service account needs no
mounted token because ESO requests one through the Kubernetes API.

```yaml vault-secret-store.yaml theme={null}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: qodo-secrets-reader
  namespace: qodo
automountServiceAccountToken: false
---
apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: qodo-secrets
  namespace: qodo
spec:
  provider:
    vault:
      server: https://REPLACE_WITH_VAULT_HOST:8200
      path: secret
      version: v2
      # Vault Enterprise or HCP Vault Dedicated only:
      # namespace: REPLACE_WITH_VAULT_NAMESPACE
      # Private certificate authority only:
      # caProvider:
      #   type: ConfigMap
      #   name: vault-ca
      #   key: ca.crt
      auth:
        kubernetes:
          mountPath: kubernetes
          role: qodo-secrets
          serviceAccountRef:
            name: qodo-secrets-reader
            audiences:
              - vault
```

`path` is the KV mount, and `version: v2` makes ESO add the `data/` segment
when it reads a secret. A `remoteRef.key` of `qodo-database` therefore reads
`secret/data/qodo-database`.

If Vault presents a certificate from a private certificate authority,
uncomment `caProvider` and create the ConfigMap in the Qodo namespace from the
public CA certificate file. A namespaced store can read the ConfigMap only from
its own namespace. For more information, see [ESO CAProvider](https://github.com/external-secrets/external-secrets/blob/v0.16.2/apis/externalsecrets/v1/secretstore_types.go#L237-L238).

```bash theme={null}
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" \
  create configmap vault-ca --from-file=ca.crt=vault-ca.pem
```

For Vault Enterprise or HCP Vault Dedicated, uncomment `namespace`. ESO uses it
for both sign-in and secret reads unless you set a separate
`auth.namespace`. For more information, see [Vault namespaces](https://external-secrets.io/latest/provider/hashicorp-vault/#vault-namespaces).

The example uses a namespaced store. If your existing configuration uses a
`ClusterSecretStore`, its service account reference also needs the account's
namespace. Keep the store's approved name and access scope.

## 3. Reconcile and verify

Apply the store and wait for it to report ready:

```bash theme={null}
kubectl --context "$KUBE_CONTEXT" apply \
  --dry-run=server -f vault-secret-store.yaml
kubectl --context "$KUBE_CONTEXT" apply -f vault-secret-store.yaml
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" \
  wait secretstore/qodo-secrets --for=condition=Ready --timeout=120s
```

For a new store, `Ready` confirms that ESO can sign in to Vault. After you
change an existing store, the condition can still describe the previous
settings until ESO reconciles the change. In both cases, `Ready` does not
confirm that the policy allows a particular secret. Apply the shared database
`ExternalSecret` next, and treat its successful refresh as the end-to-end
check. It reads property `POSTGRES_PASSWORD` from
`qodo-database` and writes the fixed `qodo-db-admin.POSTGRES_PASSWORD`
target. For more information, see [Manage Qodo secrets with External Secrets Operator](https://docs.qodo.ai/on-prem/external-secrets.md).

Verify the ExternalSecret's ready condition, refresh timestamp, target name,
and key names. Writing a new KV version does not notify ESO. With the default
refresh policy, ESO reads the source again at each `refreshInterval`. For more
information, see [Periodic refresh](https://external-secrets.io/latest/api/externalsecret/#periodic).

To refresh sooner after a rotation, change the `force-sync` annotation. For
more information, see [Can I manually trigger a secret refresh?](https://external-secrets.io/latest/introduction/faq/#can-i-manually-trigger-a-secret-refresh)

```bash theme={null}
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" \
  annotate externalsecret qodo-db-admin force-sync="$(date +%s)" --overwrite
```

Confirm the target updates before rolling out the affected consumer. Then
check that the upstream service accepts the credential and the relevant Qodo
flow still works.

## Configure the integration with Helm values

If your platform team manages ESO with Helm, merge this file into the
existing operator release's values. It creates the same ServiceAccount,
SecretStore, and database ExternalSecret as the manifests above. Use one
ownership path for each object. Do not apply the standalone manifests and
then try to create the same objects through Helm without a reviewed adoption.

Replace the Vault address after completing the Vault policy and role above.
Add `namespace` or `caProvider` under `vault` if your server needs them.
Replace namespace `qodo` with your Helm release namespace. The operator's
release namespace can remain `external-secrets`.

Download [`eso-vault-values.yaml`](https://docs.qodo.ai/examples/on-prem/eso-vault-values.yaml).

```yaml eso-vault-values.yaml theme={null}
# Values for your EXISTING External Secrets Operator Helm release, not Qodo.
# Merge with its full existing extraObjects list; Helm replaces lists.
extraObjects:
- apiVersion: v1
  kind: ServiceAccount
  metadata:
    name: qodo-secrets-reader
    namespace: qodo
  automountServiceAccountToken: false
- apiVersion: external-secrets.io/v1
  kind: SecretStore
  metadata:
    name: qodo-secrets
    namespace: qodo
  spec:
    provider:
      vault:
        server: https://REPLACE_WITH_VAULT_HOST:8200
        path: secret
        version: v2
        auth:
          kubernetes:
            mountPath: kubernetes
            role: qodo-secrets
            serviceAccountRef:
              name: qodo-secrets-reader
              audiences:
              - vault
- apiVersion: external-secrets.io/v1
  kind: ExternalSecret
  metadata:
    name: qodo-db-admin
    namespace: qodo
  spec:
    refreshInterval: 1h
    secretStoreRef:
      kind: SecretStore
      name: qodo-secrets
    target:
      name: qodo-db-admin
      creationPolicy: Orphan
      deletionPolicy: Retain
    data:
    - secretKey: POSTGRES_PASSWORD
      remoteRef:
        key: qodo-database
        property: POSTGRES_PASSWORD
```

Helm replaces the whole `extraObjects` list. Preserve unrelated entries
already managed by your ESO release in this same list. These are values for
ESO, not for the Qodo chart. The `extraObjects` field exists in the
ESO chart version linked below; check your pinned operator chart before
using it. For more information, see
[ESO Helm chart values](https://github.com/external-secrets/external-secrets/blob/v0.16.2/deploy/charts/external-secrets/values.yaml).

To reuse an existing store, omit the SecretStore and ServiceAccount entries
and set the ExternalSecret's `secretStoreRef` to your approved store's name
and kind. To stop managing this integration, transfer credential ownership
before removing these entries. For more information, see
[Configure Kubernetes add-ons with values files](https://docs.qodo.ai/on-prem/kubernetes-add-ons.md).

Reconcile the operator release through its existing Helm or GitOps process,
then wait for both `secretstore/qodo-secrets` and
`externalsecret/qodo-db-admin` to report `Ready` in the Qodo namespace.
If you changed an existing store, also change the ExternalSecret's
`force-sync` annotation and confirm a new refresh timestamp, because an
earlier `Ready` condition can describe the previous settings. Only then deploy
Qodo with `external-secrets-values.yaml` from the shared page.
Helm 3's `--wait` treats custom resources such as ExternalSecrets as ready
without checking them. In Helm 4, `--wait` uses a status watcher that reads
their `Ready` condition and fails the operator release upgrade if an ExternalSecret does
not become ready. Check readiness with `kubectl wait` either way. For more
information, see [Helm 3 readiness checks](https://github.com/helm/helm/blob/v3.22.1/pkg/kube/ready.go#L92-L204) and [kstatus Ready condition](https://github.com/fluxcd/cli-utils/blob/v1.2.2/pkg/kstatus/status/status.go#L141-L170).

## Troubleshoot Vault access

| Symptom | Check and recovery |
| - | - |
| Sign-in fails with `invalid role name` | Check that the store's `role` matches the Vault role name |
| Sign-in fails with `namespace not authorized` or `service account name not authorized` | Check the role's `bound_service_account_namespaces` and `bound_service_account_names` |
| Sign-in fails with `invalid audience (aud) claim` | Check that the store's `serviceAccountRef.audiences` includes the role's `audience` |
| Sign-in fails with `permission denied` | Check the store's `mountPath` against the Kubernetes auth method's mount path |
| Sign-in fails because the token cannot be reviewed | Check the auth method's Kubernetes API address and CA certificate, and that the reviewer identity has `system:auth-delegator` |
| ESO cannot request a token for `qodo-secrets-reader` | Check that the service account exists in the store's namespace and ESO can create service account tokens there |
| The store reports `invalid vault credentials` and `auth/token/lookup-self` returns `permission denied` | Check that the role's tokens keep Vault's `default` policy |
| The store is ready but the ExternalSecret reports `permission denied` | Check that the policy path includes `data/` and names the source secret |
| The ExternalSecret reports a missing secret or property | Check that `remoteRef.key` omits the mount and `data/`, the store uses `version: v2`, and the case-sensitive key exists in the current version |
| TLS errors such as `x509: certificate signed by unknown authority` | Configure `caProvider` with the CA that issued the Vault server certificate |
| Paths are not found on Vault Enterprise | Check the store's `namespace` and, if sign-in uses another namespace, `auth.namespace` |
| Requests time out | Check DNS, egress NetworkPolicy, firewalls, and proxies between ESO and Vault |

## Related resources

* [Manage Qodo secrets with External Secrets Operator](https://docs.qodo.ai/on-prem/external-secrets.md): Apply the shared ownership, rotation, and recovery procedure.
* [HashiCorp Vault provider](https://external-secrets.io/latest/provider/hashicorp-vault/): Review other authentication methods and KV version 1 options.
* [Kubernetes auth method](https://developer.hashicorp.com/vault/docs/auth/kubernetes): Configure token review, roles, and audiences in Vault.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.