April 2024: You are able to see the versions within Secret Dashboard in AWS Management Console. You will still need to rely on AWSCLI commands to rollback to the specific versions of the secret.

The Why

I always thought only AWS Parameter Store has version history, since it's something you can see via the AWS Management Console.

Recently, I found out that AWS Secrets Manager does have version history as well, though it's only available via the AWS CLI.

How-To

Retrieve Secrets Version ID (Current and Previous Version)

To retrieve the versions available, use the list-secret-version-ids option. It will show the latest and previous versions only.

aws secretsmanager list-secret-version-ids  --secret-id <SECRET_NAME>

Response Output Sample

{
    "Versions": [
        {
            "VersionId": "12c5b181-f655-4274-8907-7324b6ff8eeb",
            "VersionStages": [
                "AWSCURRENT"
            ],
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T22:06:31.366000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        },
        {
            "VersionId": "0ef87dec-4955-4fc2-ba88-d7e1b4f6e73c",
            "VersionStages": [
                "AWSPREVIOUS"
            ],
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T20:31:04.421000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        }
    ],
    "ARN": "arn:aws:secretsmanager:AWS_REGION:AWS_ACCOUNT_ID:secret:SECRET_NAME-UNIQUE_IDENTIFIER",
    "Name": "SECRET_NAME"
}

Retrieve all Secrets Version IDs

To show all version id for the target secret, you will need to include the --include-deprecated option which will include versions without staging labels.

• All secrets without staging labels are considered deprecated and subject to deletion by AWS Secrets Manager.

• By default, versions without staging labels are not included in list-secrets-version-ids

aws secretsmanager list-secret-version-ids  --secret-id <SECRET_NAME> --include-deprecated

Response Output Sample

Observe how the earlier version ids have no version stage i.e. staging labels tied to them

{
    "Versions": [
        {
            "VersionId": "7bcea950-fe24-9f70-c6fd-436abf571be2",
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T18:45:43.284000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        },
        {
            "VersionId": "0f3bf6c5-29db-42b7-add9-b1a1e9e5fa3c",
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T20:30:54.366000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        },
        {
            "VersionId": "0ef87dec-4955-4fc2-ba88-d7e1b4f6e73c",
            "VersionStages": [
                "AWSPREVIOUS"
            ],
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T20:31:04.421000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        },
        {
            "VersionId": "12c5b181-f655-4274-8907-7324b6ff8eeb",
            "VersionStages": [
                "AWSCURRENT"
            ],
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T22:06:31.366000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        }
    ],
    "ARN": "arn:aws:secretsmanager:AWS_REGION:AWS_ACCOUNT_ID:secret:SECRET_NAME-UNIQUE_IDENTIFIER",
    "Name": "SECRET_NAME"
}

Add/Remove staging label to secrets

If you want a specific secret's version id to show up in the list-secret-version-id, you can add a custom staging label to it.

To add a staging label

aws secretsmanager update-secret-version-stage --secret-id sample-secrets --version-stage <STAGING_LABEL> --move-to-version-id <VERSION_ID_TO_TAG>

To remove a staging label

aws secretsmanager update-secret-version-stage --secret-id sample-secrets --version-stage <STAGING_LABEL> --remove-from-version-id <VERSION_ID_TO_TAG>

Response Output Sample

• Upon adding a staging label to earlier versions, you will be able to see the version id without using --include-deprecated.

• In this case, the staging label ANOTHERSTAGINGLABEL is used to tag one of the earlier version id.

{
    "Versions": [
        {
            "VersionId": "7bcea950-fe24-9f70-c6fd-436abf571be2",
            "VersionStages": [
                "ANOTHERSTAGINGLABEL"
            ],
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T18:45:43.284000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        },
        {
            "VersionId": "12c5b181-f655-4274-8907-7324b6ff8eeb",
            "VersionStages": [
                "AWSCURRENT"
            ],
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T22:06:31.366000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        },
        {
            "VersionId": "0ef87dec-4955-4fc2-ba88-d7e1b4f6e73c",
            "VersionStages": [
                "AWSPREVIOUS"
            ],
            "LastAccessedDate": "2023-05-13T08:00:00+08:00",
            "CreatedDate": "2023-05-13T20:31:04.421000+08:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        }
    ],
    "ARN": "arn:aws:secretsmanager:AWS_REGION:AWS_ACCOUNT_ID:secret:SECRET_NAME-UNIQUE_IDENTIFIER",
    "Name": "SECRET_NAME"
}

Rolling back to the previous version of secrets

To roll back to the target secret version, you need to

1. Indicate which secret's version id to roll back to

2. Indicate the version stage label to use. There is AWSPREVIOUS and AWSCURRENT, which is used by AWS to identify the previous version and current version of secrets.

3. Move the AWSCURRENT tag to the version id you want to roll back to and remove the version stage label from the current secret

• This needs to be done together, if not, AWS CLI will throw an error as the staging label can only be attached to 1 version id at any one time.

aws secretsmanager update-secret-version-stage --secret-id SECRET_NAME --version-stage AWSCURRENT --move-to-version-id <VERSION_ID_TO_ROLL_BACAK_TO> --remove-from-version-id <CURRENT_VERSION_ID>

Response Output Sample

{
  "ARN": "arn:aws:secretsmanager:AWS_REGION:AWS_ACCOUNT_ID:secret:SECRET_NAME-UNIQUE_IDENTIFIER",
  "Name": "SECRET_NAME"
}

Final Thoughts

Writing it down since if I don't use it, I probably forget about it later 😬

Hope this article will give you insights into how version control works for secrets in AWS Secrets Manager.

Cheers! 🍻