This topic describes how to create a secret, add a secret version, and access a secret version. For information about managing secrets, see Managing secrets.
Before you begin
Configure Secret Manager and your local environment, once per project.
Creating a secret
A secret contains one or more secret versions, along with metadata such as labels and replication information. The actual contents of a secret are stored in a secret version.
If you aren't sure which replication policy is right for your secret, see Choosing A Replication Policy.
Creating a secret requires the Secret Manager Admin role
(roles/secretmanager.admin
) on the project, folder, or organization.
Console
-
Go to the Secret Manager page in the console.
-
On the Secret Manager page, click Create Secret.
-
On the Create secret page, under Name, enter a name for the secret (e.g.
my-secret
). -
(Optional) To also add a secret version when creating the initial secret, in the Secret value field, enter a value for the secret (e.g.
abcd1234
). -
Leave the Regions section unchanged.
-
Click the Create secret button.
gcloud
To use Secret Manager on the command line, first Install or upgrade to version 338.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
$ gcloud secrets create secret-id \
--replication-policy="automatic"
C#
To run this code, first set up a C# development environment and install the Secret Manager C# SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Go
To run this code, first set up a Go development environment and install the Secret Manager Go SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Java
To run this code, first set up a Java development environment and install the Secret Manager Java SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Node.js
To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Python
To run this code, first set up a Python development environment and install the Secret Manager Python SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Ruby
To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
API
These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets?secretId=secret-id" \
--request "POST" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json" \
--data "{\"replication\": {\"automatic\": {}}}"
Adding a secret version
A secret version contains the actual contents of a secret. A secret version can be enabled, disabled, or destroyed. To change the contents of a secret, you create a new version.
Adding a secret version requires the Secret Manager Admin role
(roles/secretmanager.admin
) on the secret, project, folder, or organization.
Roles can't be granted on a secret version.
Console
-
Go to the Secret Manager page in the console.
-
On the Secret Manager page, click View more
and select Add new version. -
In the Add new version dialog, in the Secret value field, enter a value for the secret (e.g.
abcd1234
). -
Click the Add new version button.
gcloud
To use Secret Manager on the command line, first Install or upgrade to version 338.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Add a secret version from the contents of a file on disk:
$ gcloud secrets versions add secret-id --data-file="/path/to/file.txt"
You can also add a secret version directly on the command line, but this is discouraged because the plaintext will appear in your shell history:
$ echo -n "this is my super secret data" | \
gcloud secrets versions add secret-id --data-file=-
Optionally: Add a version from a file's contents when first creating a secret:
$ gcloud secrets create secret-id --data-file="/path/to/file.txt"
C#
To run this code, first set up a C# development environment and install the Secret Manager C# SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Go
To run this code, first set up a Go development environment and install the Secret Manager Go SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Java
To run this code, first set up a Java development environment and install the Secret Manager Java SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Node.js
To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Python
To run this code, first set up a Python development environment and install the Secret Manager Python SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Ruby
To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
API
These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Base64-encode the secret data and save it as a shell variable.
$ SECRET_DATA=$(echo "seCr3t" | base64)
Invoke the API using curl.
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id:addVersion" \
--request "POST" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json" \
--data "{\"payload\": {\"data\": \"${SECRET_DATA}\"}}"
Accessing a secret version
Accessing a secret version returns the secret contents, as well as additional
metadata about the secret version. When you access a secret version, you specify
its version-id or alias if assigned. You can also access the latest version of a secret by
specifying "latest"
as the version.
Accessing a secret version requires the Secret Manager
Secret Accessor role (roles/secretmanager.secretAccessor
)
on the secret, project, folder, or organization. IAM roles can't be
granted on a secret version.
Resource consistency
In Secret Manager, adding a secret version and then immediately accessing that secret version is a strongly consistent operation. Other operations within Secret Manager are eventually consistent. Eventually consistent operations typically converge within minutes, but may take a few hours.
Propagating IAM permissions is eventually consistent. This means granting or revoking access to secrets may not take effect immediately. For more information, see the IAM documentation.
Console
-
Go to the Secret Manager page in the 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 View secret value from the menu.
-
You will see dialog that shows the secret version value. Click Done to finish.
gcloud
To use Secret Manager on the command line, first Install or upgrade to version 338.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Access a secret version:
$ gcloud secrets versions access version-id --secret="secret-id"
Accessing a binary secret version:
$ gcloud secrets versions access version-id --secret="secret-id" --format='get(payload.data)' | tr '_-' '/+' | base64 -d
C#
To run this code, first set up a C# development environment and install the Secret Manager C# SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Go
To run this code, first set up a Go development environment and install the Secret Manager Go SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Java
To run this code, first set up a Java development environment and install the Secret Manager Java SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Node.js
To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Python
To run this code, first set up a Python development environment and install the Secret Manager Python SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Ruby
To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
API
These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id/versions/version-id:access" \
--request "GET" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json"
The response payload.data
is the base64-encoded contents of the secret version. Here is an example of extracting the secret using the jq
tool:
$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id/versions/version-id:access" \
--request "GET" \
--header "authorization: Bearer $(gcloud auth print-access-token)" \
--header "content-type: application/json" \
| jq -r ".payload.data" | base64 --decode
What's next?
- Learn more about managing secrets and secret versions.
- Learn more about managing access to secrets.