Manage TiDB Cloud Filesystem Vault Secrets

TiDB Cloud Filesystem Vault lets you store secrets, delegate narrowly scoped and time-limited access to users or agents, and inject credentials into processes without writing plaintext to disk.

Prerequisites

• Install and configure TiDB Cloud CLI.
• Select a Filesystem by passing --file-system-id, setting TI_FS_FILE_SYSTEM_ID, or supplying an FS token that identifies the Filesystem.
• For owner operations, provide an owner FS token through --fs-token, TI_FS_TOKEN, or the local credential stored for the selected Filesystem.

Create and read a secret

ti fs-vault create-secret \
  --secret-name db-prod \
  --field DB_URL=mysql://example \
  --field PASSWORD=@./password.txt

ti fs-vault read-secret --secret-name db-prod

Delegate limited access

Create a short-lived read grant and capture its token:

export TI_VAULT_TOKEN="$(ti fs-vault create-grant \
  --agent-id deploy-agent \
  --scope db-prod/DB_URL \
  --permission read \
  --ttl 10m \
  --token-only)"

Prefer TI_VAULT_TOKEN to a command-line token because command-line values can remain in process listings or shell history.

Inject a secret into a process

The CLI can inject secret fields as environment variables into a child process without writing plaintext to disk. When you run the following command, the CLI reads the secret, sets each field as an environment variable (for example, DB_URL, PASSWORD), removes its own credential environment variables from the child, and then executes the specified command:

ti fs-vault run-with-secret --secret-path /n/vault/db-prod -- <command>

Prefer process injection to writing plaintext to disk.

Field names injected by run-with-secret must match [A-Z_][A-Z0-9_]*. The command rejects the entire injection if any field name does not match this pattern or any field value contains an unsupported control character. Use uppercase environment-variable-style names when creating fields that you plan to inject.

Audit and revoke access

ti fs-vault list-audit-events \
  --secret-name db-prod \
  --agent-id deploy-agent \
  --since 24h \
  --limit 20

ti fs-vault delete-grant \
  --grant-id "<grant-id>" \
  --revoked-by operator \
  --reason rotated

Revocation prevents new authorized operations but cannot erase a value that a process already read.

Mount a read-only Vault view

On macOS or Linux with FUSE support, you can mount a read-only FUSE view of Vault secrets. The CLI creates the mount and serves secret fields as files under the mount path (for example, /path/to/vault/db-prod/DB_URL):

Before mounting, set TI_VAULT_TOKEN to a delegated Vault token, such as the token created in Delegate limited access. The mount command requires either TI_VAULT_TOKEN or --vault-token.

mkdir -p /path/to/vault
ti fs-vault mount-vault \
  --mount-path /path/to/vault

Stop any processes that use the mount before you unmount it:

ti fs-vault unmount-vault --mount-path /path/to/vault

Vault mounts are unavailable on Windows. Direct secret reads and process injection do not require a mount.

Security recommendations

• Grant the narrowest field scope and shortest practical TTL.
• Do not store delegated tokens in CLI configuration or operation logs.
• Revoke grants after their tasks finish.

What's next

• Delegate TiDB Cloud Filesystem Vault Secrets to an Agent
• TiDB Cloud Filesystem Vault CLI Command Reference