Create and manage instance configurations

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-configslist

C++

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}"end

Show 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-CONFIG

Provide the following value:

INSTANCE-CONFIG
The instance configuration, which defines the geographic location of the instance and affects how data is replicated. For example,eur6 orregional-us-central1.

To show the details of theeur6 base configuration, run:

gcloudspannerinstance-configsdescribeeur6

Here'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:WITNESS

Additional 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.
  • configType indicates 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. Thecustom-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,eur6 orregional-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-CONFIG and refer to thereplicas andoptionalReplicas lists.
TYPE
The type of replica. To find out what corresponding locations and replica types are accepted, rungcloud spanner instance-configs describeINSTANCE-CONFIG and refer to thereplicas andoptionalReplicas lists. 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 replicaLOCATION andTYPE must 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-CONFIG

    Use 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 inus-east1 while copying all the other replicalocations from theeur6 base 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=TYPE

    Use this flag to skip any replica from being cloned.

    For example, to create a custom instance configuration with oneread-only replica inus-east4 while copying all the other replicalocations from thenam3 base 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,[...]

    KEY andVALUE: 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-only

    Use 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_ONLY

You 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}"endend

Create 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=ETAG

Provide the following values:

CUSTOM-INSTANCE-CONFIG-ID
A permanent identifier of your custom instance configuration. It will start withcustom-.
NEW-DISPLAY-NAME
The new name to display for the instance configuration in the Google Cloud console.
KEY andVALUE
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}"endend

Delete 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-ID

C++

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}"end

What's next

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.