Skip to content

Secret providers

A linked secret keeps a reference to a value held by an external provider instead of the value itself. Falak resolves it on the control plane when a deployment (or a build) needs it, so the value never has to be copied into Falak by hand.

  1. Open Settings → Secret providers → Add (secrets.providers.manage, owners and admins).
  2. Pick the type and fill in its settings (below). Credentials are write-only: they are sealed at rest and never shown again.
  3. Optionally set the cache TTL (default 5 minutes, 0 always asks the provider).
  4. Save, then Test connection. The provider’s status turns OK or Failing with the reason.

Then create a secret on any Secrets page with Source: Linked to a provider, pick the provider and enter the reference.

Provider Reference
HashiCorp Vault / OpenBao vault://<mount>/data/<path>#<key> (KV v2) · vault://<mount>/<path>#<key> (KV v1, set on the provider)
AWS Secrets Manager aws-sm://<name or ARN> · aws-sm://<name>#<json key> (one key of a JSON secret)
AWS SSM Parameter Store aws-ssm:///<path/name> (or aws-ssm://<name>; read with decryption)
1Password op://<vault>/<item>/<field> · op://<vault>/<item>/<section>/<field>
Doppler doppler://<project>/<config>/<NAME>
Infisical infisical://<project id>/<environment>[/<path>…]/<NAME>
HTTPS webhook https://<base URL>/<name>
  • A reference must match its provider’s type; Falak checks it when the secret is saved. When the organization has exactly one provider of a reference’s type, you can leave the provider out.
  • Values are text. Vault and AWS JSON values pick one key (#key); numbers and booleans become their JSON text.
Setting Notes
Address https://vault.example.com
Namespace Optional (Vault Enterprise / HCP)
KV version 2 (default) or 1
Auth method Token; AppRole (role id + secret id); JWT / OIDC (role + JWT). Optional auth mount
CA certificate Optional, for a private CA

Logins (AppRole and JWT client tokens) are cached sealed until shortly before they expire.

  • A resolved value is cached sealed in the database, bound to its provider and reference. Within the cache TTL, deployments use it without calling the provider.

  • After the TTL the provider is asked again. If it fails, the last good value is used, the provider turns Failing, and secrets.provider_unreachable fires (once, until secrets.provider_recovered).

  • The last good value is used for at most 24 hours after it was fetched (FALAK_SECRETS_PROVIDERS_MAX_STALE_SECONDS). Past that, or with nothing cached, deployments fail with the reason — never with credentials, values or the provider’s response body:

    secret DB_PASS: Production Vault: HashiCorp Vault / OpenBao at vault.example.com is unreachable …
  • Values larger than 64 KiB are refused.

  • Changing a provider’s settings drops its cached values and logins.

A linked secret can be watched: set Watch every (minutes, at least 1) when you create or edit it. Falak asks the provider at that interval and compares the answer with the last value it saw (only an HMAC of it is kept). On a change, Falak:

  1. records a new version (same reference, note Changed upstream) holding the new value as a sealed snapshot;
  2. fires secrets.linked_changed (names only);
  3. does what When it changes says: nothing more, restart the processes of the services that use it, or redeploy them.

A value reaches a service’s environment when it is deployed, so choose redeploy for environment variables; restart suits apps that read the secret from the provider themselves when they boot.

Each version keeps its reference and, when the watch saw it, the value it had. Rolling back to such a version pins the secret to that value: deployments use the snapshot instead of asking the provider, and the watch pauses. Saving the reference again (a new version) unpins it. Rolling back to a version without a snapshot only restores its reference.

  • Endpoints must be https://, and TLS is always verified (add a CA certificate for a private CA). Timeouts: 5 s to connect, 10 s in total, one retry.
  • Endpoints must resolve to public addresses. A provider on a private network needs both the instance setting FALAK_SECRETS_PROVIDERS_ALLOW_PRIVATE=true (operator, off by default) and the provider’s Allow private network (Vault, OpenBao, Infisical, 1Password Connect and webhooks).
  • Link-local and cloud metadata addresses are always refused. The check runs when the provider is saved and before every request, and the request is pinned to the addresses checked.

secrets.view sees providers (names, types, status, non-secret settings). secrets.providers.manage (owners and admins) adds, edits, tests and deletes them — whoever edits an endpoint decides where credentials are sent, so changing a URL, CA certificate, namespace, region, role, external ID or webhook header requires entering every credential again. Developers link secrets to existing providers with secrets.manage. A provider used by linked secrets can’t be deleted.