This page explains how to set up the delayed destruction of secret versions, update or remove the destruction delay duration, and restore secret versions that are scheduled for destruction.
When you destroy a secret version, the secret material is destroyed immediately and permanently. As the Secret Manager Admin, you can set up delayed destruction of secret versions such that the secret version isn't destroyed immediately upon request and remains recoverable for a configurable duration.
When delayed destruction is enabled on the secret and you destroy a secret version, the following occurs:
- The version is disabled, preventing its use.
- The system schedules the version for permanent destruction at the end of the delay period.
- After the delay period expires, the secret version is permanently and irrevocably destroyed.
Benefits
This feature provides the following benefits:
An extra layer of protection against accidental or malicious destruction of critical secret material. Any user with the Secret Manager Secret Version Manager role can destroy a secret version. This is an irreversible action. By setting up delayed destruction, you can prevent the immediate destruction of secret versions. You can grant users the minimum access required to manage the lifecycle of secret versions because you can monitor and prevent any accidental destruction of sensitive data.
Destroying a secret version triggers a SECRET_VERSION_DESTROY_SCHEDULED notification to the Pub/Sub topics configured on the secret. As a Secret Manager Admin, you can cancel the scheduled destruction and restore the secret version by either enabling or disabling the secret version.
Before you begin
Enable the Secret Manager API.
Set up authentication.
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
Required roles
To get the permissions that you need to set up delayed destruction of secret versions,
ask your administrator to grant you the
Secret Manager Admin (roles/secretmanager.admin
) IAM role on the secret.
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Set up delayed destruction
You can enable the delayed destruction of a secret version when you create the secret or when you update the secret.
Console
In the Google Cloud console, go to the Secret Manager page.
Follow the steps required to create a secret.
Go to the Delay secret version destroy section.
Select the Set duration for delayed destruction checkbox.
In the Destruction delay duration field, enter the duration in days. The minimum value that you can enter is 1 day while the maximum value is 1000 days.
Click Create secret.
To enable this feature on an existing secret, go to the Edit secret page and then configure the destruction delay duration.
gcloud
To configure the destruction delay duration on the secret, use the gcloud beta secrets create command.
Before using any of the command data below, make the following replacements:
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret.
- TTL_DURATION: the destruction delay duration for the secret versions. You can enter the duration in any format, for example, days, hours, or seconds. The minimum duration required is 1 day while maximum duration can be set to 1000 days.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION
Windows (PowerShell)
gcloud secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION
Windows (cmd.exe)
gcloud secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION
The response contains the newly created secret.
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: the Google Cloud project ID.
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret.
- TTL_DURATION: the destruction delay duration for the secret versions. Enter duration in seconds. Note that the minimum duration required is 1 day while maximum duration can be set to 1000 days.
HTTP method and URL:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID
Request JSON body:
{"replication": {"automatic": {}}, "version_destroy_ttl":"TTL_DURATION"}
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name":"projects/PROJECT_ID/secrets/SECRET_ID", "replication":{ "automatic":{ } }, "createTime":"2023-10-16T17:10:16.345401Z", "etag":"\"1607d90ee3d84c\"", "versionDestroyTtl":"TTL_DURATION" }
Delayed destruction doesn't apply in the following scenarios:
- When a secret is deleted, all the secret material and related secret versions are deleted immediately.
- When an expiration date is set on the secret and the secret expires, all the secret versions are destroyed immediately even if delayed destruction is enabled on the secret.
Update destruction delay duration
Console
In the Google Cloud console, go to the Secret Manager page.
Edit your secret using one of the following options:
- Click More actions associated with the secret that you want to edit, and then select Edit from the menu.
- Click the secret name to go to the Secret details page. On the Secret details page, click Edit secret.
Go to the Delay secret version destroy section.
In the Destruction delay duration field, enter the updated duration.
Click Update Secret.
gcloud
To update the destruction delay duration, use the gcloud beta secrets update command.
Before using any of the command data below, make the following replacements:
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
- TTL_DURATION: the destruction delay duration for the secret versions
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION
Windows (PowerShell)
gcloud secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION
Windows (cmd.exe)
gcloud secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION
The response contains the newly created secret.
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: the Google Cloud project ID
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
- TTL_DURATION: the destruction delay duration for the secret versions
HTTP method and URL:
PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl
Request JSON body:
{ "version_destroy_ttl":"TTL_DURATION" }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name":"projects/PROJECT_ID/secrets/SECRET_ID", "replication":{ "automatic":{ } }, "createTime":"2023-10-16T17:10:16.345401Z", "etag":"\"1607d90ee3d84c\"", "versionDestroyTtl":"TTL_DURATION" }
The secret versions that are affected by the destruction delay duration depends on the following:
- When delayed destruction is set for the first time on the secret, the destruction delay duration affects all the active (enabled and disabled) versions of the secret.
- When the destruction delay duration is updated or removed, the changes reflect only on new secret versions on which the destroy action is attempted. The secret versions that are already scheduled for destruction will continue to be destroyed at the scheduled destruction time.
Disable delayed destruction
Console
In the Google Cloud console, go to the Secret Manager page.
Edit your secret using one of the following options:
- Click More actions associated with the secret that you want to edit, and then select Edit from the menu.
- Click the secret name to go to the Secret details page. On the Secret details page, click Edit secret.
Go to the Delay secret version destroy section.
Clear the Set duration for delayed destruction checkbox.
Click Update Secret.
gcloud
To remove the destruction delay duration, use the gcloud beta secrets update command.
Before using any of the command data below, make the following replacements:
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud secrets update SECRET_ID --remove-version-destroy-ttl
Windows (PowerShell)
gcloud secrets update SECRET_ID --remove-version-destroy-ttl
Windows (cmd.exe)
gcloud secrets update SECRET_ID --remove-version-destroy-ttl
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: the Google Cloud project ID
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
HTTP method and URL:
PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl
Request JSON body:
{}
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name":"projects/PROJECT_ID/secrets/SECRET_ID", "replication":{ "automatic":{ } }, "createTime":"2023-10-16T17:10:16.345401Z", "etag":"\"1607d90ee3d84c\"" }
Test delayed destruction of secret versions
Console
In the Google Cloud console, go to the Secret Manager page.
Click the secret name. The Secret details page appears.
On the Secret details page, in the Versions table, select a secret version.
In the Actions column, click
View more, and then click Destroy.In the dialog that appears, click Schedule selected versions for destruction.
gcloud
To destroy a secret version, use the gcloud beta secrets versions destroy command.
Before using any of the command data below, make the following replacements:
- SECRET_VERSION_ID: the ID of the version or fully qualified identifier for the version
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID
Windows (PowerShell)
gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID
Windows (cmd.exe)
gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: the Google Cloud project ID
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
- VERSION_ID: the ID of the version or fully qualified identifier for the version
HTTP method and URL:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:destroy
Request JSON body:
{}
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:destroy"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:destroy" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name":"projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID", "createTime":"2023-10-16T17:21:55.920036Z", "state":"DISABLED", "replicationStatus":{ "automatic":{ } }, "etag":"\"1607d8b2fc1cf4\"", "scheduledDestroyTime":"2023-10-16T17:26:57.459395960Z" }
The secret version is immediately disabled and scheduled for destruction after the destruction delay duration expires. You can see the exact date and time on which the version will be destroyed under the Scheduled for destruction on column in the Versions table.
Restore secret versions
You can restore a secret version that is scheduled for destruction by enabling or disabling the secret version.
Enable a secret version that is scheduled for destruction
Console
In the Google Cloud console, go to the Secret Manager page.
Click the secret name. The Secret details page appears.
On the Secret details page, in the Versions table, select a secret version that is scheduled for destruction.
In the Actions column, click
View more, and then click Enable.In the dialog that appears, click Enable selected versions.
gcloud
To enable a secret version that is scheduled for destruction, use the gcloud beta secrets versions enable command.
Before using any of the command data below, make the following replacements:
- SECRET_VERSION_ID: the ID of the version or fully qualified identifier for the version
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID
Windows (PowerShell)
gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID
Windows (cmd.exe)
gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: the Google Cloud project ID
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
- VERSION_ID: the ID of the version or fully qualified identifier for the version
HTTP method and URL:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:enable
Request JSON body:
{}
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:enable"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:enable" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID", "createTime": "2024-09-04T06:41:57.859674Z", "state": "ENABLED", "etag": "\"1621457b3c1459\"" }
Disable a secret version that is scheduled for destruction
Console
In the Google Cloud console, go to the Secret Manager page.
Click the secret name. The Secret details page appears.
On the Secret details page, in the Versions table, select a secret version that is scheduled for destruction.
In the Actions column, click
View more, then click Disable.In the dialog that appears, click Disable selected versions.
gcloud
To disable a secret version that is scheduled for destruction, use the gcloud beta secrets versions disable command.
Before using any of the command data below, make the following replacements:
- SECRET_VERSION_ID: the ID of the version or fully qualified identifier for the version
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID
Windows (PowerShell)
gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID
Windows (cmd.exe)
gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID
The response contains the disabled version of the secret.
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: the Google Cloud project ID
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
- VERSION_ID: the ID of the version or fully qualified identifier for the version
HTTP method and URL:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable
Request JSON body:
{}
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name":"projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID", "createTime":"2023-10-16T17:21:55.920036Z", "state":"DISABLED", "replicationStatus":{ "automatic":{ } }, "etag":"\"1607d8b3e8e1bc\"" }
What's next
- Learn how to ensure data integrity.
- Learn about best practices.