Secrets Sync

In certain circumstances, fetching secrets directly from Vault is impossible or impractical. To help with this challenge, Vault can maintain a one-way sync for KVv2 secrets into various destinations that are easier to access for some clients. With this, Vault remains the system of records but can cache a subset of secrets on various external systems acting as trusted last-mile delivery systems.

A secret that is associated from a Vault KVv2 Secrets Engine into an external destination is actively managed by a continuous process. If the secret value is updated in Vault, the secret is updated in the destination as well. If the secret is deleted from Vault, it is deleted on the external system as well. This process is asynchronous and event-based. Vault propagates modifications into the proper destinations automatically in a handful of seconds.

Destinations

Secrets can be synced into various external systems, called destinations. The supported destinations are:

• AWS Secrets Manager
• Azure Key Vault
• GCP Secret Manager
• GitHub Repository Actions
• Vercel Projects

Associations

Syncing a secret into one of the external systems is done by creating a connection between it and a destination, which is called an association. These associations are created via Vault's API by adding a KVv2 secret target to one of the configured destinations. Each association keeps track of that secret's current sync status, the timestamp of its last status change, and the error code of the last sync or unsync operation if it failed. Each destination can have any number of secret associations.

Sync Statuses

There are several sync statuses which relay information about the outcome of the latest sync operation to have occurred on that secret. The status information is stored inside each association object returned by the endpoint and, upon failure, includes an error code describing the cause of the failure.

• SYNCING - The sync operation for the secret is currently in-progress.
• SYNCED - The sync operation was successful and sent the secret to the external destination.
• UNSYNCING - The unsync operation for the secret is currently in-progress.
• UNSYNCED - The unsync operation was successful and removed the secret from the external destination. This is returned when a secret itself is deleted but the association is not.
• INTERNAL_VAULT_ERROR - The sync or unsync operation failed due to an issue internal to Vault.
• CLIENT_SIDE_ERROR - The sync or unsync operation failed due to a configuration error. For example, the credentials used to configure the destination expired or were revoked.
• EXTERNAL_SERVICE_ERROR - The sync or unsync operation failed due to an issue with the external service provider's side.
• UNKNOWN - Vault is unable to determine the current state of the secret in regards to the external service.

API

Please see the secrets sync API for more details.