Skip to main content
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.

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.
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. 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 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:
qodo-secrets-read.hcl
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. 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:
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 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.
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. 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:
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. 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?
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.
eso-vault-values.yaml
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. 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