[ aws . secretsmanager ]

update-secret-version-stage

Description

Modifies the staging labels attached to a version of a secret. Secrets Manager uses staging labels to track a version as it progresses through the secret rotation process. Each staging label can be attached to only one version at a time. To add a staging label to a version when it is already attached to another version, Secrets Manager first removes it from the other version first and then attaches it to this one. For more information about versions and staging labels, see Concepts: Version .

The staging labels that you specify in the VersionStage parameter are added to the existing list of staging labels for the version.

You can move the AWSCURRENT staging label to this version by including it in this call.

Note

Whenever you move AWSCURRENT , Secrets Manager automatically moves the label AWSPREVIOUS to the version that AWSCURRENT was removed from.

If this action results in the last label being removed from a version, then the version is considered to be ‘deprecated’ and can be deleted by Secrets Manager.

Required permissions: secretsmanager:UpdateSecretVersionStage . For more information, see IAM policy actions for Secrets Manager and Authentication and access control in Secrets Manager .

See also: AWS API Documentation

See ‘aws help’ for descriptions of global parameters.

Synopsis

  update-secret-version-stage
--secret-id <value>
--version-stage <value>
[--remove-from-version-id <value>]
[--move-to-version-id <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]

Options

--secret-id (string)

The ARN or the name of the secret with the version and staging labelsto modify.

For an ARN, we recommend that you specify a complete ARN rather than a partial ARN.

--version-stage (string)

The staging label to add to this version.

--remove-from-version-id (string)

The ID of the version that the staging label is to be removed from. If the staging label you are trying to attach to one version is already attached to a different version, then you must include this parameter and specify the version that the label is to be removed from. If the label is attached and you either do not specify this parameter, or the version ID does not match, then the operation fails.

--move-to-version-id (string)

The ID of the version to add the staging label to. To remove a label from a version, then do not specify this parameter.

If the staging label is already attached to a different version of the secret, then you must also specify the RemoveFromVersionId parameter.

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See ‘aws help’ for descriptions of global parameters.

Examples

Example 1: To revert a secret to the previous version

The following update-secret-version-stage example moves the AWSCURRENT staging label to the previous version of a secret, which reverts the secret to the previous version. To find the ID for the previous version, use list-secret-version-ids. For this example, the version with the AWSCURRENT label is a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 and the version with the AWSPREVIOUS label is a1b2c3d4-5678-90ab-cdef-EXAMPLE22222. In this example, you move the AWSCURRENT label from version 11111 to 22222. Because the AWSCURRENT label is removed from a version, update-secret-version-stage automatically moves the AWSPREVIOUS label to that version (11111). The effect is that the AWSCURRENT and AWSPREVIOUS versions are swapped.

aws secretsmanager update-secret-version-stage \
    --secret-id MyTestSecret \
    --version-stage AWSCURRENT \
    --move-to-version-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --remove-from-version-id a1b2c3d4-5678-90ab-cdef-EXAMPLE22222

Output:

{
    "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestSecret-a1b2c3",
    "Name": "MyTestSecret"
}

For more information, see Version in the Secrets Manager User Guide.

Example 2: To add a staging label attached to a version of a secret

The following update-secret-version-stage example adds a staging label to a version of a secret. You can review the results by running list-secret-version-ids and viewing the VersionStages response field for the affected version.

aws secretsmanager update-secret-version-stage \
    --secret-id MyTestSecret \
    --version-stage STAGINGLABEL1 \
    --move-to-version-id EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE

Output:

{
    "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestSecret-a1b2c3",
    "Name": "MyTestSecret"
}

For more information, see Version in the Secrets Manager User Guide.

Example 3: To delete a staging label attached to a version of a secret

The following update-secret-version-stage example deletes a staging label that is attached to a version of a secret. You can review the results by running list-secret-version-ids and viewing the VersionStages response field for the affected version.

aws secretsmanager update-secret-version-stage \
    --secret-id MyTestSecret \
    --version-stage STAGINGLABEL1 \
    --remove-from-version-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

Output:

{
    "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestSecret-a1b2c3",
    "Name": "MyTestSecret"
}

For more information, see Version in the Secrets Manager User Guide.

Output

ARN -> (string)

The ARN of the secret that was updated.

Name -> (string)

The name of the secret that was updated.