> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/guides-and-tutorials/data-platform/use-a-secrets-manager.md).

# Use a Secrets Manager

Keep the credentials of a self-hosted Soda Runner in HashiCorp Vault and sync them into Kubernetes with the External Secrets Operator, so that rotated passwords reach the runner without a redeploy.

A self-hosted Soda Runner connects to your data sources from your own Kubernetes cluster, so the data source credentials can stay in your environment. This guide keeps every credential the runner needs in HashiCorp Vault: the user name and password of the data source, and the runner's own API key. None of them appears in Soda Cloud or in the Helm values of the runner.

The [External Secrets Operator](https://external-secrets.io/latest/) (ESO) copies the credentials from Vault into Kubernetes secrets and reads Vault again at a set interval. The runner mounts the data source credentials into every job it starts, and the data source configuration in Soda Cloud refers to them as environment variables. When you rotate the password in Vault, the next job uses the new one.

{% hint style="info" %}
The self-hosted Soda Runner is available on license plans. Need access? [Contact us](mailto:support@soda.io).
{% endhint %}

The examples use a PostgreSQL database `sales_dw` with a read-only user `soda_reader`, and a runner in the namespace `soda-runner`. The setup has these parts:

| Part                      | Role                                                                                                           |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Vault                     | Holds the credentials under `secret/soda/` in a KV version 2 secrets engine                                    |
| `SecretStore`             | Tells ESO how to reach Vault and how to authenticate, here with an AppRole                                     |
| `ExternalSecret`          | Tells ESO which Vault secret to copy into which Kubernetes secret, and how often to refresh it                 |
| Soda Runner               | Reads its API key from one Kubernetes secret and mounts the data source credentials from another into its jobs |
| Data source in Soda Cloud | Refers to the credentials as `${env.POSTGRES_USER}` and `${env.POSTGRES_PASSWORD}`                             |

ESO supports other secrets managers, such as [AWS Secrets Manager](https://external-secrets.io/latest/provider/aws-secrets-manager/) and [Azure Key Vault](https://external-secrets.io/latest/provider/azure-key-vault/). With another provider, you store the credentials there and write a `SecretStore` for that provider; the runner and the data source configuration stay the same.

## Prerequisites

* A Kubernetes cluster, with `kubectl` and [Helm](https://helm.sh/docs/intro/install/) installed. See [Deploy a Soda Runner in a Kubernetes cluster](broken://spaces/A2PmHkO5cBgeRPdiPPOG/pages/Db0zxXDkPOUSKNNBuQXE) for the network access the runner needs.
* A Vault server that pods in the cluster can reach, with a [KV version 2](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) secrets engine mounted at `secret`, and the `vault` CLI logged in with permission to write policies and enable auth methods.
* A PostgreSQL database that the cluster can reach, with a read-only user for Soda. See [PostgreSQL](https://docs.soda.io/soda-documentation/developer-tools/data-source-reference-for-soda-core/postgresql.md) for the grants.
* In Soda Cloud, the global permission **Create data sources and manage runners**. See [Global and dataset roles](https://docs.soda.io/soda-documentation/govern/organization-and-admin-settings/global-and-dataset-roles.md).

{% hint style="info" %}
To try the setup without a Vault server, run Vault in [dev mode](https://developer.hashicorp.com/vault/docs/concepts/dev-server) in the cluster. A dev server keeps its data in memory, starts unsealed, and mounts KV version 2 at `secret`; the Helm chart sets its root token to `root`. Use it only to try things out.

```bash
helm repo add hashicorp https://helm.releases.hashicorp.com
helm install vault hashicorp/vault -n vault --create-namespace --set server.dev.enabled=true
kubectl -n vault port-forward svc/vault 8200:8200
```

In a second terminal, `export VAULT_ADDR=http://127.0.0.1:8200 VAULT_TOKEN=root`. In `secret-store.yml`, set `server` to `http://vault.vault.svc.cluster.local:8200`.
{% endhint %}

## Store the credentials in Vault

Store the user name and password of the database user in Vault. `read -rs` reads the password without showing it, and `password=-` makes Vault read it from standard input, so it does not end up in your shell history:

```bash
read -rs DB_PASSWORD
printf '%s' "$DB_PASSWORD" | vault kv put -mount=secret soda/sales-postgres username=soda_reader password=-
```

## Give ESO read access to Vault

Create a policy that can read the secrets under `secret/soda/`. With KV version 2, the policy path includes `data/`:

{% code title="soda-runner-read.hcl" %}

```hcl
path "secret/data/soda/*" {
  capabilities = ["read"]
}
```

{% endcode %}

Write the policy, enable the [AppRole auth method](https://developer.hashicorp.com/vault/docs/auth/approle), and create a role with the policy:

```bash
vault policy write soda-runner-read soda-runner-read.hcl
vault auth enable approle
vault write auth/approle/role/soda-runner token_policies=soda-runner-read token_ttl=1h token_max_ttl=4h
```

ESO logs in with the role ID and a secret ID of this role, and uses the token it receives to read the secrets.

## Install the External Secrets Operator

Install ESO with its Helm chart:

```bash
helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets external-secrets/external-secrets -n external-secrets --create-namespace --wait
```

The operator serves its resources in the API version `external-secrets.io/v1`.

## Sync the credentials into Kubernetes

Create the namespace of the runner, and a Kubernetes secret with the role ID and a new secret ID of the AppRole. The values go from `vault` straight into the secret:

```bash
kubectl create namespace soda-runner
kubectl -n soda-runner create secret generic vault-approle \
  --from-literal=role-id="$(vault read -field=role_id auth/approle/role/soda-runner/role-id)" \
  --from-literal=secret-id="$(vault write -f -field=secret_id auth/approle/role/soda-runner/secret-id)"
```

Create a `SecretStore` that connects to Vault with the AppRole. Set `server` to the address of your Vault server:

{% code title="secret-store.yml" %}

```yaml
apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: vault
  namespace: soda-runner
spec:
  provider:
    vault:
      server: https://vault.example.com:8200
      path: secret
      version: v2
      auth:
        appRole:
          path: approle
          roleRef:
            name: vault-approle
            key: role-id
          secretRef:
            name: vault-approle
            key: secret-id
```

{% endcode %}

Create an `ExternalSecret` that copies the database credentials into the Kubernetes secret `sales-postgres-credentials`:

{% code title="sales-postgres-credentials.yml" %}

```yaml
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: sales-postgres-credentials
  namespace: soda-runner
spec:
  refreshInterval: 1m
  secretStoreRef:
    kind: SecretStore
    name: vault
  target:
    name: sales-postgres-credentials
    template:
      engineVersion: v2
      data:
        sales_postgres.env: |
          POSTGRES_USER='{{ .username }}'
          POSTGRES_PASSWORD='{{ .password }}'
  dataFrom:
    - extract:
        key: soda/sales-postgres
```

{% endcode %}

A few details in the two resources:

* A `SecretStore` serves only the `ExternalSecret` resources in its own namespace. To share one Vault connection across namespaces, use a `ClusterSecretStore`: add the `namespace` of the `vault-approle` secret to `roleRef` and `secretRef`, and set `kind: ClusterSecretStore` in `secretStoreRef`. See [SecretStore](https://external-secrets.io/latest/api/secretstore/) and [ClusterSecretStore](https://external-secrets.io/latest/api/clustersecretstore/) in the ESO documentation.
* `dataFrom.extract` reads every key of the Vault secret `soda/sales-postgres`, so the template can use `.username` and `.password`.
* The template writes a single key, `sales_postgres.env`, in the dotenv format. The runner reads each key of the secret as a file of environment variables. The single quotes keep characters such as `#`, `$`, and spaces in the password as they are. See [Templating](https://external-secrets.io/latest/guides/templating/) for the template syntax.
* `refreshInterval` sets how often ESO reads Vault and updates the Kubernetes secret. Without it, ESO refreshes every hour. Match it to how soon the runner must pick up a rotated password.

Apply both resources and check that they are ready:

```bash
kubectl apply -f secret-store.yml
kubectl apply -f sales-postgres-credentials.yml
kubectl -n soda-runner get secretstore vault
kubectl -n soda-runner get externalsecret sales-postgres-credentials
```

```
NAME    AGE   STATUS   CAPABILITIES   READY
vault   1s    Valid    ReadWrite      True
NAME                         STORETYPE     STORE   REFRESH INTERVAL   STATUS         READY   LAST SYNC
sales-postgres-credentials   SecretStore   vault   1m                 SecretSynced   True    0s
```

## Deploy the runner

{% stepper %}
{% step %}

### Create the runner's API key

In Soda Cloud, go to **Settings** > **Runners** and click **New Soda Runner**. Copy the API key ID and the API key secret from the dialog.

Store both in Vault. Replace `<API key ID>`, then paste the secret when `read` waits for it:

```bash
read -rs SODA_RUNNER_API_KEY_SECRET
printf '%s' "$SODA_RUNNER_API_KEY_SECRET" | vault kv put -mount=secret soda/runner-api-key \
  api_key_id="<API key ID>" api_key_secret=-
```

{% endstep %}

{% step %}

### Sync the API key into Kubernetes

The runner uses its API key twice: to connect to Soda Cloud, and to pull its images from the Soda container registry. Create two `ExternalSecret` resources, one for each:

{% code title="soda-runner-api-key.yml" %}

```yaml
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: soda-runner-api-key
  namespace: soda-runner
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: vault
  target:
    name: soda-runner-api-key
  dataFrom:
    - extract:
        key: soda/runner-api-key
---
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: soda-registry-credentials
  namespace: soda-runner
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: vault
  target:
    name: soda-registry-credentials
    template:
      type: kubernetes.io/dockerconfigjson
      engineVersion: v2
      data:
        .dockerconfigjson: |
          {"auths": {"registry.us.soda.io": {"username": "{{ .api_key_id }}", "password": "{{ .api_key_secret }}"}}}
  dataFrom:
    - extract:
        key: soda/runner-api-key
```

{% endcode %}

The registry is `registry.us.soda.io` for the US region of Soda Cloud and `registry.cloud.soda.io` for the EU region.

```bash
kubectl apply -f soda-runner-api-key.yml
```

{% endstep %}

{% step %}

### Install the runner

Create a values file that points the runner at the three Kubernetes secrets:

{% code title="values.yml" %}

```yaml
soda:
  apikey:
    existingSecret: soda-runner-api-key
    secretKeys:
      idKey: api_key_id
      secretKey: api_key_secret
  runner:
    name: secrets-manager-guide
  cloud:
    region: us
  scanLauncher:
    existingSecrets:
      - sales-postgres-credentials
imageCredentials:
  create: false
existingImagePullSecrets:
  - name: soda-registry-credentials
```

{% endcode %}

A few details in the values:

* `soda.apikey.existingSecret` and `secretKeys` name the secret and the keys that hold the API key ID and secret.
* `imageCredentials.create: false` stops the chart from creating its own registry secret from the API key, and `existingImagePullSecrets` gives it the one that ESO maintains.
* `soda.scanLauncher.existingSecrets` mounts each listed secret into every job the runner starts, including contract verifications, and tells the job to read the mounted files as environment variables.
* `soda.cloud.region` is `us` or `eu`, the region of your Soda Cloud organization.

Install the runner:

```bash
helm repo add soda-runner https://helm.soda.io/soda-runner/
helm repo update
helm install soda-runner soda-runner/soda-runner --values values.yml --namespace soda-runner
```

Once the runner registers with Soda Cloud, it shows up in **Settings** > **Runners**, with a green dot under **Last seen** while it is online.

<figure><img src="https://1928210810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJJOow5YZtrrxZJBNXV2D%2Fuploads%2Fgit-blob-f6cd87b8be9a802d0a87921641024f992accd80a%2Fuse-a-secrets-manager-runner-online.png?alt=media" alt="The Runners page with secrets-manager-guide, last seen less than a minute ago"><figcaption><p>The runner is online</p></figcaption></figure>
{% endstep %}
{% endstepper %}

> For every value of the Helm chart, see [Soda Runner: additional information](broken://spaces/A2PmHkO5cBgeRPdiPPOG/pages/nAuMYvhG1bT9hNhRsS3y).

## Connect the data source

Add the data source in Soda Cloud on the new runner:

1. Go to **Data Sources**, click **New Data Source**, and select **PostgreSQL**.
2. Under **Data Source Identifier**, enter `sales_postgres`.
3. Under **Default Runner**, in **Default Scan Runner**, select `secrets-manager-guide`.

   <figure><img src="https://1928210810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJJOow5YZtrrxZJBNXV2D%2Fuploads%2Fgit-blob-df172a6307495c4f60b4aecaeddd44d199ae6cb8%2Fuse-a-secrets-manager-connection-runner.png?alt=media" alt="The Default Runner field, with secrets-manager-guide selected"><figcaption><p>The data source runs on the self-hosted runner</p></figcaption></figure>
4. Under **Connection Details**, enter the host, port, and database. In **User**, enter `${env.POSTGRES_USER}`, and in **Password**, enter `${env.POSTGRES_PASSWORD}`.
5. Click **Test connection**. When the test passes, click **Connect** and complete the remaining steps.

<figure><img src="https://1928210810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJJOow5YZtrrxZJBNXV2D%2Fuploads%2Fgit-blob-0191fa876dc798fe5bfcb955032e0330c7b4d0d3%2Fuse-a-secrets-manager-connection-details.png?alt=media" alt="The Connection Details of sales_postgres, with the user and password set to environment variables"><figcaption><p>The connection refers to the credentials as environment variables</p></figcaption></figure>

Soda Cloud stores only the variable names. The runner's jobs resolve them from the mounted secret. This is the data source configuration that Soda Cloud stores:

{% code title="sales\_postgres.yml" %}

```yaml
type: postgres
name: sales_postgres
connection:
  host: postgres.example.com
  port: 5432
  user: ${env.POSTGRES_USER}
  password: ${env.POSTGRES_PASSWORD}
  database: sales_dw
```

{% endcode %}

To create the data source with the REST API instead, send this configuration in `configurationFileContents` to `POST /api/v1/datasources`, with the runner's ID in `runnerId`. See the [REST API](https://docs.soda.io/apis/rest-api.md) reference.

After you connect the data source, onboard its datasets and verify contracts as with any other data source. Every scan runs on the runner with the credentials from Vault.

<figure><img src="https://1928210810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJJOow5YZtrrxZJBNXV2D%2Fuploads%2Fgit-blob-3a8929871cb91ab0acfac81955f85c25bd2e7980%2Fuse-a-secrets-manager-dataset-checks.png?alt=media" alt="The Checks tab of fact_internet_sales, with every check of the contract passing"><figcaption><p>Contract results of <code>fact_internet_sales</code>, verified on the runner</p></figcaption></figure>

> For the onboarding steps, see [Onboard datasets on Soda Cloud](https://docs.soda.io/soda-documentation/connect/onboard-data-sources-and-datasets/onboard-datasets-on-soda-cloud.md).

## Rotate the password

To rotate the password, change it in the database:

```sql
ALTER USER soda_reader WITH PASSWORD '<new password>';
```

Then update it in Vault. `vault kv patch` changes the password and keeps the user name:

```bash
read -rs DB_PASSWORD
printf '%s' "$DB_PASSWORD" | vault kv patch -mount=secret soda/sales-postgres password=-
```

At its next refresh, ESO writes the new password to the Kubernetes secret, and every job that the runner starts after that uses it. You don't redeploy or restart the runner. Until the refresh, jobs use the old password, so keep the `refreshInterval` of the `ExternalSecret` short enough for your rotation.

## Next steps

* Use Soda secrets for credentials that Soda Cloud stores. See [Onboard datasets on Soda Cloud](https://docs.soda.io/soda-documentation/connect/onboard-data-sources-and-datasets/onboard-datasets-on-soda-cloud.md).
* Verify contracts on the runner from Soda Cloud or on a schedule. See [Verify a contract](https://docs.soda.io/soda-documentation/find/data-testing/cloud-managed-data-contracts/verify-a-contract.md).
* Configure the runner further. See [Soda Runner: additional information](broken://spaces/A2PmHkO5cBgeRPdiPPOG/pages/nAuMYvhG1bT9hNhRsS3y).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.soda.io/guides-and-tutorials/data-platform/use-a-secrets-manager.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
