This page describes how to list, create, update, delete, and show the details of a Spanner instance configuration. Some custom instance configuration functionalities are not available in the Google Cloud console UI. In those cases, use the Google Cloud CLI (gcloud) commands provided.
List instance configurations
You can list all the available Spanner instance configurations with the Google Cloud CLI and client libraries. To find a list of all Spanner instance configurations, see Regional and multi-region configurations.
gcloud
Run the gcloud spanner instance-configs list
command:
gcloud spanner instance-configs list
C++
To learn how to install and use the client library for Spanner, see Spanner client libraries.
C#
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Go
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Java
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Node.js
To learn how to install and use the client library for Spanner, see Spanner client libraries.
PHP
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Python
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Ruby
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Show instance configuration details
You can show the details of any instance configuration with the
Google Cloud CLI and client libraries. When you
create a new custom instance configuration,
you can add any location listed under optionalReplicas
as an optional replica.
If you don't see your desired read-only replica location, you can
request a new optional read-only replica region.
For more information, see Create a custom instance configuration.
gcloud
Run the gcloud spanner instance-configs describe
command:
gcloud spanner instance-configs describe INSTANCE-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
orus-central1
.
To show the details of the eur6
base configuration, run:
gcloud spanner instance-configs describe eur6
Here's an example output for the eur6
base configuration:
configType: GOOGLE_MANAGED
displayName: Europe (Netherlands, Frankfurt)
freeInstanceAvailability: UNSUPPORTED
leaderOptions:
- europe-west3
- europe-west4
name: projects/cloud-spanner-demo/instanceConfigs/eur6
optionalReplicas:
- displayName: South Carolina
labels:
cloud.googleapis.com/country: US
cloud.googleapis.com/location: us-east1
cloud.googleapis.com/region: us-east1
location: us-east1
type: READ_ONLY
- displayName: South Carolina
labels:
cloud.googleapis.com/country: US
cloud.googleapis.com/location: us-east1
cloud.googleapis.com/region: us-east1
location: us-east1
type: READ_ONLY
replicas:
- defaultLeaderLocation: true
location: europe-west4
type: READ_WRITE
- location: europe-west4
type: READ_WRITE
- location: europe-west3
type: READ_WRITE
- location: europe-west3
type: READ_WRITE
- location: europe-west6
type: WITNESS
Additional usage notes:
baseConfig
(for custom configurations only) points to the base instance configuration. Refer to available regional configurations and available multi-region configurations for lists of base instance configurations that can be used to create a custom instance configuration.configType
indicates whether this instance configuration is a base instance configuration or a custom instance configuration.etag
(for custom configurations only) is a base64-encoded string representation of the configuration. It is used for optimistic concurrency control.
C++
To learn how to install and use the client library for Spanner, see Spanner client libraries.
C#
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Go
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Java
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Node.js
To learn how to install and use the client library for Spanner, see Spanner client libraries.
PHP
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Python
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Ruby
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Create a custom instance configuration
You can create a custom regional or multi-region instance configuration and add optional read-only replicas to scale reads and support low latency stale reads. Refer to available regional configurations and available multi-region configurations for lists of base instance configurations that can be used to create a custom instance configuration. You can't create a custom dual-region instance configuration. For more information about Spanner replication and replica types, see Replication.
To create a custom instance configuration, you must have the
spanner.instanceConfigs.create
permission. By default, roles that have the
spanner.instances.create
permission will also have the
spanner.instanceConfigs.create
permission.
Console
You can't create a custom instance configuration using the Google Cloud console. To create an instance with read-only replicas, use the gcloud CLI or client libraries.
gcloud
Use the gcloud spanner instance-configs create
command:
gcloud spanner instance-configs create CUSTOM-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 another
base or custom instance configuration while also declaring the location and
type of a specific custom replica.
gcloud spanner instance-configs create CUSTOM-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
- A
permanent identifier that is unique within your Google Cloud project. You
can't change the instance configuration ID later. The
custom-
prefix is required to avoid name conflicts with base instance configurations. DISPLAY-NAME
- The name to display for the custom instance configuration in the Google Cloud console. If you choose to use the flags `--base-config` and `--replicas`, provide the following 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 describe INSTANCE-CONFIG
and refer to thereplicas
andoptionalReplicas
lists. TYPE
- The type of replica. To find out what corresponding locations and
replica types are accepted, run
gcloud spanner instance-configs describe INSTANCE-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 the gcloud instance-configs describe help-text.
If you choose to use the flags --clone-config
and --add-replicas
(only
use --skip-replicas
if there are replicas you want to skip from being
cloned), provide the following values:
--clone-config=INSTANCE-CONFIG
Use this flag as a convenient way to clone another base or custom instance configuration while also declaring the location and type of a specific custom replica. Then use
--add-replicas=location=LOCATION,type=TYPE
to specify where you want to add your optional replica.For example, to create a custom instance configuration with two read-only replicas in
us-east1
while copying all the other replica locations from theeur6
base instance configuration, run:gcloud spanner instance-configs create custom-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 one read-only replica in
us-east4
while copying all the other replica locations from thenam3
base instance configuration except the read-only replica inus-central1
, run:gcloud spanner instance-configs create custom-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 of key 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 contain only hyphens (-), underscores (_), lowercase characters, and numbers.
--validate-only
Use this flag to validate that the request will succeed before executing it.
For example, to create a custom instance configuration with the eur6
base
configuration with one additional read-only replica in us-east1
, run:
gcloud spanner instance-configs create custom-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:
gcloud spanner instance-configs create custom-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, see Spanner client libraries.
C#
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Go
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Java
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Node.js
To learn how to install and use the client library for Spanner, see Spanner client libraries.
PHP
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Python
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Ruby
To learn how to install and use the client library for Spanner, see Spanner client libraries.
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 the gcloud CLI or client libraries.
gcloud
After you create the custom instance configuration, follow the instructions provided in Create an instance.
C++
After you create the custom instance configuration, follow the instructions provided in Create an instance.
C#
After you create the custom instance configuration, follow the instructions provided in Create an instance.
Go
After you create the custom instance configuration, follow the instructions provided in Create an instance.
Java
After you create the custom instance configuration, follow the instructions provided in Create an instance.
Node.js
After you create the custom instance configuration, follow the instructions provided in Create an instance.
PHP
After you create the custom instance configuration, follow the instructions provided in Create an instance.
Python
After you create the custom instance configuration, follow the instructions provided in Create an instance.
Ruby
After you create the custom instance configuration, follow the instructions provided in Create 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 additional
replicas, then move your instance to the new
custom instance configuration with your chosen additional replicas. For example,
if your instance is in us-central1
and you want to add a read-only replica
us-west1
, then you need to create a new custom instance configuration with
us-central1
as the base configuration and add us-west1
as a read-only
replica. Then move your instance to this
new custom instance configuration.
gcloud
Use the gcloud spanner instance-configs update
command:
gcloud spanner instance-configs update CUSTOM-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 with
custom-
. 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
: TheETAG
argument can be used to select and skip simultaneous updates in a read-modify-write scenario.--validate-only
: Use this flag to validate that the request will succeed before executing it.
For example:
gcloud spanner instance-configs update custom-eur6 \
--display-name="Customer managed europe replicas"
C++
To learn how to install and use the client library for Spanner, see Spanner client libraries.
C#
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Go
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Java
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Node.js
To learn how to install and use the client library for Spanner, see Spanner client libraries.
PHP
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Python
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Ruby
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Delete a custom instance configuration
To delete a custom instance configuration, first delete any instance in the instance configuration.
gcloud
Use the gcloud spanner instance-configs delete
command, replacing
CUSTOM-INSTANCE-CONFIG-ID
with the custom instance
configuration ID:
gcloud spanner instance-configs delete CUSTOM-INSTANCE-CONFIG-ID
C++
To learn how to install and use the client library for Spanner, see Spanner client libraries.
C#
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Go
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Java
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Node.js
To learn how to install and use the client library for Spanner, see Spanner client libraries.
PHP
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Python
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Ruby
To learn how to install and use the client library for Spanner, see Spanner client libraries.
What's next
- Learn how to insert, update, and delete data with Data Manipulation Language (DML) or the gcloud CLI.
- Grant IAM roles for the instance and its databases.
- Understand how to design a Spanner schema.
- Spanner Quotas and limits.