feat: added regional secret support for secret-manager (#3365)

Issue: #3331

Description:

Added the support for regional secret creation/updation, deletion and fetch for secret manager service.

Updated the autoconfigure/secretmanager to create the regional client and secretmanager module to support the regional secret operation.
Added the optional property location in GcpSecretManagerProperties.java which will take region from application.properties file. Whenever the location is available, it will use to perform the operation on regional secret. If not provided the global stack will be served.
Updated the documentation for this additional property in the docs/src/main/asciidoc/secretmanager.adoc
Added the sample application for regional secret operations.
Added/Updated the unit and integration tests.
Note: Fixed the integration test testUpdateSecrets in the file secretmanager/it/SecretManagerTemplateIntegrationTests.java

Performed the below mentioned manual unit tests to validate the working of the global and regional secret operations.

Create secret with only secretId and payload
Create secret with existing secretId and payload
Create secret with secretId, payload and valid projectID
Create secret with secretId, payload and invalid projectID (project on which user doesn't have access)
Read an existing secret with secretId
Read a non-existing secret with secretId
Read a secret with secretId and existing version
Read a secret with secretId and disabled version
Read a secret with secretId and destroyed version
Read a secret with secretId and non-existing version
Read a secret with secretId and valid project
Read a secret with secretId and invalid project (project on which user doesn't have access)
Read a secret with secretId and existing version and valid project
Read a secret with secretId and existing version and invalid project
Read a secret with secretId and non-existing version and valid project
Read a secret with secretId and non-existing version and invalid project
Update an existing secret with only secretId and payload
Update an existing secret with secretId, payload and valid projectID
Update an existing secret with secretId, payload and invalid projectID (project on which user doesn't have access)
Delete an existing secret with secretId
Delete a non-existing secret with secretId
Delete a secret with secretId and valid projectId
Delete a secret with secretId and invalid projectId
Enable an existing secret and valid version
Enable an existing secret without version
Enable an existing secret and invalid version
Enable a non-existing secret
Disable an existing secret and valid version
Disable an existing secret without version
Disable an existing secret and invalid version
Disable a non-existing secret
Check if secret exists for existing secret
Check if secret exists for non-existing secret
Check if secret exists for existing secret & valid projectId
Check if secret exists for existing secret & invalid projectId
Read secret with secretId and other project using service account
Inject secret with the @value annotation
More information about regional secrets: https://cloud.google.com/secret-manager/regional-secrets/data-residency

Author: abheda-crest

docs/src/main/asciidoc/secretmanager.adoc

@@ -56,12 +56,15 @@ This allows you to specify and load secrets from Google Cloud Secret Manager as
 
 The Secret Manager config data resource uses the following syntax to specify secrets:
 
+== Global Secrets
+The following formats apply to **global secrets**, where secrets are stored without specifying a region.
+
 [source]
 ----
 # 1. Long form - specify the project ID, secret ID, and version
 sm@projects/<project-id>/secrets/<secret-id>/versions/<version-id>}
 
-# 2.  Long form - specify project ID, secret ID, and use latest version
+# 2. Long form - specify project ID, secret ID, and use latest version
 sm@projects/<project-id>/secrets/<secret-id>
 
 # 3. Short form - specify project ID, secret ID, and version
@@ -78,6 +81,28 @@ sm@<secret-id>/<version>
 sm@<secret-id>
 ----
 
+== Regional Secrets
+The following formats apply to **regional secrets**, where secrets are stored in a specific Google Cloud region.
+For more details, see https://cloud.google.com/secret-manager/regional-secrets/data-residency[Google Cloud Regional Secrets].
+
+[source]
+----
+# 6. Long form - specify project ID, location ID, secret ID, and version
+sm@projects/<project-id>/locations/<location-id>/secrets/<secret-id>/versions/<version-id>
+
+# 7. Long form - specify project ID, location ID, secret ID, and use latest version
+sm@projects/<project-id>/locations/<location-id>/secrets/<secret-id>
+
+# 8. Short form - specify project ID, location ID, secret ID, and version
+sm@<project-id>/<location-id>/<secret-id>/<version-id>
+
+# 9. Short form - specify location ID, secret ID, version and use default project
+sm@locations/<location-id>/<secret-id>/<version>
+
+# 10. Shortest form - specify location ID, secret ID, and use default project and latest version
+sm@locations/<location-id>/<secret-id>
+----
+
 You can use this syntax in the following places:
 
 1. In your `application.properties` file:

spring-cloud-gcp-autoconfigure/src/main/java/com/google/cloud/spring/autoconfigure/secretmanager/DefaultSecretManagerServiceClientFactory.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.spring.autoconfigure.secretmanager;
+
+import static com.google.cloud.spring.secretmanager.SecretManagerTemplate.GLOBAL_LOCATION;
+
+import com.google.api.gax.core.CredentialsProvider;
+import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
+import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
+import com.google.cloud.spring.core.UserAgentHeaderProvider;
+import com.google.cloud.spring.secretmanager.SecretManagerServiceClientFactory;
+import java.io.IOException;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import javax.annotation.Nullable;
+import org.springframework.stereotype.Component;
+import org.springframework.util.ObjectUtils;
+
+/**
+ * A default implementation of the {@link SecretManagerServiceClientFactory} interface.
+ *
+ * <p>This factory provides a caching layer for {@link SecretManagerServiceClient} instances.
+ * Clients are created using the provided {@link CredentialsProvider} and a {@link
+ * UserAgentHeaderProvider} that adds the Spring Cloud GCP agent header to the client.
+ *
+ */
+@Component
+public class DefaultSecretManagerServiceClientFactory implements SecretManagerServiceClientFactory {
+
+  private final CredentialsProvider credentialsProvider;
+  private final Map<String, SecretManagerServiceClient> clientCache = new ConcurrentHashMap<>();
+
+  DefaultSecretManagerServiceClientFactory(CredentialsProvider credentialsProvider, SecretManagerServiceClient client) {
+    this.credentialsProvider = credentialsProvider;
+    this.clientCache.putIfAbsent(GLOBAL_LOCATION, client);
+  }
+
+  @Override
+  public SecretManagerServiceClient getClient(@Nullable String location) {
+    if (ObjectUtils.isEmpty(location)) {
+      location = GLOBAL_LOCATION;
+    }
+    return clientCache.computeIfAbsent(location, loc -> {
+      try {
+        SecretManagerServiceSettings.Builder settings = SecretManagerServiceSettings.newBuilder()
+            .setCredentialsProvider(credentialsProvider)
+            .setHeaderProvider(new UserAgentHeaderProvider(SecretManagerConfigDataLoader.class));
+        if (!loc.equals(GLOBAL_LOCATION)) {
+          settings.setEndpoint(String.format("secretmanager.%s.rep.googleapis.com:443", loc));
+        }
+        return SecretManagerServiceClient.create(settings.build());
+      } catch (IOException e) {
+        throw new RuntimeException(
+            "Failed to create SecretManagerServiceClient for location: " + loc, e);
+      }
+    });
+  }
+}

spring-cloud-gcp-autoconfigure/src/main/java/com/google/cloud/spring/autoconfigure/secretmanager/GcpSecretManagerAutoConfiguration.java

@@ -22,8 +22,10 @@
 import com.google.cloud.spring.autoconfigure.core.GcpContextAutoConfiguration;
 import com.google.cloud.spring.core.GcpProjectIdProvider;
 import com.google.cloud.spring.core.UserAgentHeaderProvider;
+import com.google.cloud.spring.secretmanager.SecretManagerServiceClientFactory;
 import com.google.cloud.spring.secretmanager.SecretManagerTemplate;
 import java.io.IOException;
+import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.AutoConfigureAfter;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
@@ -32,6 +34,7 @@
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
 
+
 /**
  *  Autoconfiguration for GCP Secret Manager.
  *
@@ -63,22 +66,36 @@ public GcpSecretManagerAutoConfiguration(
 
   @Bean
   @ConditionalOnMissingBean
-  public SecretManagerServiceClient secretManagerClient()
-      throws IOException {
+  public SecretManagerServiceClient secretManagerClient() throws IOException {
     SecretManagerServiceSettings settings =
         SecretManagerServiceSettings.newBuilder()
             .setCredentialsProvider(this.credentialsProvider)
-            .setHeaderProvider(
-                new UserAgentHeaderProvider(GcpSecretManagerAutoConfiguration.class))
+            .setHeaderProvider(new UserAgentHeaderProvider(GcpSecretManagerAutoConfiguration.class))
             .build();
-
     return SecretManagerServiceClient.create(settings);
   }
 
   @Bean
   @ConditionalOnMissingBean
-  public SecretManagerTemplate secretManagerTemplate(SecretManagerServiceClient client) {
-    return new SecretManagerTemplate(client, this.gcpProjectIdProvider)
-        .setAllowDefaultSecretValue(this.properties.isAllowDefaultSecret());
+  public SecretManagerServiceClientFactory clientFactory(SecretManagerServiceClient client) {
+    return new DefaultSecretManagerServiceClientFactory(this.credentialsProvider, client);
+  }
+
+
+  @Bean
+  @ConditionalOnMissingBean
+  public SecretManagerTemplate secretManagerTemplate(
+      SecretManagerServiceClient client, ObjectProvider<SecretManagerServiceClientFactory> clientFactoryProvider) {
+
+    SecretManagerServiceClientFactory clientFactory = clientFactoryProvider.getIfAvailable();
+
+    if (clientFactory != null) {
+      return new SecretManagerTemplate(clientFactory, this.gcpProjectIdProvider)
+          .setAllowDefaultSecretValue(this.properties.isAllowDefaultSecret());
+    } else {
+      return new SecretManagerTemplate(client, this.gcpProjectIdProvider)
+          .setAllowDefaultSecretValue(this.properties.isAllowDefaultSecret());
+    }
   }
+
 }

spring-cloud-gcp-autoconfigure/src/main/java/com/google/cloud/spring/autoconfigure/secretmanager/SecretManagerConfigDataLoader.java

@@ -40,7 +40,8 @@ public ConfigData load(
     GcpProjectIdProvider projectIdProvider = context.getBootstrapContext()
         .get(GcpProjectIdProvider.class);
 
-    return new ConfigData(Collections.singleton(new SecretManagerPropertySource(
-        "spring-cloud-gcp-secret-manager", secretManagerTemplate, projectIdProvider)));
+    SecretManagerPropertySource secretManagerPropertySource = new SecretManagerPropertySource(
+        "spring-cloud-gcp-secret-manager", secretManagerTemplate, projectIdProvider);
+    return new ConfigData(Collections.singleton(secretManagerPropertySource));
   }
 }

spring-cloud-gcp-autoconfigure/src/main/java/com/google/cloud/spring/autoconfigure/secretmanager/SecretManagerConfigDataLocationResolver.java

@@ -19,13 +19,15 @@
 import static com.google.cloud.spring.secretmanager.SecretManagerSyntaxUtils.getMatchedPrefixes;
 import static com.google.cloud.spring.secretmanager.SecretManagerSyntaxUtils.warnIfUsingDeprecatedSyntax;
 
+import com.google.api.gax.core.CredentialsProvider;
 import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
 import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
 import com.google.cloud.spring.autoconfigure.core.GcpProperties;
 import com.google.cloud.spring.core.DefaultCredentialsProvider;
 import com.google.cloud.spring.core.DefaultGcpProjectIdProvider;
 import com.google.cloud.spring.core.GcpProjectIdProvider;
 import com.google.cloud.spring.core.UserAgentHeaderProvider;
+import com.google.cloud.spring.secretmanager.SecretManagerServiceClientFactory;
 import com.google.cloud.spring.secretmanager.SecretManagerTemplate;
 import java.io.IOException;
 import java.util.Collections;
@@ -52,6 +54,10 @@ public class SecretManagerConfigDataLocationResolver implements
    * A static client to avoid creating another client after refreshing.
    */
   private static SecretManagerServiceClient secretManagerServiceClient;
+  /**
+   * A static client factory to avoid creating another client after refreshing.
+   */
+  private static SecretManagerServiceClientFactory secretManagerServiceClientFactory;
 
   /**
    * Checks if the property can be resolved by the Secret Manager resolver.
@@ -104,8 +110,15 @@ private static void registerSecretManagerBeans(ConfigDataLocationResolverContext
     // Register the Core properties.
     registerBean(context, GcpProperties.class, getGcpProperties(context));
     // Register the Secret Manager properties.
-    registerBean(
-        context, GcpSecretManagerProperties.class, getSecretManagerProperties(context));
+    registerBean(context, GcpSecretManagerProperties.class, getSecretManagerProperties(context));
+    // Register the CredentialsProvider.
+    registerBean(context, CredentialsProvider.class, getCredentialsProvider(context));
+    // Register the Secret Manager client factory.
+    registerAndPromoteBean(
+        context,
+        SecretManagerServiceClientFactory.class,
+        BootstrapRegistry.InstanceSupplier.from(
+            () -> createSecretManagerServiceClientFactory(context)));
     // Register the Secret Manager client.
     registerAndPromoteBean(
         context,
@@ -135,6 +148,20 @@ private static GcpSecretManagerProperties getSecretManagerProperties(
         .orElse(new GcpSecretManagerProperties());
   }
 
+  private static CredentialsProvider getCredentialsProvider(
+      ConfigDataLocationResolverContext context) {
+    try {
+      GcpSecretManagerProperties properties =
+          context.getBootstrapContext().get(GcpSecretManagerProperties.class);
+      return context.getBinder()
+          .bind(GcpSecretManagerProperties.PREFIX, CredentialsProvider.class)
+          .orElse(new DefaultCredentialsProvider(properties));
+    } catch (IOException e) {
+      throw new RuntimeException(
+          "Failed to create the Secret Manager Client Factory for ConfigData loading.", e);
+    }
+  }
+
   @VisibleForTesting
   static GcpProjectIdProvider createProjectIdProvider(ConfigDataLocationResolverContext context) {
     ConfigurableBootstrapContext bootstrapContext = context.getBootstrapContext();
@@ -176,17 +203,36 @@ static synchronized SecretManagerServiceClient createSecretManagerClient(
     }
   }
 
+  @VisibleForTesting
+  static synchronized SecretManagerServiceClientFactory createSecretManagerServiceClientFactory(
+      ConfigDataLocationResolverContext context) {
+    if (secretManagerServiceClientFactory != null) {
+      return secretManagerServiceClientFactory;
+    }
+    SecretManagerServiceClient client = context.getBootstrapContext()
+        .get(SecretManagerServiceClient.class);
+    return new DefaultSecretManagerServiceClientFactory(
+        context.getBootstrapContext().get(CredentialsProvider.class), client);
+  }
+
   private static SecretManagerTemplate createSecretManagerTemplate(
       ConfigDataLocationResolverContext context) {
     SecretManagerServiceClient client = context.getBootstrapContext()
         .get(SecretManagerServiceClient.class);
+    SecretManagerServiceClientFactory clientFactory = context.getBootstrapContext()
+        .get(SecretManagerServiceClientFactory.class);
     GcpProjectIdProvider projectIdProvider = context.getBootstrapContext()
         .get(GcpProjectIdProvider.class);
     GcpSecretManagerProperties properties = context.getBootstrapContext()
         .get(GcpSecretManagerProperties.class);
 
-    return new SecretManagerTemplate(client, projectIdProvider)
-        .setAllowDefaultSecretValue(properties.isAllowDefaultSecret());
+    if (clientFactory != null) {
+      return new SecretManagerTemplate(clientFactory, projectIdProvider)
+          .setAllowDefaultSecretValue(properties.isAllowDefaultSecret());
+    } else {
+      return new SecretManagerTemplate(client, projectIdProvider)
+          .setAllowDefaultSecretValue(properties.isAllowDefaultSecret());
+    }
   }
 
   /**
@@ -223,4 +269,10 @@ private static <T> void registerAndPromoteBean(
   static void setSecretManagerServiceClient(SecretManagerServiceClient client) {
     secretManagerServiceClient = client;
   }
+
+  @VisibleForTesting
+  static void setSecretManagerServiceClientFactory(
+      SecretManagerServiceClientFactory clientFactory) {
+    secretManagerServiceClientFactory = clientFactory;
+  }
 }

spring-cloud-gcp-autoconfigure/src/test/java/com/google/cloud/spring/autoconfigure/secretmanager/GcpSecretManagerAutoConfigurationUnitTests.java

@@ -17,13 +17,12 @@
 package com.google.cloud.spring.autoconfigure.secretmanager;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.mockito.Mockito.mock;
 
 import com.google.api.gax.core.CredentialsProvider;
-import com.google.auth.Credentials;
 import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
 import com.google.cloud.spring.autoconfigure.TestUtils;
 import com.google.cloud.spring.autoconfigure.core.GcpContextAutoConfiguration;
+import com.google.cloud.spring.secretmanager.SecretManagerServiceClientFactory;
 import com.google.cloud.spring.secretmanager.SecretManagerTemplate;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -67,6 +66,13 @@ void testSecretManagerServiceClientExists() {
             .isNotNull());
   }
 
+  @Test
+  void testSecretManagerServiceClientFactoryExists() {
+    contextRunner.run(
+        ctx -> assertThat(ctx.getBean(SecretManagerServiceClientFactory.class))
+            .isNotNull());
+  }
+
   @Test
   void testSecretManagerTemplateExists() {
     contextRunner.run(

spring-cloud-gcp-autoconfigure/src/test/java/com/google/cloud/spring/autoconfigure/secretmanager/SecretManagerConfigDataLoaderUnitTests.java

@@ -5,9 +5,11 @@
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 
+import com.google.api.gax.core.CredentialsProvider;
 import com.google.cloud.spring.core.GcpProjectIdProvider;
 import com.google.cloud.spring.secretmanager.SecretManagerTemplate;
-import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
 import org.springframework.boot.ConfigurableBootstrapContext;
 import org.springframework.boot.context.config.ConfigDataLoaderContext;
 import org.springframework.boot.context.config.ConfigDataLocation;
@@ -21,15 +23,23 @@ class SecretManagerConfigDataLoaderUnitTests {
   private final ConfigDataLoaderContext loaderContext = mock(ConfigDataLoaderContext.class);
   private final GcpProjectIdProvider idProvider = mock(GcpProjectIdProvider.class);
   private final SecretManagerTemplate template = mock(SecretManagerTemplate.class);
+  private final GcpSecretManagerProperties properties = mock(GcpSecretManagerProperties.class);
+  private final CredentialsProvider credentialsProvider = mock(CredentialsProvider.class);
   private final ConfigurableBootstrapContext bootstrapContext = mock(
       ConfigurableBootstrapContext.class);
   private final SecretManagerConfigDataLoader loader = new SecretManagerConfigDataLoader();
 
-  @Test
-  void loadIncorrectResourceThrowsException() {
+  @ParameterizedTest
+  @CsvSource({
+      "regional-fake, us-central1",
+      "fake, "
+  })
+  void loadIncorrectResourceThrowsException(String resourceName, String location) {
     when(loaderContext.getBootstrapContext()).thenReturn(bootstrapContext);
     when(bootstrapContext.get(GcpProjectIdProvider.class)).thenReturn(idProvider);
     when(bootstrapContext.get(SecretManagerTemplate.class)).thenReturn(template);
+    when(bootstrapContext.get(GcpSecretManagerProperties.class)).thenReturn(properties);
+    when(bootstrapContext.get(CredentialsProvider.class)).thenReturn(credentialsProvider);
     when(template.secretExists(anyString(), anyString())).thenReturn(false);
     SecretManagerConfigDataResource resource = new SecretManagerConfigDataResource(
         ConfigDataLocation.of("fake"));