Assign an alias to a regional secret version

You can assign aliases to secret versions for easier access. After an alias is assigned, you can access the secret versions using their aliases in the same way that you can access secret versions by their version number.

Required roles

To get the permissions that you need to assign an alias to a secret version, ask your administrator to grant you the Secret Manager Admin ( roles/secretmanager.admin ) IAM role on the secret, project, folder, or organization. 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 .

Assign an alias to a secret version

To assign an alias to a secret version, use one of the following methods:

Console

In the Google Cloud console, go to the Secret Manager page.

Go to Secret Manager
On the Secret Manager page, click the Regional secrets tab.
To edit a secret, use one of the following methods:
- Click Actions for the secret that you want to edit, and then click Edit .
- Click the secret name to go to the secret details page. On the secret details page, click Edit secret .
On the Edit secret page, go to Version aliases , and then click Add alias .
Do the following:
1. Specify the alias name.
2. Select the secret version to which you will assign this alias.
Click Update secret .

gcloud

Before using any of the command data below, make the following replacements:

SECRET_ID : the ID of the secret
LOCATION : the Google Cloud location of the secret
KEY : the version alias
VALUE : the secret version number

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud  
secrets  
update  
 SECRET_ID 
  
--location = 
 LOCATION 
  
 \ 
  
--update-version-aliases = 
  KEY 
 
 = 
 VALUE

Windows (PowerShell)

gcloud  
secrets  
update  
 SECRET_ID 
  
