- Configuration reference: The
external-secrets.io/v1API. - Live validation: ESO
0.16.2and Vault2.2.2on a local kind cluster, covering Kubernetes authentication, KV version 2 synchronization, private CA trust, force-sync rotation, and the Helm values path.
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.
Before you begin
Complete the common ESO controller, webhook, CRD, namespace, and permission checks first. For more information, see 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.
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.
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.
These examples use namespace qodo. Select your context and replace the
namespace consistently:
1. Prepare the source secret and permissions
Using your approved secret-management process, create KV secretqodo-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:
qodo-secrets-read.hcl
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.
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:
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
and Vault namespaces.
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.
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
and 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.vault-secret-store.yaml
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.
namespace. ESO uses it
for both sign-in and secret reads unless you set a separate
auth.namespace. For more information, see 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: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.
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.
To refresh sooner after a rotation, change the force-sync annotation. For
more information, see Can I manually trigger a secret refresh?
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. Addnamespace 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.
eso-vault-values.yaml
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.
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.
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 and kstatus Ready condition.
Troubleshoot Vault access
Related resources
- Manage Qodo secrets with External Secrets Operator: Apply the shared ownership, rotation, and recovery procedure.
- HashiCorp Vault provider: Review other authentication methods and KV version 1 options.
- Kubernetes auth method: Configure token review, roles, and audiences in Vault.