A secret version contains the actual secret data, along with state and metadata about the secret. This topic describes how to manage a secret's versions.
Before you begin
Configure Secret Manager and your local environment, once per project.
Secret version states
A secret version can be in one of the following states at any given time:
Enabled - In this state, the secret version can be accessed and described. This is the default state for a new secret version.
Disabled - In this state, the secret version cannot be accessed, but the secret's contents still exist. The secret version can be re-enabled to restore access.
Destroyed - In this state, the secret version's contents are discarded. The secret version cannot be changed to another state.
Getting details about a secret version
These examples show how to get details about a secret version, except for the secret version's sensitive data, by viewing its metadata.
Viewing a secret version's metadata requires the Secret Viewer role
(roles/secretmanager.viewer
) on the secret, project, folder, or organization.
IAM roles can't be granted on a secret version.
Web UI
-
Go to the Secret Manager page in the Cloud Console.
-
On the Secret Manager page, click on the Name of a secret.
-
On the Secret details page, in the Versions table, locate a secret version to get.
-
Find the ID of the version in the table and read its metadata.
Command-line
To use Secret Manager on the command line, first Install or upgrade to version 306.0.0 or higher of the Cloud SDK.
$ gcloud secrets versions describe version-id --secret="secret-id"
C#
To run this code, first set up a C# development environment and install the Secret Manager C# SDK.
Go
To run this code, first set up a Go development environment and install the Secret Manager Go SDK.
Java
To run this code, first set up a Java development environment and install the Secret Manager Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK.
Python
To run this code, first set up a Python development environment and install the Secret Manager Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK.
API
These examples use curl to demonstrate using the API.
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id/versions/version-id" \
--request "GET" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json" \
--header "x-goog-user-project: project-id"
Listing a secret's versions
Listing secret versions returns all versions associated with the secret, and the state of each, whether enabled, disabled, or destroyed.
Listing secret versions requires the Secret Viewer role
(roles/secretmanager.viewer
) on the secret, project, folder, or organization.
IAM roles can't be granted on a secret version.
Web UI
-
Go to the Secret Manager page in the Cloud Console.
-
On the Secret Manager page, click on the Name of a secret.
-
The Secret details page displays the list of versions in the Versions table.
Command-line
To use Secret Manager on the command line, first Install or upgrade to version 306.0.0 or higher of the Cloud SDK.
$ gcloud secrets versions list secret-id
C#
To run this code, first set up a C# development environment and install the Secret Manager C# SDK.
Go
To run this code, first set up a Go development environment and install the Secret Manager Go SDK.
Java
To run this code, first set up a Java development environment and install the Secret Manager Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK.
Python
To run this code, first set up a Python development environment and install the Secret Manager Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK.
API
These examples use curl to demonstrate using the API.
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id/versions" \
--request "GET" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json" \
--header "x-goog-user-project: project-id"
Disabling a secret version
When you disable a secret version, it can't be accessed. Disabling a secret is reversible.
Disabling a secret version requires the Secret Admin role
(roles/secretmanager.admin
) on the secret, project, folder, or organization.
IAM roles can't be granted on a secret version.
Web UI
-
Go to the Secret Manager page in the Cloud Console.
-
On the Secret Manager page, click on the Name of a secret.
-
On the Secret details page, in the Versions table, locate a secret version to access.
-
In the Actions column, click View more
. -
Click Disable from the menu.
-
In the Disable secret version dialog, click the Disable selected versions button.
Command-line
To use Secret Manager on the command line, first Install or upgrade to version 306.0.0 or higher of the Cloud SDK.
$ gcloud secrets versions disable version-id --secret="secret-id"
C#
To run this code, first set up a C# development environment and install the Secret Manager C# SDK.
Go
To run this code, first set up a Go development environment and install the Secret Manager Go SDK.
Java
To run this code, first set up a Java development environment and install the Secret Manager Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK.
Python
To run this code, first set up a Python development environment and install the Secret Manager Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK.
API
These examples use curl to demonstrate using the API.
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id/versions/version-id?updateMask=state" \
--request "POST" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json" \
--header "x-goog-user-project: project-id" \
--data "{\"state\": \"DISABLED\"}"
Enable a secret version
When you enable a disabled secret, it can be accessed again.
Enabling a secret version requires the Secret Admin role
(roles/secretmanager.admin
) on the secret, project, folder, or organization.
IAM roles can't be granted on a secret version.
Web UI
-
Go to the Secret Manager page in the Cloud Console.
-
On the Secret Manager page, click on the Name of a secret.
-
On the Secret details page, in the Versions table, locate a secret version to access.
-
In the Actions column, click View more
. -
Click Enable from the menu.
-
In the Enable secret version dialog, click the Enable selected versions button.
Command-line
To use Secret Manager on the command line, first Install or upgrade to version 306.0.0 or higher of the Cloud SDK.
$ gcloud secrets versions enable version-id --secret="secret-id"
C#
To run this code, first set up a C# development environment and install the Secret Manager C# SDK.
Go
To run this code, first set up a Go development environment and install the Secret Manager Go SDK.
Java
To run this code, first set up a Java development environment and install the Secret Manager Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK.
Python
To run this code, first set up a Python development environment and install the Secret Manager Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK.
API
These examples use curl to demonstrate using the API.
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id/versions/version-id?updateMask=state" \
--request "POST" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json" \
--header "x-goog-user-project: project-id" \
--data "{\"state\": \"ENABLED\"}"
Destroy a secret version
When you destroy a secret version, it can't be accessed. Destroying a secret version is permanent. Before destroying a secret version, try disabling it and observe your application's behavior. You can re-enable the secret version if you encounter unexpected issues.
When you disable or destroy a secret or secret version, the change takes time to propagate through the system. If necessary, you can revoke IAM access to the secret. Changes to IAM permissions are consistent within seconds.
Destroying a secret version requires the Secret Admin role
(roles/secretmanager.admin
) on the secret, project, folder, or organization.
IAM roles can't be granted on a secret version.
Web UI
-
Go to the Secret Manager page in the Cloud Console.
-
On the Secret Manager page, click on the Name of a secret.
-
On the Secret details page, in the Versions table, locate a secret version to access.
-
In the Actions column, click View more
. -
Click Destroy from the menu.
-
In the Destroy secret version dialog, enter the name of the secret.
-
Click the Destroy selected versions button.
Command-line
To use Secret Manager on the command line, first Install or upgrade to version 306.0.0 or higher of the Cloud SDK.
$ gcloud secrets versions destroy version-id --secret="secret-id"
C#
To run this code, first set up a C# development environment and install the Secret Manager C# SDK.
Go
To run this code, first set up a Go development environment and install the Secret Manager Go SDK.
Java
To run this code, first set up a Java development environment and install the Secret Manager Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK.
Python
To run this code, first set up a Python development environment and install the Secret Manager Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK.
API
These examples use curl to demonstrate using the API.
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id/versions/version-id:destroy" \
--request "POST" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json" \
--header "x-goog-user-project: project-id"
What's next?
- Learn more about managing secrets.
- Learn more about managing access to secrets.
- Learn more about creating and accessing secrets.