Create regional secrets

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.

Go to Secret Manager
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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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.

Go to Secret Manager
Click the Regional secrets tab, and then click Create regional secret.
Enter a secret name and value.
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 exists
PROJECT_ID: the Google Cloud project ID which contains the secret
SECRET_NAME: the name of your secret
VERSION_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:

What's next

Learn about audit logging