Create and manage instance configurations Stay organized with collections Save and categorize content based on your preferences.
This page describes how to list, create, update, delete, and show the details ofa Spannerinstance configuration.Some custom instance configuration functionalities are not available in theGoogle Cloud console UI. In those cases, use the Google Cloud CLI (gcloud) commandsprovided.
List instance configurations
You can list all the available Spanner instance configurationswith thegcloud CLI and client libraries.To find a list of all Spanner instance configurations, seeRegional and multi-region configurations.
gcloud
Run thegcloud spanner instance-configs list command:
gcloudspannerinstance-configslistC++
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
voidListInstanceConfigs(google::cloud::spanner_admin::InstanceAdminClientclient,std::stringconst&project_id){intcount=0;autoproject=google::cloud::Project(project_id);for(auto&config:client.ListInstanceConfigs(project.FullName())){if(!config)throwstd::move(config).status();++count;std::cout <<"Instance config [" <<count <<"]:\n" <<config->DebugString();}if(count==0){std::cout <<"No instance configs found in project " <<project_id <<"\n";}}C#
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
usingGoogle.Api.Gax.ResourceNames;usingGoogle.Cloud.Spanner.Admin.Instance.V1;usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;publicclassListInstanceConfigsSample{publicIEnumerable<InstanceConfig>ListInstanceConfigs(stringprojectId){varinstanceAdminClient=InstanceAdminClient.Create();varprojectName=ProjectName.FromProject(projectId);varinstanceConfigs=instanceAdminClient.ListInstanceConfigs(projectName);// We print the first 5 elements for demonstration purposes.// You can print all configs in the sequence by removing the call to Take(5).// The sequence will lazily fetch elements in pages as needed.foreach(varinstanceConfigininstanceConfigs.Take(5)){Console.WriteLine($"Available leader options for instance config {instanceConfig.InstanceConfigName.InstanceConfigId}:");foreach(varleaderininstanceConfig.LeaderOptions){Console.WriteLine(leader);}Console.WriteLine($"Available optional replica for instance config {instanceConfig.InstanceConfigName.InstanceConfigId}:");foreach(varoptionalReplicaininstanceConfig.OptionalReplicas){Console.WriteLine($"Replica type - {optionalReplica.Type}, default leader location - {optionalReplica.DefaultLeaderLocation}, location - {optionalReplica.Location}");}}returninstanceConfigs;}}Go
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
import("context""fmt""io"instance"cloud.google.com/go/spanner/admin/instance/apiv1""cloud.google.com/go/spanner/admin/instance/apiv1/instancepb""google.golang.org/api/iterator")// istInstanceConfigs gets available leader options for all instancesfunclistInstanceConfigs(wio.Writer,projectNamestring)error{// projectName = `projects/<project>ctx:=context.Background()instanceAdmin,err:=instance.NewInstanceAdminClient(ctx)iferr!=nil{returnerr}deferinstanceAdmin.Close()request:=&instancepb.ListInstanceConfigsRequest{Parent:projectName,}for{iter:=instanceAdmin.ListInstanceConfigs(ctx,request)for{ic,err:=iter.Next()iferr==iterator.Done{break}iferr!=nil{returnerr}fmt.Fprintf(w,"Available leader options for instance config %s: %v\n",ic.Name,ic.LeaderOptions)}pageToken:=iter.PageInfo().TokenifpageToken==""{break}else{request.PageToken=pageToken}}returnnil}Java
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
importcom.google.cloud.spanner.Spanner;importcom.google.cloud.spanner.SpannerOptions;importcom.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;importcom.google.spanner.admin.instance.v1.InstanceConfig;importcom.google.spanner.admin.instance.v1.ProjectName;publicclassListInstanceConfigsSample{staticvoidlistInstanceConfigs(){// TODO(developer): Replace these variables before running the sample.StringprojectId="my-project";listInstanceConfigs(projectId);}staticvoidlistInstanceConfigs(StringprojectId){try(Spannerspanner=SpannerOptions.newBuilder().setProjectId(projectId).build().getService();InstanceAdminClientinstanceAdminClient=spanner.createInstanceAdminClient()){finalProjectNameprojectName=ProjectName.of(projectId);for(InstanceConfiginstanceConfig:instanceAdminClient.listInstanceConfigs(projectName).iterateAll()){System.out.printf("Available leader options for instance config %s: %s%n",instanceConfig.getName(),instanceConfig.getLeaderOptionsList());}}}}Note: The old client library interface code samples for Java are archived inGitHub.
Node.js
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
/** * TODO(developer): Uncomment the following line before running the sample. */// const projectId = 'my-project-id';// Imports the Google Cloud client libraryconst{Spanner}=require('@google-cloud/spanner');// Creates a clientconstspanner=newSpanner({projectId:projectId,});constinstanceAdminClient=spanner.getInstanceAdminClient();asyncfunctionlistInstanceConfigs(){// Lists all available instance configurations in the project.// See https://cloud.google.com/spanner/docs/instance-configurations#configuration for a list of all available// configurations.const[instanceConfigs]=awaitinstanceAdminClient.listInstanceConfigs({parent:instanceAdminClient.projectPath(projectId),});console.log(`Available instance configs for project${projectId}:`);instanceConfigs.forEach(instanceConfig=>{console.log(`Available leader options for instance config${instanceConfig.name} ('${instanceConfig.displayName}'):${instanceConfig.leaderOptions.join()}`,);});}listInstanceConfigs();Note: The old client library interface code samples for Node.js are archived inGitHub.
PHP
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;use Google\Cloud\Spanner\Admin\Instance\V1\ListInstanceConfigsRequest;/** * Lists the available instance configurations. * Example: * ``` * list_instance_configs(); * ``` * * @param string $projectId The Google Cloud project ID. */function list_instance_configs(string $projectId): void{ $instanceAdminClient = new InstanceAdminClient(); $projectName = InstanceAdminClient::projectName($projectId); $request = new ListInstanceConfigsRequest(); $request->setParent($projectName); $resp = $instanceAdminClient->listInstanceConfigs($request); foreach ($resp as $element) { printf( 'Available leader options for instance config %s: %s' . PHP_EOL, $element->getDisplayName(), implode(',', iterator_to_array($element->getLeaderOptions())) ); }}Note: The old client library interface code samples for PHP are archived inGitHub.
Python
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
deflist_instance_config():"""Lists the available instance configurations."""fromgoogle.cloud.spanner_admin_instance_v1.typesimportspanner_instance_adminspanner_client=spanner.Client()request=spanner_instance_admin.ListInstanceConfigsRequest(parent=spanner_client.project_name)forconfiginspanner_client.instance_admin_api.list_instance_configs(request=request):print("Available leader options for instance config{}:{}".format(config.name,config.leader_options))Note: The old client library interface code samples for Python are archived inGitHub.
Ruby
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
# project_id = "Your Google Cloud project ID"require"google/cloud/spanner"require"google/cloud/spanner/admin/instance"instance_admin_client=Google::Cloud::Spanner::Admin::Instance.instance_adminproject_path=instance_admin_client.project_pathproject:project_idconfigs=instance_admin_client.list_instance_configsparent:project_pathconfigs.eachdo|c|puts"Available leader options for instance config#{c.name} :#{c.leader_options}"endShow instance configuration details
You can show the details of any instance configuration with thegcloud CLI and client libraries. When youcreate a newcustom instance configuration,you can add any location listed underoptionalReplicas as an optional replica.If you don't see your desired read-only replica location, you canrequest a new optional read-only replica region.
For more information, seeCreate a custom instance configuration.
gcloud
Run thegcloud spanner instance-configs describe command:
gcloudspannerinstance-configsdescribeINSTANCE-CONFIGProvide the following value:
INSTANCE-CONFIG- The instance configuration, which defines the geographic location of the instance and affects how data is replicated. For example,
eur6orregional-us-central1.
To show the details of theeur6 base configuration, run:
gcloudspannerinstance-configsdescribeeur6Here's an example output for theeur6 base configuration:
configType:GOOGLE_MANAGEDdisplayName:Europe(Netherlands,Frankfurt)freeInstanceAvailability:UNSUPPORTEDleaderOptions:-europe-west3-europe-west4name:projects/cloud-spanner-demo/instanceConfigs/eur6optionalReplicas:-displayName:SouthCarolinalabels:cloud.googleapis.com/country:UScloud.googleapis.com/location:us-east1cloud.googleapis.com/region:us-east1location:us-east1type:READ_ONLY-displayName:SouthCarolinalabels:cloud.googleapis.com/country:UScloud.googleapis.com/location:us-east1cloud.googleapis.com/region:us-east1location:us-east1type:READ_ONLYreplicas:-defaultLeaderLocation:truelocation:europe-west4type:READ_WRITE-location:europe-west4type:READ_WRITE-location:europe-west3type:READ_WRITE-location:europe-west3type:READ_WRITE-location:europe-west6type:WITNESSAdditional usage notes:
baseConfig(for custom configurations only) points to the baseinstance configuration. Refer toavailable regional configurationsandavailable multi-region configurationsfor lists of base instance configurations that can be used to create acustom instance configuration.configTypeindicates whether this instance configuration is abase instance configuration or a custom instance configuration.etag(for custom configurations only) is a base64-encoded stringrepresentation of the configuration. It is used for optimistic concurrencycontrol.
C++
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
voidGetInstanceConfig(google::cloud::spanner_admin::InstanceAdminClientclient,std::stringconst&project_id,std::stringconst&config_id){autoproject=google::cloud::Project(project_id);autoconfig=client.GetInstanceConfig(project.FullName()+"/instanceConfigs/"+config_id);if(!config)throwstd::move(config).status();std::cout <<"The instanceConfig " <<config->name() <<" exists and its metadata is:\n" <<config->DebugString();}C#
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
usingGoogle.Cloud.Spanner.Admin.Instance.V1;usingSystem;usingSystem.Threading.Tasks;publicclassGetInstanceConfigAsyncSample{publicasyncTask<InstanceConfig>GetInstanceConfigAsync(stringprojectId,stringinstanceConfigId){varinstanceAdminClient=awaitInstanceAdminClient.CreateAsync();varinstanceConfigName=InstanceConfigName.FromProjectInstanceConfig(projectId,instanceConfigId);varinstanceConfig=awaitinstanceAdminClient.GetInstanceConfigAsync(instanceConfigName);Console.WriteLine($"Available leader options for instance config {instanceConfigName.InstanceConfigId}:");foreach(varleaderininstanceConfig.LeaderOptions){Console.WriteLine(leader);}returninstanceConfig;}}Go
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
import("context""fmt""io"instance"cloud.google.com/go/spanner/admin/instance/apiv1""cloud.google.com/go/spanner/admin/instance/apiv1/instancepb")// getInstanceConfig gets available leader optionsfuncgetInstanceConfig(wio.Writer,instanceConfigNamestring)error{// defaultLeader = `nam3`ctx:=context.Background()instanceAdmin,err:=instance.NewInstanceAdminClient(ctx)iferr!=nil{returnerr}deferinstanceAdmin.Close()ic,err:=instanceAdmin.GetInstanceConfig(ctx,&instancepb.GetInstanceConfigRequest{Name:instanceConfigName,})iferr!=nil{returnfmt.Errorf("could not get instance config %s: %w",instanceConfigName,err)}fmt.Fprintf(w,"Available leader options for instance config %s: %v",instanceConfigName,ic.LeaderOptions)returnnil}Java
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
importcom.google.cloud.spanner.Spanner;importcom.google.cloud.spanner.SpannerOptions;importcom.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;importcom.google.spanner.admin.instance.v1.InstanceConfig;importcom.google.spanner.admin.instance.v1.InstanceConfigName;publicclassGetInstanceConfigSample{staticvoidgetInstanceConfig(){// TODO(developer): Replace these variables before running the sample.finalStringprojectId="my-project";finalStringinstanceConfigId="nam6";getInstanceConfig(projectId,instanceConfigId);}staticvoidgetInstanceConfig(StringprojectId,StringinstanceConfigId){try(Spannerspanner=SpannerOptions.newBuilder().setProjectId(projectId).build().getService();InstanceAdminClientinstanceAdminClient=spanner.createInstanceAdminClient()){finalInstanceConfigNameinstanceConfigName=InstanceConfigName.of(projectId,instanceConfigId);finalInstanceConfiginstanceConfig=instanceAdminClient.getInstanceConfig(instanceConfigName.toString());System.out.printf("Available leader options for instance config %s: %s%n",instanceConfig.getName(),instanceConfig.getLeaderOptionsList());}}}Note: The old client library interface code samples for Java are archived inGitHub.
Node.js
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
/** * TODO(developer): Uncomment the following line before running the sample. */// const projectId = 'my-project-id';// Imports the Google Cloud client libraryconst{Spanner}=require('@google-cloud/spanner');// Creates a clientconstspanner=newSpanner({projectId:projectId,});constinstanceAdminClient=spanner.getInstanceAdminClient();asyncfunctiongetInstanceConfig(){// Get the instance config for the multi-region North America 6 (NAM6).// See https://cloud.google.com/spanner/docs/instance-configurations#configuration for a list of all available// configurations.const[instanceConfig]=awaitinstanceAdminClient.getInstanceConfig({name:instanceAdminClient.instanceConfigPath(projectId,'nam6'),});console.log(`Available leader options for instance config${instanceConfig.name} ('${instanceConfig.displayName}'):${instanceConfig.leaderOptions.join()}`,);}getInstanceConfig();Note: The old client library interface code samples for Node.js are archived inGitHub.
PHP
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;use Google\Cloud\Spanner\Admin\Instance\V1\GetInstanceConfigRequest;/** * Gets the leader options for the instance configuration. * * @param string $projectId The Google Cloud Project ID. * @param string $instanceConfig The name of the instance configuration. */function get_instance_config(string $projectId, string $instanceConfig): void{ $instanceAdminClient = new InstanceAdminClient(); $instanceConfigName = InstanceAdminClient::instanceConfigName($projectId, $instanceConfig); $request = (new GetInstanceConfigRequest()) ->setName($instanceConfigName); $configInfo = $instanceAdminClient->getInstanceConfig($request); printf('Available leader options for instance config %s: %s' . PHP_EOL, $instanceConfig, implode(',', array_keys(iterator_to_array($configInfo->getLeaderOptions()))) );}Note: The old client library interface code samples for PHP are archived inGitHub.
Python
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
defget_instance_config(instance_config):"""Gets the leader options for the instance configuration."""spanner_client=spanner.Client()config_name="{}/instanceConfigs/{}".format(spanner_client.project_name,instance_config)config=spanner_client.instance_admin_api.get_instance_config(name=config_name)print("Available leader options for instance config{}:{}".format(instance_config,config.leader_options))Note: The old client library interface code samples for Python are archived inGitHub.
Ruby
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
# project_id = "Your Google Cloud project ID"# instance_config_id = "Spanner instance config ID"require"google/cloud/spanner"require"google/cloud/spanner/admin/instance"instance_admin_client=Google::Cloud::Spanner::Admin::Instance.instance_admininstance_config_path=instance_admin_client.instance_config_path\project:project_id,instance_config:instance_config_idconfig=instance_admin_client.get_instance_configname:instance_config_pathputs"Available leader options for instance config#{config.name} :#{config.leader_options}"Create a custom instance configuration
The instance configurations with predefined regions and replication topologiesare calledbase instance configurations. You can't change the replicationtopology of base instance configurations.
You can create acustom instance configuration, which lets you add additionaloptionalread-only replicas to thepredefined base instance configuration. This scales reads and supports lowlatency stale reads. The added read-only replica must be in a region that isn'tpart of the existing instance configuration. For a list of the optionalread-only regions that you can use to create a custom instance configuration,see the Optional Region column underRegional available configurationsandMulti-region available configurations.
You can't create a customdual-region instance configuration.For more information about Spannerreplication and replica types, seeReplication.
To create a custom instance configuration, you must have thespanner.instanceConfigs.create permission. By default, roles that have thespanner.instances.create permission will also have thespanner.instanceConfigs.create permission.
Console
You can't create a custom instance configuration using theGoogle Cloud console. To create an instance with read-only replicas, usethegcloud CLIor client libraries.
gcloud
Use thegcloud spanner instance-configs create command:
gcloudspannerinstance-configscreateCUSTOM-INSTANCE-CONFIG-ID\--display-name=DISPLAY-NAME\--base-config=BASE-CONFIG\--labels=KEY=VALUE,[...]\--replicas=location=LOCATION,type=TYPE[:...]You can use the--clone-config flag as a convenient way to clone anotherbase or custom instance configuration while also declaring the location andtype of a specific custom replica.
gcloudspannerinstance-configscreateCUSTOM-INSTANCE-CONFIG-ID\--display-name=DISPLAY-NAME\--clone-config=INSTANCE-CONFIG\--labels=KEY=VALUE,[...]\--add-replicas=location=LOCATION,type=TYPE[:...]\--skip-replicas=location=LOCATION,type=TYPE[:...]Provide the following values:
CUSTOM-INSTANCE-CONFIG-ID- Apermanent identifier that is unique within your Google Cloud project. Youcan't change the instance configuration ID later. The
custom-prefix is required to avoid name conflicts with base instanceconfigurations. DISPLAY-NAME- Thename to display for the custom instance configuration in theGoogle Cloud console. If you choose to use the flags `--base-config` and `--replicas`, provide thefollowing values:
BASE-CONFIG- The region name of the base instance configuration on which your custom instance configuration is based. For example,
eur6orregional-us-central1. LOCATION- The region name of the serving resources (replicas), for example,
us-east1. To find out what location names are accepted, rungcloud spanner instance-configs describeINSTANCE-CONFIGand refer to thereplicasandoptionalReplicaslists. TYPE- The type of replica. To find out what corresponding locations and replica types are accepted, run
gcloud spanner instance-configs describeINSTANCE-CONFIGand refer to thereplicasandoptionalReplicaslists. The types are one of the following:- READ_ONLY
- READ_WRITE
- WITNESS
- Items in the list are separated by ":".
- Unless the
--[clone-config]flag is used, all replicaLOCATIONandTYPEmust be specified when creating a custom instance configuration, including the ones predefined in the base configuration. For more information, see thegcloud instance-configs describe help-text.
If you choose to use the flags--clone-config and--add-replicas (onlyuse--skip-replicas if there are replicas you want to skip from beingcloned), provide the following values:
--clone-config=INSTANCE-CONFIGUse this flag as a convenient way to clone another base or custominstance configuration while also declaring the location and type of aspecific custom replica. Then use
--add-replicas=location=LOCATION,type=TYPEto specify where you want to add your optional replica.For example, to create a custom instance configuration with tworead-only replicas in
us-east1while copying all the other replicalocations from theeur6base instance configuration, run:gcloudspannerinstance-configscreatecustom-eur6--clone-config=eur6\--add-replicas=location=us-east1,type=READ_ONLY:location=us-east1,type=READ_ONLY--skip-replicas=location=LOCATION,type=TYPEUse this flag to skip any replica from being cloned.
For example, to create a custom instance configuration with oneread-only replica in
us-east4while copying all the other replicalocations from thenam3base instance configuration except theread-only replica inus-central1, run:gcloudspannerinstance-configscreatecustom-nam3--clone-config=nam3\--add-replicas=location=us-east4,type=READ_ONLY\--skip-replicas=location=us-central1,type=READ_ONLY
The following flags and values are optional:
--labels=KEY=VALUE,[...]KEYandVALUE: A list ofkey and value pairs to add to your custom instance configuration.Keys must start with a lowercase character and contain only hyphens (-),underscores (_), lowercase characters, and numbers. Values must containonly hyphens (-), underscores (_), lowercase characters, and numbers.
--validate-onlyUse this flag to validate that the request will succeed before executingit.
For example, to create a custom instance configuration with theeur6 baseconfiguration with one additional read-only replica inus-east1, run:
gcloudspannerinstance-configscreatecustom-eur6\--display-name="Custom eur6"--clone-config=eur6\--add-replicas=location=us-east1,type=READ_ONLY\You can also create a custom instance configuration without the--clone-config flag:
gcloudspannerinstance-configscreatecustom-eur6\--display-name="Custom eur6"--base-config=eur6\--replicas=location=europe-west4,type=READ_WRITE:location=europe-west3,type=READ_WRITE:location=europe-west4,type=READ_WRITE:location=europe-west3,type=READ_WRITE:location=europe-west6,type=WITNESS:location=us-east1,type=READ_ONLYYou should see the following output:
Creating instance-config...done.
C++
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
voidCreateInstanceConfig(google::cloud::spanner_admin::InstanceAdminClientclient,std::stringconst&project_id,std::stringconst&user_config_id,std::stringconst&base_config_id){autoproject=google::cloud::Project(project_id);autobase_config=client.GetInstanceConfig(project.FullName()+"/instanceConfigs/"+base_config_id);if(!base_config)throwstd::move(base_config).status();if(base_config->optional_replicas().empty()){throwstd::runtime_error("No optional replicas in base config");}google::spanner::admin::instance::v1::CreateInstanceConfigRequestrequest;request.set_parent(project.FullName());request.set_instance_config_id(user_config_id);auto*request_config=request.mutable_instance_config();request_config->set_name(project.FullName()+"/instanceConfigs/"+user_config_id);request_config->set_display_name("My instance config");// The user-managed instance config must contain all the replicas// of the base config plus at least one of the optional replicas.*request_config->mutable_replicas()=base_config->replicas();for(autoconst&replica:base_config->optional_replicas()){*request_config->add_replicas()=replica;}request_config->set_base_config(base_config->name());*request_config->mutable_leader_options()=base_config->leader_options();request.set_validate_only(false);autouser_config=client.CreateInstanceConfig(request).get();if(!user_config)throwstd::move(user_config).status();std::cout <<"Created instance config [" <<user_config_id <<"]:\n" <<user_config->DebugString();}C#
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
usingSystem;usingSystem.Threading.Tasks;usingGoogle.Api.Gax.ResourceNames;usingGoogle.Cloud.Spanner.Admin.Instance.V1;publicclassCreateInstanceConfigAsyncSample{publicasyncTask<InstanceConfig>CreateInstanceConfigAsync(stringprojectId,stringbaseInstanceConfigId,stringcustomInstanceConfigId){InstanceAdminClientinstanceAdminClient=awaitInstanceAdminClient.CreateAsync();varinstanceConfigName=newInstanceConfigName(projectId,baseInstanceConfigId);varinstanceConfig=awaitinstanceAdminClient.GetInstanceConfigAsync(instanceConfigName);varcustomInstanceConfigName=newInstanceConfigName(projectId,customInstanceConfigId);//Create a custom config.InstanceConfiguserInstanceConfig=newInstanceConfig{DisplayName="C# test custom instance config",ConfigType=InstanceConfig.Types.Type.UserManaged,BaseConfigAsInstanceConfigName=instanceConfigName,InstanceConfigName=customInstanceConfigName,//The replicas for the custom instance configuration must include all the replicas of the base//configuration, in addition to at least one from the list of optional replicas of the base//configuration.Replicas={instanceConfig.Replicas},OptionalReplicas={newReplicaInfo{Type=ReplicaInfo.Types.ReplicaType.ReadOnly,Location="us-east1",DefaultLeaderLocation=false},//The replicas for the custom instance configuration must include all the replicas of the base//configuration, in addition to at least one from the list of optional replicas of the base//configuration.instanceConfig.OptionalReplicas}};varoperationResult=awaitinstanceAdminClient.CreateInstanceConfigAsync(newCreateInstanceConfigRequest{ParentAsProjectName=ProjectName.FromProject(projectId),InstanceConfig=userInstanceConfig,InstanceConfigId=customInstanceConfigId});varpollResult=awaitoperationResult.PollUntilCompletedAsync();if(pollResult.IsFaulted){throwpollResult.Exception;}Console.WriteLine($"Instance config created successfully");Console.WriteLine($"Available custom replication options for instance config {pollResult.Result.Name}\r\n{pollResult.Result.OptionalReplicas}");returnpollResult.Result;}}Go
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
import("context""fmt""io""time"instance"cloud.google.com/go/spanner/admin/instance/apiv1""cloud.google.com/go/spanner/admin/instance/apiv1/instancepb")// createInstanceConfig creates a custom spanner instance configfunccreateInstanceConfig(wio.Writer,projectID,userConfigID,baseConfigIDstring)error{// projectID := "my-project-id"// userConfigID := "custom-config", custom config names must start with the prefix “custom-”.// baseConfigID := "my-base-config"// Add timeout to context.ctx,cancel:=context.WithTimeout(context.Background(),10*time.Minute)defercancel()adminClient,err:=instance.NewInstanceAdminClient(ctx)iferr!=nil{returnerr}deferadmiadminClient.ClosebaseConfig,err:=adminClient.GetInstanceConfig(ctx,&instancepb.GetInstanceConfigRequest{Name:fmt.Sprintf("projects/%s/instanceConfigs/%s",projectID,baseConfigID),})iferr!=nil{returnfmt.Errorf("createInstanceConfig.GetInstanceConfig: %w",err)}ifbaseConfig.OptionalReplicas==nil||len(baseConfig.OptionalReplicas)==0{returnfmt.Errorf("CreateInstanceConfig expects base config with at least from the list of optional replicas")}op,err:=adminClient.CreateInstanceConfig(ctx,&instancepb.CreateInstanceConfigRequest{Parent:fmt.Sprintf("projects/%s",projectID),// Custom config names must start with the prefix “custom-”.InstanceConfigId:userConfigID,InstanceConfig:&instancepb.InstanceConfig{Name:fmt.Sprintf("projects/%s/instanceConfigs/%s",projectID,userConfigID),DisplayName:"custom-golang-samples",ConfigType:instanceinstancepb.InstanceConfig_USER_MANAGEDThereplicasforthecustominstanceconfigurationmustincludeallthereplicasofthebase// configuration, in addition to at least one from the list of optional replicas of the base// configuration.Replicas:append(baseConfig.Replicas,baseConfig.OptionalReplicas...),BaseConfig:baseConfig.Name,Labels:map[string]string{"go_cloud_spanner_samples":"true"},},})iferr!=nil{returnerr}fmt.Fprintf(w,"Waiting for create operation on projects/%s/instanceConfigs/%s to complete...\n",projectID,userConfigID)// Wait for the instance configuration creation to finish.i,err:=op.Wait(ctx)iferr!=nil{returnfmt.Errorf("Waiting for instance config creation to finish failed: %w",err)}// The instance configuration may not be ready to serve yet.ifi.State!=instanceinstancepb.InstanceConfig_READY.Fprintf(w,"InstanceConfig state is not READY yet. Got state %v\n",i.State)}fmt.Fprintf(w,"Created instance configuration [%s]\n",userConfigID)returnnil}Java
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
importcom.google.cloud.spanner.Spanner;importcom.google.cloud.spanner.SpannerOptions;importcom.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;importcom.google.spanner.admin.instance.v1.CreateInstanceConfigRequest;importcom.google.spanner.admin.instance.v1.InstanceConfig;importcom.google.spanner.admin.instance.v1.InstanceConfigName;importcom.google.spanner.admin.instance.v1.ProjectName;importcom.google.spanner.admin.instance.v1.ReplicaInfo;importjava.util.List;importjava.util.concurrent.ExecutionException;importjava.util.concurrent.TimeUnit;importjava.util.concurrent.TimeoutException;importjava.util.stream.Collectors;importjava.util.stream.Stream;classCreateInstanceConfigSample{staticvoidcreateInstanceConfig(){// TODO(developer): Replace these variables before running the sample.StringprojectId="my-project";StringbaseInstanceConfigId="nam11";StringinstanceConfigId="custom-instance-config4";createInstanceConfig(projectId,baseInstanceConfigId,instanceConfigId);}staticvoidcreateInstanceConfig(StringprojectId,StringbaseInstanceConfigId,StringinstanceConfigId){try(Spannerspanner=SpannerOptions.newBuilder().setProjectId(projectId).build().getService();InstanceAdminClientinstanceAdminClient=spanner.createInstanceAdminClient()){finalInstanceConfigNamebaseInstanceConfigName=InstanceConfigName.of(projectId,baseInstanceConfigId);finalInstanceConfigbaseConfig=instanceAdminClient.getInstanceConfig(baseInstanceConfigName.toString());finalInstanceConfigNameinstanceConfigName=InstanceConfigName.of(projectId,instanceConfigId);/** * The replicas for the custom instance configuration must include all the replicas of the * base configuration, in addition to at least one from the list of optional replicas of the * base configuration. */finalList<ReplicaInfo>replicas=Stream.concat(baseConfig.getReplicasList().stream(),baseConfig.getOptionalReplicasList().stream().limit(1)).collect(Collectors.toList());finalInstanceConfiginstanceConfig=InstanceConfig.newBuilder().setName(instanceConfigName.toString()).setBaseConfig(baseInstanceConfigName.toString()).setDisplayName("Instance Configuration").addAllReplicas(replicas).build();finalCreateInstanceConfigRequestcreateInstanceConfigRequest=CreateInstanceConfigRequest.newBuilder().setParent(ProjectName.of(projectId).toString()).setInstanceConfigId(instanceConfigId).setInstanceConfig(instanceConfig).build();try{System.out.printf("Waiting for create operation for %s to complete...\n",instanceConfigName);InstanceConfiginstanceConfigResult=instanceAdminClient.createInstanceConfigAsync(createInstanceConfigRequest).get(5,TimeUnit.MINUTES);System.out.printf("Created instance configuration %s\n",instanceConfigResult.getName());}catch(ExecutionException|TimeoutExceptione){System.out.printf("Error: Creating instance configuration %s failed with error message %s\n",instanceConfig.getName(),e.getMessage());}catch(InterruptedExceptione){System.out.println("Error: Waiting for createInstanceConfig operation to finish was interrupted");}}}}Note: The old client library interface code samples for Java are archived inGitHub.
Node.js
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
/** * TODO(developer): Uncomment the following lines before running the sample. */// const instanceConfigId = 'custom-my-instance-config-id'// const baseInstanceConfigId = 'my-base-instance-config-id';// const projectId = 'my-project-id';// Imports the Google Cloud client libraryconst{Spanner}=require('@google-cloud/spanner');// Creates a clientconstspanner=newSpanner({projectId:projectId,});constinstanceAdminClient=spanner.getInstanceAdminClient();// Creates a new instance configasyncfunctioncreateInstanceConfig(){const[baseInstanceConfig]=awaitinstanceAdminClient.getInstanceConfig({name:instanceAdminClient.instanceConfigPath(projectId,baseInstanceConfigId,),});try{console.log(`Creating instance config${instanceAdminClient.instanceConfigPath(projectId,instanceConfigId,)}.`,);const[operation]=awaitinstanceAdminClient.createInstanceConfig({instanceConfigId:instanceConfigId,parent:instanceAdminClient.projectPath(projectId),instanceConfig:{name:instanceAdminClient.instanceConfigPath(projectId,instanceConfigId,),baseConfig:instanceAdminClient.instanceConfigPath(projectId,baseInstanceConfigId,),displayName:instanceConfigId,replicas:baseInstanceConfig.replicas.concat(baseInstanceConfig.optionalReplicas[0],),},});console.log(`Waiting for create operation for${instanceConfigId} to complete...`,);awaitoperation.promise();console.log(`Created instance config${instanceConfigId}.`);}catch(err){console.error('ERROR: Creating instance config ',instanceConfigId,' failed with error message ',err,);}}createInstanceConfig();Note: The old client library interface code samples for Node.js are archived inGitHub.
PHP
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
use Google\Cloud\Spanner\Admin\Instance\V1\CreateInstanceConfigRequest;use Google\Cloud\Spanner\Admin\Instance\V1\GetInstanceConfigRequest;use Google\Cloud\Spanner\Admin\Instance\V1\InstanceConfig;use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;use Google\Cloud\Spanner\Admin\Instance\V1\ReplicaInfo;/** * Creates a customer managed instance configuration. * Example: * ``` * create_instance_config($instanceConfigId); * ``` * * @param string $projectId The Google Cloud Project ID. * @param string $instanceConfigId The customer managed instance configuration id. The id must start with 'custom-'. * @param string $baseConfigId Base configuration ID to be used for creation, e.g. nam11. */function create_instance_config(string $projectId, string $instanceConfigId, string $baseConfigId): void{ $instanceAdminClient = new InstanceAdminClient(); $projectName = InstanceAdminClient::projectName($projectId); $instanceConfigName = $instanceAdminClient->instanceConfigName( $projectId, $instanceConfigId ); // Get a Google Managed instance configuration to use as the base for our custom instance configuration. $baseInstanceConfig = $instanceAdminClient->instanceConfigName( $projectId, $baseConfigId ); $request = new GetInstanceConfigRequest(['name' => $baseInstanceConfig]); $baseInstanceConfigInfo = $instanceAdminClient->getInstanceConfig($request); $instanceConfig = (new InstanceConfig()) ->setBaseConfig($baseInstanceConfig) ->setName($instanceConfigName) ->setDisplayName('My custom instance configuration') ->setLabels(['php-cloud-spanner-samples' => true]) ->setReplicas(array_merge( iterator_to_array($baseInstanceConfigInfo->getReplicas()), [new ReplicaInfo([ 'location' => 'us-east1', 'type' => ReplicaInfo\ReplicaType::READ_ONLY, 'default_leader_location' => false ])] )); $request = new CreateInstanceConfigRequest([ 'parent' => $projectName, 'instance_config' => $instanceConfig, 'instance_config_id' => $instanceConfigId ]); $operation = $instanceAdminClient->createInstanceConfig($request); print('Waiting for operation to complete...' . PHP_EOL); $operation->pollUntilComplete(); printf('Created instance configuration %s' . PHP_EOL, $instanceConfigId);}Note: The old client library interface code samples for PHP are archived inGitHub.
Python
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
defcreate_instance_config(user_config_name,base_config_id):"""Creates the new user-managed instance configuration using base instance config."""# user_config_name = `custom-nam11`# base_config_id = `projects/<project>/instanceConfigs/nam11`spanner_client=spanner.Client()base_config=spanner_client.instance_admin_api.get_instance_config(name=base_config_id)# The replicas for the custom instance configuration must include all the replicas of the base# configuration, in addition to at least one from the list of optional replicas of the base# configuration.replicas=[]forreplicainbase_config.replicas:replicas.append(replica)replicas.append(base_config.optional_replicas[0])operation=spanner_client.instance_admin_api.create_instance_config(parent=spanner_client.project_name,instance_config_id=user_config_name,instance_config=spanner_instance_admin.InstanceConfig(name="{}/instanceConfigs/{}".format(spanner_client.project_name,user_config_name),display_name="custom-python-samples",config_type=spanner_instance_admin.InstanceConfig.Type.USER_MANAGED,replicas=replicas,base_config=base_config.name,labels={"python_cloud_spanner_samples":"true"},),)print("Waiting for operation to complete...")operation.result(OPERATION_TIMEOUT_SECONDS)print("Created instance configuration{}".format(user_config_name))Note: The old client library interface code samples for Python are archived inGitHub.
Ruby
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
require"google/cloud/spanner"require"google/cloud/spanner/admin/instance"defspanner_create_instance_configproject_id:,user_config_name:,base_config_id:# project_id = "Your Google Cloud project ID"# user_config_name = "Your custom instance configuration name, The name must start with 'custom-'"# base_config_id = "Base configuration ID to be used for creation, e.g projects/<project>/instanceConfigs/nam11"instance_admin_client=Google::Cloud::Spanner::Admin::Instance.instance_adminproject_path=instance_admin_client.project_pathproject:project_idbase_instance_config=instance_admin_client.get_instance_configname:base_config_id# The replicas for the custom instance configuration must include all the replicas of the base# configuration, in addition to at least one from the list of optional replicas of the base# configuration.custom_replicas=[]base_instance_config.replicas.eachdo|replica|custom_replicas <<replicaendcustom_replicas <<base_instance_config.optional_replicas[0]custom_instance_config_id=instance_admin_client.instance_config_path\project:project_id,instance_config:user_config_namecustom_instance_config={name:custom_instance_config_id,display_name:"custom-ruby-samples",config_type::USER_MANAGED,replicas:custom_replicas,base_config:base_config_id,labels:{ruby_cloud_spanner_samples:"true"}}request={parent:project_path,# Custom config names must start with the prefix “custom-”.instance_config_id:user_config_name,instance_config:custom_instance_config}job=instance_admin_client.create_instance_configrequestputs"Waiting for create instance config operation to complete"job.wait_until_done!ifjob.error?putsjob.errorelseputs"Created instance configuration#{user_config_name}"endendCreate an instance in a custom instance configuration
You can create an instance in a custom instance configuration.
Console
To create an instance in a custom instance configuration, use thegcloud CLIor client libraries.
gcloud
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
C++
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
C#
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
Go
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
Java
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
Node.js
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
PHP
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
Python
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
Ruby
After youcreate the custom instance configuration,follow the instructions provided inCreate an instance.
Update a custom instance configuration
You can change the display name and labels of a custom instance configuration.
You cannot change or update the replicas of your custom instance configuration.However, you can create a new custom instance configuration with additionalreplicas, then move your instance to the newcustom instance configuration with your chosen additional replicas. For example,if your instance is inregional-us-central1 and you want to add a read-onlyreplicaus-west1, then you need to create a new custom instanceconfiguration withregional-us-central1 as the base configuration and addus-west1 as a read-only replica. Thenmove your instanceto this new custom instance configuration.
gcloud
Use thegcloud spanner instance-configs update command:
gcloudspannerinstance-configsupdateCUSTOM-INSTANCE-CONFIG-ID\--display-name=NEW-DISPLAY-NAME\--update-labels=KEY=VALUE,[...],\--etag=ETAGProvide the following values:
CUSTOM-INSTANCE-CONFIG-ID- A permanent identifier of your custom instance configuration. It will start with
custom-. NEW-DISPLAY-NAME- The new name to display for the instance configuration in the Google Cloud console.
KEYandVALUE- A list of key and value pairs to update.
- Keys must start with a lowercase character and contain only hyphens (-), underscores (_), lowercase characters, and numbers. Values must contain only hyphens (-), underscores (_), lowercase characters, and numbers.
The following flags and values are optional:
--etag=ETAG: TheETAGargument can be used to select and skip simultaneous updates in aread-modify-write scenario.--validate-only: Use this flag to validate that the request will succeedbefore executing it.
For example:
gcloudspannerinstance-configsupdatecustom-eur6\--display-name="Customer managed europe replicas"C++
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
voidUpdateInstanceConfig(google::cloud::spanner_admin::InstanceAdminClientclient,std::stringconst&project_id,std::stringconst&config_id){autoproject=google::cloud::Project(project_id);autoconfig=client.GetInstanceConfig(project.FullName()+"/instanceConfigs/"+config_id);if(!config)throwstd::move(config).status();google::spanner::admin::instance::v1::UpdateInstanceConfigRequestrequest;auto*request_config=request.mutable_instance_config();request_config->set_name(config->name());request_config->mutable_labels()->insert({"key","value"});request.mutable_update_mask()->add_paths("labels");request_config->set_etag(config->etag());request.set_validate_only(false);autoupdated_config=client.UpdateInstanceConfig(request).get();if(!updated_config)throwstd::move(updated_config).status();std::cout <<"Updated instance config [" <<config_id <<"]:\n" <<updated_config->DebugString();}C#
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
usingSystem;usingSystem.Collections.Generic;usingSystem.Threading.Tasks;usingGoogle.Cloud.Spanner.Admin.Instance.V1;usingGoogle.LongRunning;usingGoogle.Protobuf.WellKnownTypes;publicclassUpdateInstanceConfigAsyncSample{publicasyncTask<Operation<InstanceConfig,UpdateInstanceConfigMetadata>>UpdateInstanceConfigAsync(stringprojectId,stringinstanceConfigId){InstanceAdminClientinstanceAdminClient=awaitInstanceAdminClient.CreateAsync();varinstanceConfigName=newInstanceConfigName(projectId,instanceConfigId);varinstanceConfig=newInstanceConfig();instanceConfig.InstanceConfigName=instanceConfigName;instanceConfig.DisplayName="New display name";instanceConfig.Labels.Add(newDictionary<string,string>{{"cloud_spanner_samples","true"},{"updated","true"},});varupdateInstanceConfigOperation=awaitinstanceAdminClient.UpdateInstanceConfigAsync(newUpdateInstanceConfigRequest{InstanceConfig=instanceConfig,UpdateMask=newFieldMask{Paths={"display_name","labels"}}});updateInstanceConfigOperation=awaitupdateInstanceConfigOperation.PollUntilCompletedAsync();if(updateInstanceConfigOperation.IsFaulted){throwupdateInstanceConfigOperation.Exception;}Console.WriteLine("Update Instance Config operation completed successfully.");returnupdateInstanceConfigOperation;}}Go
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
import("context""fmt""io""time"instance"cloud.google.com/go/spanner/admin/instance/apiv1""cloud.google.com/go/spanner/admin/instance/apiv1/instancepb""google.golang.org/genproto/protobuf/field_mask")// updateInstanceConfig updates the custom spanner instance configfuncupdateInstanceConfig(wio.Writer,projectID,userConfigIDstring)error{// projectID := "my-project-id"// userConfigID := "custom-config", custom config names must start with the prefix “custom-”.// Add timeout to context.ctx,cancel:=context.WithTimeout(context.Background(),10*time.Minute)defercancel()adminClient,err:=instance.NewInstanceAdminClient(ctx)iferr!=nil{returnerr}deferadmiadminClient.Closeconfig,err:=adminClient.GetInstanceConfig(ctx,&instancepb.GetInstanceConfigRequest{Name:fmt.Sprintf("projects/%s/instanceConfigs/%s",projectID,userConfigID),})iferr!=nil{returnfmt.Errorf("updateInstanceConfig.GetInstanceConfig: %w",err)}config.DisplayName="updated custom instance config"config.Labels["updated"]="true"op,err:=adminClient.UpdateInstanceConfig(ctx,&instancepb.UpdateInstanceConfigRequest{InstanceConfig:config,UpdateMask:&field_mask.FieldMask{Paths:[]string{"display_name","labels"},},ValidateOnly:false,})iferr!=nil{returnerr}fmt.Fprintf(w,"Waiting for update operation on %s to complete...\n",userConfigID)// Wait for the instance configuration creation to finish.i,err:=op.Wait(ctx)iferr!=nil{returnfmt.Errorf("Waiting for instance config creation to finish failed: %w",err)}// The instance configuration may not be ready to serve yet.ifi.State!=instinstancepb.InstanceConfig_READYfmt.Fprintf(w,"InstanceConfig state is not READY yet. Got state %v\n",i.State)}fmt.Fprintf(w,"Updated instance configuration [%s]\n",config.Name)returnnil}Java
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
importcom.google.cloud.spanner.Spanner;importcom.google.cloud.spanner.SpannerOptions;importcom.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;importcom.google.common.collect.ImmutableList;importcom.google.protobuf.FieldMask;importcom.google.spanner.admin.instance.v1.InstanceConfig;importcom.google.spanner.admin.instance.v1.InstanceConfigName;importcom.google.spanner.admin.instance.v1.UpdateInstanceConfigRequest;importjava.util.concurrent.ExecutionException;importjava.util.concurrent.TimeUnit;importjava.util.concurrent.TimeoutException;classUpdateInstanceConfigSample{staticvoidupdateInstanceConfig(){// TODO(developer): Replace these variables before running the sample.StringprojectId="my-project";StringinstanceConfigId="custom-instance-config";updateInstanceConfig(projectId,instanceConfigId);}staticvoidupdateInstanceConfig(StringprojectId,StringinstanceConfigId){try(Spannerspanner=SpannerOptions.newBuilder().setProjectId(projectId).build().getService();InstanceAdminClientinstanceAdminClient=spanner.createInstanceAdminClient()){finalInstanceConfigNameinstanceConfigName=InstanceConfigName.of(projectId,instanceConfigId);finalInstanceConfiginstanceConfig=InstanceConfig.newBuilder().setName(instanceConfigName.toString()).setDisplayName("updated custom instance config").putLabels("updated","true").build();/** * The field mask must always be specified; this prevents any future * fields in [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig] * from being erased accidentally by clients that do not know about them. */finalUpdateInstanceConfigRequestupdateInstanceConfigRequest=UpdateInstanceConfigRequest.newBuilder().setInstanceConfig(instanceConfig).setUpdateMask(FieldMask.newBuilder().addAllPaths(ImmutableList.of("display_name","labels")).build()).build();try{System.out.printf("Waiting for update operation on %s to complete...\n",instanceConfigName);InstanceConfiginstanceConfigResult=instanceAdminClient.updateInstanceConfigAsync(updateInstanceConfigRequest).get(5,TimeUnit.MINUTES);System.out.printf("Updated instance configuration %s with new display name %s\n",instanceConfigResult.getName(),instanceConfig.getDisplayName());}catch(ExecutionException|TimeoutExceptione){System.out.printf("Error: Updating instance config %s failed with error message %s\n",instanceConfig.getName(),e.getMessage());e.printStackTrace();}catch(InterruptedExceptione){System.out.println("Error: Waiting for updateInstanceConfig operation to finish was interrupted");}}}}Note: The old client library interface code samples for Java are archived inGitHub.
Node.js
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
/** * TODO(developer): Uncomment the following lines before running the sample. */// const instanceConfigId = 'custom-my-instance-config-id';// const projectId = 'my-project-id';// Imports the Google Cloud client libraryconst{Spanner,protos}=require('@google-cloud/spanner');// Creates a clientconstspanner=newSpanner({projectId:projectId,});constinstanceAdminClient=spanner.getInstanceAdminClient();asyncfunctionupdateInstanceConfig(){// Updates an instance configtry{console.log(`Updating instance config${instanceAdminClient.instanceConfigPath(projectId,instanceConfigId,)}.`,);const[operation]=awaitinstanceAdminClient.updateInstanceConfig({instanceConfig:{name:instanceAdminClient.instanceConfigPath(projectId,instanceConfigId,),displayName:'updated custom instance config',labels:{updated:'true',created:Math.round(Date.now()/1000).toString(),// current time},},// Field mask specifying fields that should get updated in InstanceConfig// Only display_name and labels can be updatedupdateMask:(protos.google.protobuf.FieldMask={paths:['display_name','labels'],}),});console.log(`Waiting for update operation for${instanceConfigId} to complete...`,);awaitoperation.promise();console.log(`Updated instance config${instanceConfigId}.`);}catch(err){console.error('ERROR: Updating instance config ',instanceConfigId,' failed with error message ',err,);}}updateInstanceConfig();Note: The old client library interface code samples for Node.js are archived inGitHub.
PHP
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;use Google\Cloud\Spanner\Admin\Instance\V1\InstanceConfig;use Google\Cloud\Spanner\Admin\Instance\V1\UpdateInstanceConfigRequest;use Google\Protobuf\FieldMask;/** * Updates a customer managed instance configuration. * Example: * ``` * update_instance_config($instanceConfigId); * ``` * * @param string $projectId The Google Cloud project ID. * @param string $instanceConfigId The customer managed instance configuration id. The id must start with 'custom-'. */function update_instance_config(string $projectId, string $instanceConfigId): void{ $instanceAdminClient = new InstanceAdminClient(); $instanceConfigPath = $instanceAdminClient->instanceConfigName($projectId, $instanceConfigId); $displayName = 'New display name'; $instanceConfig = new InstanceConfig(); $instanceConfig->setName($instanceConfigPath); $instanceConfig->setDisplayName($displayName); $instanceConfig->setLabels(['cloud_spanner_samples' => true, 'updated' => true]); $fieldMask = new FieldMask(); $fieldMask->setPaths(['display_name', 'labels']); $updateInstanceConfigRequest = (new UpdateInstanceConfigRequest()) ->setInstanceConfig($instanceConfig) ->setUpdateMask($fieldMask); $operation = $instanceAdminClient->updateInstanceConfig($updateInstanceConfigRequest); print('Waiting for operation to complete...' . PHP_EOL); $operation->pollUntilComplete(); printf('Updated instance configuration %s' . PHP_EOL, $instanceConfigId);}Note: The old client library interface code samples for PHP are archived inGitHub.
Python
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
defupdate_instance_config(user_config_name):"""Updates the user-managed instance configuration."""# user_config_name = `custom-nam11`spanner_client=spanner.Client()config=spanner_client.instance_admin_api.get_instance_config(name="{}/instanceConfigs/{}".format(spanner_client.project_name,user_config_name))config.display_name="updated custom instance config"config.labels["updated"]="true"operation=spanner_client.instance_admin_api.update_instance_config(instance_config=config,update_mask=field_mask_pb2.FieldMask(paths=["display_name","labels"]),)print("Waiting for operation to complete...")operation.result(OPERATION_TIMEOUT_SECONDS)print("Updated instance configuration{}".format(user_config_name))Note: The old client library interface code samples for Python are archived inGitHub.
Ruby
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
require"google/cloud/spanner"require"google/cloud/spanner/admin/instance"defspanner_update_instance_configuser_config_id:# user_config_id = "The customer managed instance configuration ID, e.g projects/<project>/instanceConfigs/custom-nam11"instance_admin_client=Google::Cloud::Spanner::Admin::Instance.instance_adminconfig=instance_admin_client.get_instance_configname:user_config_idconfig.display_name="updated custom instance config"config.labels["updated"]="true"request={instance_config:config,update_mask:{paths:["display_name","labels"]},validate_only:false}job=instance_admin_client.update_instance_configrequestputs"Waiting for update instance config operation to complete"job.wait_until_done!ifjob.error?putsjob.errorelseputs"Updated instance configuration#{config.name}"endendDelete a custom instance configuration
Note: Deleting an instance configuration permanently removes the instanceconfiguration. You can't delete a custom instance configuration which is used byan instance. To delete an instance, seeDelete an instance.To delete a custom instance configuration, first delete any instance in theinstance configuration.
gcloud
Use thegcloud spanner instance-configs delete command, replacingCUSTOM-INSTANCE-CONFIG-ID with the custom instanceconfiguration ID:
gcloudspannerinstance-configsdeleteCUSTOM-INSTANCE-CONFIG-IDC++
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
voidDeleteInstanceConfig(google::cloud::spanner_admin::InstanceAdminClientclient,std::stringconst&project_id,std::stringconst&config_id){autoproject=google::cloud::Project(project_id);autoconfig_name=project.FullName()+"/instanceConfigs/"+config_id;autostatus=client.DeleteInstanceConfig(config_name);if(!status.ok())throwstd::move(status);std::cout <<"Instance config " <<config_name <<" successfully deleted\n";}C#
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
usingSystem;usingSystem.Threading.Tasks;usingGoogle.Cloud.Spanner.Admin.Instance.V1;usingGrpc.Core;publicclassDeleteInstanceConfigAsyncSample{publicasyncTaskDeleteInstanceConfigAsync(stringprojectId,stringinstanceConfigId){InstanceAdminClientinstanceAdminClient=awaitInstanceAdminClient.CreateAsync();varinstanceConfigName=newInstanceConfigName(projectId,instanceConfigId);try{awaitinstanceAdminClient.DeleteInstanceConfigAsync(newDeleteInstanceConfigRequest{InstanceConfigName=instanceConfigName});}catch(RpcExceptionex)when(ex.Status.StatusCode==StatusCode.NotFound){Console.WriteLine("The specified instance config does not exist. It cannot be deleted.");return;}Console.WriteLine("Delete Instance Config operation is completed");}}Go
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
import("context""fmt""io"instance"cloud.google.com/go/spanner/admin/instance/apiv1""cloud.google.com/go/spanner/admin/instance/apiv1/instancepb")// deleteInstanceConfig deletes the custom spanner instance configfuncdeleteInstanceConfig(wio.Writer,projectID,userConfigIDstring)error{// projectID := "my-project-id"// userConfigID := "custom-config", custom config names must start with the prefix “custom-”.ctx:=context.Background()adminClient,err:=instance.NewInstanceAdminClient(ctx)iferr!=nil{returnerr}deferadmiadminClient.Closeerr=adminClient.DeleteInstanceConfig(ctx,&instancepb.DeleteInstanceConfigRequest{Name:fmt.Sprintf("projects/%s/instanceConfigs/%s",projectID,userConfigID),})iferr!=nil{returnerr}fmt.Fprintf(w,"Deleted instance configuration [%s]\n",userConfigID)returnnil}Java
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
importcom.google.cloud.spanner.Spanner;importcom.google.cloud.spanner.SpannerException;importcom.google.cloud.spanner.SpannerOptions;importcom.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;importcom.google.spanner.admin.instance.v1.DeleteInstanceConfigRequest;importcom.google.spanner.admin.instance.v1.InstanceConfigName;classDeleteInstanceConfigSample{staticvoiddeleteInstanceConfig(){// TODO(developer): Replace these variables before running the sample.StringprojectId="my-project";StringinstanceConfigId="custom-user-config";deleteInstanceConfig(projectId,instanceConfigId);}staticvoiddeleteInstanceConfig(StringprojectId,StringinstanceConfigId){try(Spannerspanner=SpannerOptions.newBuilder().setProjectId(projectId).build().getService();InstanceAdminClientinstanceAdminClient=spanner.createInstanceAdminClient()){finalInstanceConfigNameinstanceConfigName=InstanceConfigName.of(projectId,instanceConfigId);finalDeleteInstanceConfigRequestrequest=DeleteInstanceConfigRequest.newBuilder().setName(instanceConfigName.toString()).build();try{System.out.printf("Deleting %s...\n",instanceConfigName);instanceAdminClient.deleteInstanceConfig(request);System.out.printf("Deleted instance configuration %s\n",instanceConfigName);}catch(SpannerExceptione){System.out.printf("Error: Deleting instance configuration %s failed with error message: %s\n",instanceConfigName,e.getMessage());}}}}Note: The old client library interface code samples for Java are archived inGitHub.
Node.js
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
/** * TODO(developer): Uncomment the following lines before running the sample. */// const instanceConfigId = 'custom-my-instance-config-id';// const projectId = 'my-project-id';// Imports the Google Cloud client libraryconst{Spanner}=require('@google-cloud/spanner');// Creates a clientconstspanner=newSpanner({projectId:projectId,});constinstanceAdminClient=spanner.getInstanceAdminClient();asyncfunctiondeleteInstanceConfig(){// Deletes an instance config.try{// Delete the instance config.console.log(`Deleting${instanceConfigId}...\n`);awaitinstanceAdminClient.deleteInstanceConfig({name:instanceAdminClient.instanceConfigPath(projectId,instanceConfigId,),});console.log(`Deleted instance config${instanceConfigId}.\n`);}catch(err){console.error('ERROR: Deleting instance config ',instanceConfigId,' failed with error message ',err,);}}deleteInstanceConfig();Note: The old client library interface code samples for Node.js are archived inGitHub.
PHP
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;use Google\Cloud\Spanner\Admin\Instance\V1\DeleteInstanceConfigRequest;/** * Deletes a customer managed instance configuration. * Example: * ``` * delete_instance_config($instanceConfigId); * ``` * * @param string $projectId The Google Cloud Project ID. * @param string $instanceConfigId The customer managed instance configuration id. The id must start with 'custom-'. */function delete_instance_config(string $projectId, string $instanceConfigId){ $instanceAdminClient = new InstanceAdminClient(); $instanceConfigName = $instanceAdminClient->instanceConfigName( $projectId, $instanceConfigId ); $request = new DeleteInstanceConfigRequest(); $request->setName($instanceConfigName); $instanceAdminClient->deleteInstanceConfig($request); printf('Deleted instance configuration %s' . PHP_EOL, $instanceConfigId);}Note: The old client library interface code samples for PHP are archived inGitHub.
Python
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
defdelete_instance_config(user_config_id):"""Deleted the user-managed instance configuration."""spanner_client=spanner.Client()spanner_client.instance_admin_api.delete_instance_config(name=user_config_id)print("Instance config{} successfully deleted".format(user_config_id))Note: The old client library interface code samples for Python are archived inGitHub.
Ruby
To learn how to install and use the client library for Spanner, seeSpanner client libraries.
require"google/cloud/spanner"require"google/cloud/spanner/admin/instance"defspanner_delete_instance_configuser_config_id:# user_config_id = "The customer managed instance configuration ID, e.g projects/<project>/instanceConfigs/custom-nam11"instance_admin_client=Google::Cloud::Spanner::Admin::Instance.instance_admininstance_admin_client.delete_instance_configname:user_config_idputs"Deleted instance configuration#{user_config_id}"endWhat's next
- Learn how to insert, update, and delete data withData Manipulation Language(DML) or thegcloud CLI.
- GrantIdentity and Access Management (IAM) roles for the instance and itsdatabases.
- Understand how todesign a Spanner schema.
- SpannerQuotas and limits.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-05 UTC.