Configure a secret store
This page applies to the Enterprise plan, where you run the data plane in your own VPC. A data plane uses two kinds of secret storage. The secret store holds runtime state, such as the credentials your users connect. To choose one, see Choose a secret store. A vault holds the upstream secrets that you keep in your own system, such as an API key. This page explains how to choose each one, how to connect Azure Key Vault or HashiCorp Vault, and how to fix common errors.
Prerequisites
Before you begin, make sure you have the following:
- A data plane that’s connected to the control plane. See Connect the data plane to the control plane.
- The app Secret with an encryption key. See Secrets and keys.
- For a vault, network access from the gateway pods to the vault.
- Access to the Vaults page under Admin in the console.
Choose a secret store and a vault
Choose the secret store first, because the data plane needs it to start:
distributed-embeddedis the default on a data plane. The gateway pods keep the values in memory and replicate them to each other, so there’s no database to run. It needs the gossip key and data-port password in the app Secret.mysqlis optional. It stores the values in your MySQL database, for customers who prefer to run one. The Helm chart selects it unless you setdistributed.enabled: true. When you use a vault for your secrets, you don’t need it.
The bbolt store, which is a local file, isn’t supported on a data plane. The gateway fails to start with secrets.type=bbolt is not supported on the dataplane; use distributed-embedded (default) or mysql.
Choose a vault by where your secrets already live. Use Azure Key Vault if you run on Azure, and HashiCorp Vault if you run it already. A vault is independent of the secret store, and you can register more than one.
Settings
The data plane reads these environment variables for the secret store. In the Helm chart, set them under env.vars.
Register a vault
You register a vault on the Vaults page. The control plane stores the vault’s settings and sends them to the data plane. The data plane then reads and writes secrets in your vault itself, so secret values don’t pass through the control plane.
- In the console, select Vaults under Admin, and then select Add.
- Enter a Name. You choose this name later, when you point a credential or plugin at the vault.
- For the provider, select Azure Key Vault or HashiCorp Vault.
- Enter the authentication fields in one of the following sections, and save the vault.
Both vault types have two optional settings:
Azure Key Vault
The gateway doesn’t use the developer credentials on a node, such as the Azure CLI. It uses only the mode you select.
Choose the mode that fits where the data plane runs:
managed_identityfor a node, VM scale set, or App Service identity. Set onlyvault_url, and addclient_idfor a user-assigned identity.workload_identityfor AKS. The pod’s ServiceAccount needs theazure.workload.identity/client-idannotation, and the pod needs theazure.workload.identity/use=truelabel. The AKS webhook then injectsAZURE_TENANT_ID,AZURE_CLIENT_ID, andAZURE_FEDERATED_TOKEN_FILE.client_secretwhen neither is available. You manage the secret’s rotation.
Give the identity one of these Azure roles on the vault:
Use a Key Vault that’s dedicated to gateway-managed credentials. Key Vault deletes a whole secret, so if another writer adds versions to the same secrets, the gateway detects and rolls back the change, but it can’t block it atomically.
Example for AKS with the Helm chart. The chart sets the ServiceAccount annotation through serviceAccount.annotations:
The chart has no value for pod labels, so it can’t add the azure.workload.identity/use=true label for you. Add the label to the data plane’s pod template yourself, for example with a Helm post-renderer or a Kustomize patch. If you can’t, use managed_identity or client_secret instead.
Then register the vault in the console with vault_url set to https://<vault-name>.vault.azure.net and auth_mode set to workload_identity.
HashiCorp Vault
With approle and kubernetes, the gateway logs in again before the token expires, and once more if Vault returns 403.
Give the identity a Vault policy for the paths the gateway uses. For KV v2 with the default mount, the gateway reads secret/data/<path>. To store and delete secrets that it manages, it also writes secret/data/<path> and writes, reads, and deletes secret/metadata/<path>. It stamps each secret it creates with managed-by: fabric-gateway, and deletes only secrets that carry it. The health check calls auth/token/lookup-self.
For read-only use, keep only read on secret/data/*. With KV v1, the gateway can read and write, but it declines to delete, because v1 can’t carry the marker.
Reference a secret
A credential or plugin points at a secret with a vault and a secret reference. In the console, select the vault by name, and then enter the reference. For a plugin, see Secret Injector. Where you enter a secret directly, on a data plane that you run, you enter a reference instead of the value.
If a secret has more than one field, enter Property to pick one. A secret with a single value field needs no property.
For secrets that the gateway creates, such as a managed credential, the console stores and returns the full identifier or URL. Keep the full form for those. The gateway refuses a bare Azure name for a managed secret.
Common errors
Each message is in the gateway log. The data plane redacts the secret reference.
The console’s Dependencies view shows whether your vault is reachable. See Monitor the data plane.
Next steps
- To create the app Secret and rotate the encryption key, see Secrets and keys.
- To store a vault secret as a plugin’s credential, see Secret Injector.
- For every chart setting, see Helm values.
- To manage credentials and vaults in the console, see Manage credentials and vaults.

