Secret Versions and Rotation States

This topic explains the relationship between secrets, secret versions, and rotation states. It also discusses the impact of service limits on secret versions. Understanding secret versions and rotation states will help you track and manage secret contents to stay in compliance with any limits, rotation or other rules, or regulations. For a basic definition of secret concepts, including secret versions and rotation states, see Key and Secret Management Concepts. For information about working with secret versions, see Managing Secrets.

Secret Versions

Every secret has at least one secret version. Every time you update the contents of a secret, you create a new secret version. Secret version numbers start at 1 and increment by 1. While every secret has at least one version, you might have multiple versions of a secret at any given time.

In addition to a version number, you can identify a secret version by its version name or rotation state. A secret version's rotation state represents how the secret is being used. Typically, applications need the current version of a secret. Marking a secret version as the 'current' version indicates that it has the secret contents currently used for access to the intended resource. Meaning, if you stored the password to connect to a database as a secret, when you request the current version of that secret, you do so with the knowledge that it's the password that the database currently expects.

Rotation States

Secret versions can have more than one rotation state at a time. Where only one secret version exists, such as when you first create a secret, the secret version is automatically marked as both 'current' and the 'latest'. The 'latest' version of a secret contains the secret contents that were last uploaded to the vault, in case you want to keep track of that.

When you rotate a secret to upload new secret contents, you can mark it as 'pending'. Marking a secret version's rotation state as 'pending' lets you upload the secret contents to the vault without immediately putting them into active use. You can continue using the 'current' secret version until you're ready to promote a pending secret version to 'current' status. This typically happens after you’ve rotated credentials on the target resource or service first. You don’t want to unexpectedly change a secret version. Changing what secret version is current prevents the application that needs it from retrieving the expected secret version from the vault.

For the purposes of rolling back to a previous version easily, such as when you've made a mistake in updating the secret contents or when you've restored a backup of an older resource and need to resume using older secret contents, secret versions can also be marked as 'previous.' A secret version marked as 'previous' was previously a secret version marked as 'current.' To roll back to a previous version, you update the secret to specify the secret version number you want.

As long as a secret version hasn't been deleted, you can update the secret to use that past secret version. When you update the secret, the secret version number you choose gets marked as 'current.' This has the same effect as promoting a secret version to 'current.'

You can only delete secret versions that have been marked as 'deprecated.' A deprecated secret version is one that’s not marked as 'current,' 'pending,' or 'previous.' This helps to prevent circumstances where you might delete a secret version that you need later (for example, when restoring a database you backed up previously). A secret version that’s marked as anything other than 'deprecated' can be marked as 'current' to return it to active use.

Secret Version Limits

The limits on secret versions applies to both a secret’s versions that are in use and versions that are deprecated, including those that have been scheduled for deletion. For information about limits on the number of versions for a given secret and for secret versions in a tenancy, see Service Limits.