--location = 
 LOCATION 
  
 ` 
  
--update-version-aliases = 
  KEY 
 
 = 
 VALUE

Windows (cmd.exe)

gcloud  
secrets  
update  
 SECRET_ID 
  
--location = 
 LOCATION 
  
^  
--update-version-aliases = 
  KEY 
 
 = 
 VALUE

The response contains the updated secret.

REST

Before using any of the request data, make the following replacements:

LOCATION : the Google Cloud location of the secret
PROJECT_ID : the Google Cloud project ID
SECRET_ID : the ID of the secret
KEY : the version alias
VALUE : the secret version number

HTTP method and URL:

PATCH https://secretmanager. LOCATION 
.rep.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/secrets/ SECRET_ID 
?updateMask=version_aliases

Request JSON body:

{'version_aliases': {' KEY 
': ' VALUE 
'}}

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 PATCH \
-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/ SECRET_ID 
?updateMask=version_aliases"

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 PATCH `
-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/ SECRET_ID 
?updateMask=version_aliases" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/ PROJECT_ID 
/locations/ LOCATION 
/secrets/ SECRET_ID 
",
  "createTime": "2024-09-04T06:34:32.995517Z",
  "etag": "\"16214584d1479c\"",
  "versionAliases": {
    "nonprod": "1"
  }
}

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 .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 secretmanager 
  
 "cloud.google.com/go/secretmanager/apiv1" 
  
 "cloud.google.com/go/secretmanager/apiv1/secretmanagerpb" 
  
 "google.golang.org/api/option" 
  
 "google.golang.org/genproto/protobuf/field_mask" 
 ) 
 // updateSecret updates the alias map on an existing secret. 
 func 
  
 UpdateRegionalSecretWithAlias 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectId 
 , 
  
 locationId 
 , 
  
 secretId 
  
 string 
 ) 
  
 error 
  
 { 
  
 // name := "projects/my-project/locations/my-location/secrets/my-secret" 
  
 // Create the client. 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 //Endpoint to send the request to regional server 
  
 endpoint 
  
 := 
  
 fmt 
 . 
 Sprintf 
 ( 
 "secretmanager.%s.rep.googleapis.com:443" 
 , 
  
 locationId 
 ) 
  
 client 
 , 
  
 err 
  
 := 
  
 secretmanager 
 . 
  NewClient 
 
 ( 
 ctx 
 , 
  
 option 
 . 
 WithEndpoint 
 ( 
 endpoint 
 )) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to create regional secretmanager client: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
  Close 
 
 () 
  
 name 
  
 := 
  
 fmt 
 . 
 Sprintf 
 ( 
 "projects/%s/locations/%s/secrets/%s" 
 , 
  
 projectId 
 , 
  
 locationId 
 , 
  
 secretId 
 ) 
  
 // Build the request. 
  
 req 
  
 := 
  
& secretmanagerpb 
 . 
 UpdateSecretRequest 
 { 
  
 Secret 
 : 
  
& secretmanagerpb 
 . 
 Secret 
 { 
  
 Name 
 : 
  
 name 
 , 
  
 VersionAliases 
 : 
  
 map 
 [ 
 string 
 ] 
 int64 
 { 
  
 "test" 
 : 
  
 1 
 , 
  
 }, 
  
 }, 
  
 UpdateMask 
 : 
  
& field_mask 
 . 
 FieldMask 
 { 
  
 Paths 
 : 
  
 [] 
 string 
 { 
 "version_aliases" 
 }, 
  
 }, 
  
 } 
  
 // Call the API. 
  
 result 
 , 
  
 err 
  
 := 
  
 client 
 . 
 UpdateSecret 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to update regional secret: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Updated regional secret: %s\n" 
 , 
  
 result 
 . 
 Name 
 ) 
  
 return 
  
 nil 
 }

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 .

  import 
  
 com.google.cloud.secretmanager.v1. Secret 
 
 ; 
 import 
  
 com.google.cloud.secretmanager.v1. SecretManagerServiceClient 
 
 ; 
 import 
  
 com.google.cloud.secretmanager.v1. SecretManagerServiceSettings 
 
 ; 
 import 
  
 com.google.cloud.secretmanager.v1. SecretName 
 
 ; 
 import 
  
 com.google.protobuf. FieldMask 
 
 ; 
 import 
  
 com.google.protobuf.util. FieldMaskUtil 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 UpdateRegionalSecretWithAlias 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 // Your GCP project ID. 
  
 String 
  
 projectId 
  
 = 
  
 "your-project-id" 
 ; 
  
 // Location of the secret. 
  
 String 
  
 locationId 
  
 = 
  
 "your-location-id" 
 ; 
  
 // Resource ID of the secret to update. 
  
 String 
  
 secretId 
  
 = 
  
 "your-secret-id" 
 ; 
  
 updateRegionalSecretWithAlias 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 secretId 
 ); 
  
 } 
  
 // Update an existing secret using an alias. 
  
 public 
  
 static 
  
  Secret 
 
  
 updateRegionalSecretWithAlias 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 locationId 
 , 
  
 String 
  
 secretId 
 ) 
  
  
 throws 
  
 IOException 
  
 { 
  
 // Endpoint to call the regional secret manager sever 
  
 String 
  
 apiEndpoint 
  
 = 
  
 String 
 . 
 format 
 ( 
 "secretmanager.%s.rep.googleapis.com:443" 
 , 
  
 locationId 
 ); 
  
  SecretManagerServiceSettings 
 
  
 secretManagerServiceSettings 
  
 = 
  
  SecretManagerServiceSettings 
 
 . 
 newBuilder 
 (). 
 setEndpoint 
 ( 
 apiEndpoint 
 ). 
 build 
 (); 
  
 // Initialize the client that will be used to send requests. This client only needs to be 
  
 // created once, and can be reused for multiple requests. 
  
 try 
  
 ( 
  SecretManagerServiceClient 
 
  
 client 
  
 = 
  
  
  SecretManagerServiceClient 
 
 . 
 create 
 ( 
 secretManagerServiceSettings 
 )) 
  
 { 
  
 // Build the name. 
  
  SecretName 
 
  
 secretName 
  
 = 
  
  
  SecretName 
 
 . 
  ofProjectLocationSecretName 
 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 secretId 
 ); 
  
 // Build the updated secret. 
  
  Secret 
 
 . 
 Builder 
  
 secret 
  
 = 
  
  Secret 
 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 secretName 
 . 
  toString 
 
 ()); 
  
 secret 
 . 
  getMutableVersionAliases 
 
 (). 
 put 
 ( 
 "test" 
 , 
  
 1L 
 ); 
  
  
 // Build the field mask. 
  
  FieldMask 
 
  
 fieldMask 
  
 = 
  
  FieldMaskUtil 
 
 . 
 fromString 
 ( 
 "version_aliases" 
 ); 
  
 // Update the secret. 
  
  Secret 
 
  
 updatedSecret 
  
 = 
  
 client 
 . 
 updateSecret 
 ( 
 secret 
 . 
 build 
 (), 
  
 fieldMask 
 ); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Updated alias map: %s\n" 
 , 
  
  
 updatedSecret 
 . 
  getVersionAliasesMap 
 
 (). 
 toString 
 ()); 
  
 return 
  
 updatedSecret 
 ; 
  
 } 
  
 } 
 }

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 .

  /** 
 * TODO(developer): Uncomment these variables before running the sample. 
 */ 
 // const projectId = 'my-project'; 
 // const locationId = 'my-location'; 
 // const secretId = 'my-secret'; 
 const 
  
 name 
  
 = 
  
 `projects/ 
 ${ 
 projectId 
 } 
 /locations/ 
 ${ 
 locationId 
 } 
 /secrets/ 
 ${ 
 secretId 
 } 
 ` 
 ; 
 // Imports the Secret Manager library 
 const 
  
 { 
 SecretManagerServiceClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/secret-manager 
' 
 ); 
 // Adding the endpoint to call the regional secret manager sever 
 const 
  
 options 
  
 = 
  
 {}; 
 options 
 . 
 apiEndpoint 
  
 = 
  
 `secretmanager. 
 ${ 
 locationId 
 } 
 .rep.googleapis.com` 
 ; 
 // Instantiates a client 
 const 
  
 client 
  
 = 
  
 new 
  
  SecretManagerServiceClient 
 
 ( 
 options 
 ); 
 async 
  
 function 
  
 updateRegionalSecret 
 () 
  
 { 
  
 const 
  
 [ 
 secret 
 ] 
  
 = 
  
 await 
  
 client 
 . 
 updateSecret 
 ({ 
  
 secret 
 : 
  
 { 
  
 name 
 : 
  
 name 
 , 
  
 versionAliases 
 : 
  
 { 
  
 test 
 : 
  
 1 
 , 
  
 }, 
  
 }, 
  
 updateMask 
 : 
  
 { 
  
 paths 
 : 
  
 [ 
 'version_aliases' 
 ], 
  
 }, 
  
 }); 
  
 console 
 . 
 info 
 ( 
 `Updated secret 
 ${ 
 secret 
 . 
 name 
 } 
 ` 
 ); 
 } 
 updateRegionalSecret 
 ();

What's next

Learn how to list regional secret versions and view version details .
Learn how to ensure data integrity when adding and accessing secret versions.

Assign an alias to a regional secret version Stay organized with collections Save and categorize content based on your preferences.

Required roles

Assign an alias to a secret version

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

Go

Java

Node.js

What's next

Assign an alias to a regional secret version