External Secrets Store (Optional)

Connect Kindo to your organization’s central secrets store to manage application passwords and API keys there. Kindo stores these secrets in your Kubernetes cluster by default; follow this page when you choose an external store.

What you manage

Use an external store for values your organization chooses to manage centrally.

Kindo supplies values you leave out. Values added to the external store override the corresponding Kindo values.

Set up access to your store

Kindo installs and manages its own External Secrets Operator (ESO). If your cluster already runs ESO, it must serve external-secrets.io/v1 (ESO 0.17 or later); Kindo then uses it. This requirement applies to every backend, including kubernetes.

Create the authentication resources for the backend and auth mode you choose. The identity needs read access to the entries listed below. Reference the resources from the secretsStore block in install-contract.yaml.

Use the linked provider setup instructions for provider-specific steps.

Backend	Auth mode	You create
AWS Secrets Manager	authMode: irsa	The External Secrets Operator’s AWS identity
AWS Secrets Manager	authMode: access-key	A Kubernetes Secret in kindo-system named by credentialsSecretName, with access-key-id and secret-access-key keys
Azure Key Vault	authMode: workload-identity	A managed identity federated to the kindo-secret-store ServiceAccount in the kindo-system namespace; set clientId to its client ID
Azure Key Vault	authMode: service-principal	A Kubernetes Secret in kindo-system named by credentialsSecretName, with client-id and client-secret keys
Vault	authMethod: kubernetes	A Vault role bound to the kindo-secret-store ServiceAccount in the kindo-system namespace
Vault	authMethod: token	A Kubernetes Secret in kindo-system named by tokenSecretName, with a token key holding the Vault token

Create the entries

An entry is a named group of keys and values in your external store. Create these entries:

• api-env
• credits-env
• hatchet-env
• integrations-reconciler-hatchet
• litellm-env
• mcp-env
• mcp-platform-env
• mcp-unified-env
• nango-env
• next-env
• prisma-migrations-env
• sandbox-env
• task-worker-ts-env

You can leave application values out of these entries if you want Kindo to supply them. For AWS Secrets Manager and Azure Key Vault, create a secret whose value is the empty JSON object {}. For Vault, create a KV v2 secret with one placeholder key, such as KINDO_PLACEHOLDER=1; Vault requires at least one key.

Common values to store

You can store credentials that your organization already manages centrally. Add a shared value to every listed entry that consumes it. Use application database URLs and credentials in the external store. Keep bootstrap PostgreSQL administrator connections and the other required infrastructure bindings in environment-bindings.yaml.

Value	Keys	Store entries
PostgreSQL: Hatchet	DATABASE_URL	hatchet-env
PostgreSQL: LiteLLM	DATABASE_URL	litellm-env
PostgreSQL: Main	DATABASE_URL	api-env, credits-env, prisma-migrations-env, task-worker-ts-env
PostgreSQL: Main read connection	DATABASE_READ_URL	api-env
PostgreSQL: Nango	NANGO_DATABASE_URL	nango-env
PostgreSQL: OpenShell	DATABASE_URL	sandbox-env
RabbitMQ: API	RABBITMQ_URL	api-env
RabbitMQ: Hatchet	SERVER_TASKQUEUE_RABBITMQ_URL	hatchet-env
Redis	REDIS_URL	api-env, credits-env, task-worker-ts-env
S3 static credentials	AWS_ACCESS_KEY, AWS_SECRET_KEY	api-env, task-worker-ts-env
SMTP connection	SMTP_URL	nango-env
SMTP credentials	SMTP_USER, SMTP_PASSWORD	api-env, task-worker-ts-env

Point the install contract at the store

Replace the existing secretsStore block in install-contract.yaml with the example for your backend. Each example shows one auth mode. Fill in its values, then run kindo config validate.

AWS Secrets Manager

secretsStore:
  backend: 'aws'
  region: 'us-west-2'
  authMode: 'irsa'

For access-key authentication, replace authMode with authMode: "access-key" and add credentialsSecretName: "<secret-name>". With IRSA, roleArn is optional when you need to assume a different role.

Azure Key Vault

secretsStore:
  backend: 'azurekv'
  vaultUrl: 'https://your-vault.vault.azure.net'
  tenantId: '00000000-0000-0000-0000-000000000000'
  authMode: 'workload-identity'
  clientId: '<managed-identity-client-id>'

For service-principal authentication, replace authMode and clientId with authMode: "service-principal" and credentialsSecretName: "<secret-name>".

Vault

secretsStore:
  backend: 'vault'
  address: 'https://vault.example.com:8200'
  path: 'secret'
  authMethod: 'kubernetes'
  role: 'kindo'

For token authentication, replace authMethod and role with authMethod: "token" and tokenSecretName: "<secret-name>".

Install or upgrade

Prepare and check the required store entries before running kindo install --apply. A missing entry blocks its application.

Before applying an upgrade, run:

kindo upgrade --version <target> --plan

The plan checks whether the store is ready and reports any required key missing from both the store and Kindo’s supplied values. When the upgrade needs to install ESO, the plan reports that this check will run during --apply, after ESO and the store are installed. The upgrade stops before changing applications if the store check fails.

After installation, run kindo doctor to investigate application and store health. Continue when it reports no store or sync findings and the applications are healthy. Then complete Configure & Validate. See Operate for diagnosis and recovery commands.

What changes with an external store

• kindo config override set, unset, edit, and apply refuse to run. Manage those values in your external store.
• kindo config log-level set and unset refuse to run. See kindo config log-level to change the level.
• kindo config helm-override works with an external store.

See Operate for applying configuration changes.

Move an existing install onto an external store

1. Set up access and entries. Complete Set up access to your store and Create the entries.

2. Update the install contract. Replace secretsStore in install-contract.yaml with the configuration for your backend. If the contract sets applications.ssoready: true, remove SSOReady first.

3. Validate the configuration.

   kindo config validate

4. Review the upgrade plan. Use your currently installed version:

   kindo upgrade --version <current-version> --plan

5. Apply the upgrade.

   kindo upgrade --version <current-version> --apply

   The upgrade installs ESO and the store, checks the store, and stops before changing applications if the check fails.

Change a value later

Update a value your organization owns

Update the appropriate entry. For example, after updating a value in api-env, run:

kindo config apply --only api

The command waits for the sync before restarting the API. If the sync times out, it warns and restarts anyway. Run kindo doctor, resolve the sync finding, and rerun kindo config apply --only api.

Return a key to Kindo management

Remove the key from your external store to use Kindo’s value. After the change has synced, restart the affected application to pick it up.

For example, you can use kindo config apply --only api to wait for the sync and restart the API. If the command reports a sync timeout, resolve it and rerun the command.

Related: Operate and Upgrade.