This page describes how you can create regional secrets and enable customer-managed encryption keys (CMEK) for regional secrets. A regional secret refers to a secret (sensitive data like passwords or API keys) that is stored and managed within a specific location.
Before you begin
- Enable the Secret Manager API, once per project.
- Assign the Secret Manager Admin role (
roles/secretmanager.admin
) on the project, folder, or organization. Authenticate to the Secret Manager API using one of the following ways:
- If you use client libraries to access the Secret Manager API, set up Application Default Credentials.
- If you use the Google Cloud CLI to access the Secret Manager API, use your Google Cloud CLI credentials to authenticate.
- To authenticate a REST call, use either Google Cloud CLI credentials or Application Default Credentials.
Configure Secret Manager to use a regional endpoint
This section describes how to configure regional endpoints to access the Secret Manager resources. Regional endpoints are request endpoints that only allow requests to proceed if the affected resource exists in the location specified by the endpoint. Using regional endpoints lets you run your workloads in a manner that complies with data residency and data sovereignty requirements.
Regional endpoints use the following format:
SERVICE_NAME.LOCATION.rep.googleapis.com
To use regional endpoints, you must update your configuration with the regional endpoint address depending on how you access the Secret Manager service.
gcloud
To configure the Google Cloud CLI to use regional endpoints, complete the following steps:
Make sure you're using the Google Cloud CLI 402.0.0 or newer.
Set the
api_endpoint_overrides/secretmanager
property to the regional endpoint you want to use:gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.LOCATION.rep.googleapis.com/
Replace LOCATION with the name of the supported Google Cloud location, such as
me-central2
.
REST
To connect to the Secret Manager service using the API, replace the
generic API endpoint URL (https://secretmanager.googleapis.com/v1/
) with the
specific regional endpoint that you want to use. Regional endpoints use the
following format:
https://secretmanager.LOCATION.rep.googleapis.com/v1/
Replace LOCATION with the name of the supported Google Cloud location,
such as me-central2
.
To see which locations are supported, see Secret Manager locations.
Create a regional secret
You can create regional secrets through the Google Cloud console. Alternatively, you can use the Secret Manager API or the Google Cloud CLI.
console
Go to the Secret Manager page in the Google Cloud console.
Click the Regional secrets tab, and then click Create regional secret.
On the Create regional secret page, enter a name for the secret in the Name field. A secret name can contain uppercase and lowercase letters, numerals, hyphens, and underscores. The maximum allowed length for a name is 255 characters.
Enter a secret value. The secret value can be in any format but must not be larger than 64 KiB. You can also upload a text file containing the secret value using the Upload file option. This action automatically creates the secret version.
Select a location from the Region list.
Click Create secret.
gcloud
To create a regional 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
- LOCATION: the Google Cloud location where you want to store the secret data
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud secrets create SECRET_ID \ --location=LOCATION
Windows (PowerShell)
gcloud secrets create SECRET_ID ` --location=LOCATION
Windows (cmd.exe)
gcloud secrets create SECRET_ID ^ --location=LOCATION
The response contains the newly created regional secret.
REST
Before using any of the request data, make the following replacements:
- LOCATION: the Google Cloud location where you want to store the secret data
- 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:
POST https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?secretId=SECRET_ID
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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?secretId=SECRET_ID" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "/projects/my-project/locations/me-central2/secrets/my-drz-secret", "createTime": "2024-03-25T08:24:13.153705Z", "etag": "\"161477e6071da9\"" }
Create a regional secret with CMEK encryption
CMEK adds an extra layer of security and control over your sensitive data stored as regional secrets. You can use CMEK to meet the following goals:
- Have complete control over the encryption keys used to protect your secrets.
- Use your own key management system with potentially stricter security policies, auditing capabilities, and compliance features.
- Comply with data sovereignty regulations by keeping the keys within your own infrastructure.
- Define fine-grained access controls for your encryption keys, specifying who can use them and for what purposes.
To enable CMEK and to create the CMEK keys and key rings that you require for this step, see Enable customer-managed encryption keys for Secret Manager.
console
Go to the Secret Manager page in the Google Cloud console.
Click the Regional secrets tab, and then click Create regional secret.
Select a location from the Region list.
Under Encryption, select Customer-managed encryption key (CMEK), and then choose your CMEK key from the Encryption key list. Ensure your CMEK key exists in the specified location and that your Secret Manager project has the necessary permissions to use it.
Click Create secret.
gcloud
To create a regional 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
- LOCATION: the Google Cloud location where you want to store the secret data
- CMEK KEY: the fully qualified path to the specific CMEK key in Cloud Key Management Service that will protect the secret
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud secrets create SECRET_ID --location=LOCATION \ --regional-kms-key-name=CMEK KEY
Windows (PowerShell)
gcloud secrets create SECRET_ID --location=LOCATION ` --regional-kms-key-name=CMEK KEY
Windows (cmd.exe)
gcloud secrets create SECRET_ID --location=LOCATION ^ --regional-kms-key-name=CMEK KEY
The response contains the newly created regional secret.
REST
Before using any of the request data, make the following replacements:
- LOCATION: the Google Cloud location where you want to store the secret data
- PROJECT_ID: the Google Cloud project ID
- SECRET_ID: the ID of the secret or fully qualified identifier for the secret
- KMS_PROJECT_ID: the Google Cloud project ID that contains the key ring
- KEY_RING: the name of the key ring in Cloud Key Management Service that contains the key
- YOUR_CMEK_KEY: the specific Customer-Managed Encryption Key (CMEK) that you have created within your chosen key ring in Cloud Key Management Service
HTTP method and URL:
POST https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?secretId=SECRET_ID
Request JSON body:
{"customer_managed_encryption": {"kms_key_name":"projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/MY_CMEK_KEY"}}
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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?secretId=SECRET_ID" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/1034382619294/locations/me-central2/secrets/my-drz-secret", "createTime": "2024-03-27T13:30:07.437859Z", "etag": "\"1614a467b60423\"", "customerManagedEncryption": { "kmsKeyName": "projects/my-project/locations/me-central2/keyRings/test_keyring_to_check_rep/cryptoKeys/cmek-key-2" } }
Use the correct syntax for regional resources
When you access regional secrets and their versions using the Secret Manager API or the gcloud CLI, make sure that you use the correct resource syntax while making the API calls. Use the following as an example:
Syntax for a regional secret
projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_NAME
Syntax for a regional secret's version
projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_NAME/versions/VERSION_ID
Provide the following values:
LOCATION
: the Google Cloud location where the secret existsPROJECT_ID
: the Google Cloud project ID which contains the secretSECRET_NAME
: the name of your secretVERSION_ID
: version number or alias related to the specific secret version
Manage regional secrets
You interact with regional secrets, their versions, and perform all management operations (such as setting expiration, rotation, adding labels, annotations) in the same way as the default global secrets. Refer to the following list for some frequently used tasks:
- Access a secret version
- List secrets and view secret details
- Edit a secret
- Create rotation schedules
- Delete a secret
- Add a secret version
- View secret version details
- Set up notifications on a secret
What's next
- Learn about audit logging