> For the complete documentation index, see [llms.txt](https://docs.zerve.ai/self-managed/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zerve.ai/self-managed/configuration/vault.md). # Vault Zerve uses [HashiCorp Vault](https://www.hashicorp.com/en/products/vault) to store the secrets your users hand to the platform: data source connection credentials, cloud credentials, organization and per-user secrets (including LLM provider API keys), and secret constants. Secrets are read and written through the KV v2 secrets engine at its default mount, `secret/`. The mount path is not configurable. ## Bundled Vault The chart can run a Vault on your cluster for you. It is meant for evaluation and testing only: `vault server -dev`, which means in-memory storage, auto-initialised, auto-unsealed, and a single root token. Setting `vault.enabled: true` creates the instance, but the asset service still reads `HASHICORP_VAULT_*` from its own environment and secrets. The chart ships a values file with that wiring already in place, so layer it on top of your own values and keep it last: ``` helm upgrade --install zerve . -f my-values.yaml -f examples/bundled-vault.yaml ``` The dev-mode root token comes from `vault.auth.rootToken` (default `zerve-dev-root`), which the chart templates into a Secret named `zerve-vault`. To keep the token out of your values file, create the Secret yourself and set `vault.auth.existingSecret` to its name. For production, we recommend an external Vault managed outside the cluster. ## External Vault Point the asset service at your instance in the Helm chart: ```yaml # my-values.yaml asset: workloads: common: secrets: HASHICORP_VAULT_TOKEN: secretName: zerve-creds key: vault_token # optional, defaults to HASHICORP_VAULT_TOKEN env: HASHICORP_VAULT_URL: "https://vault.acme.internal:8200" ``` `HASHICORP_VAULT_URL` has no usable default and is always required. The scheme decides whether the connection is TLS — see [TLS](#tls) below. Zerve does not unseal Vault for you, so you will have to do this on your end. ### Preparing the Vault Enable KV v2 at `secret/` before installing. Dev mode mounts it for you, but a freshly initialised Vault does not: ``` vault secrets enable -path=secret kv-v2 ``` Then create a policy for Zerve: ```hcl # zerve.hcl path "secret/data/*" { capabilities = ["create", "read", "update"] } path "secret/metadata/*" { capabilities = ["delete"] } ``` ``` vault policy write zerve zerve.hcl ``` Deleting a secret removes all of its versions, which is a write to `secret/metadata/`, hence the second rule. Add `"list"` there if you also want the token to be able to browse the mount with the CLI. Zerve writes to `secret/user_secrets/` and `secret/org_secrets/`, and to `secret/` for connections, constants and cloud credentials. Because that last group sits at the root of the mount, the policy cannot be narrowed by prefix. ### Token This version of Zerve Self-Managed authenticates with a static token. The Kubernetes auth method, AppRole and Vault Agent injection are coming in future Zerve releases. ``` vault token create -policy=zerve -orphan -ttl=8760h ``` Zerve reads the token once at startup and never renews it, which has two consequences: * The token has to outlive the install. Give it a long TTL, or renew it externally and remember that a replaced token does not reach the running pods until you restart them (`kubectl rollout restart deployment/asset-service-api`). * `-orphan` keeps it from being revoked along with the token that created it. ### TLS With an `https://` URL, the certificate is verified against the trust store in the image. If your Vault presents a certificate from a private or internal CA, mount your CA bundle into the asset service and point the client at it: ```yaml # my-values.yaml asset: volumes: vaultCa: name: vault-ca mountPath: /etc/zerve/vault-ca readOnly: true source: secret: secretName: vault-ca # must already exist in the release namespace workloads: api: extraVolumes: - vaultCa env: REQUESTS_CA_BUNDLE: /etc/zerve/vault-ca/ca.crt ``` `REQUESTS_CA_BUNDLE` names a file, so it must match a key in the Secret — `ca.crt` above. Use `extraVolumes` rather than `volumes`: the latter replaces the service's default volume list instead of adding to it. Only the `api` workload talks to Vault, so the migration Job needs neither the volume nor the variable. --- # 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.zerve.ai/self-managed/configuration/vault.md?ask=&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.