instance_configs

Creates, updates, deletes, gets or lists an instance_configs resource.

Overview

Name	instance_configs
Type	Resource
Id	google.spanner.instance_configs

Fields

The following fields are returned by SELECT queries:

projects_instance_configs_get

Successful response

Name	Datatype	Description
name	string	A unique identifier for the instance configuration. Values are of the form projects//instanceConfigs/a-z*. User instance configuration must start with custom-.
baseConfig	string	Base configuration name, e.g. projects//instanceConfigs/nam3, based on which this configuration is created. Only set for user-managed configurations. base_config must refer to a configuration of type GOOGLE_MANAGED in the same project as this configuration.
configType	string	Output only. Whether this instance configuration is a Google-managed or user-managed configuration.
displayName	string	The name of this instance configuration as it appears in UIs.
etag	string	etag is used for optimistic concurrency control as a way to help prevent simultaneous updates of a instance configuration from overwriting each other. It is strongly suggested that systems make use of the etag in the read-modify-write cycle to perform instance configuration updates in order to avoid race conditions: An etag is returned in the response which contains instance configurations, and systems are expected to put that etag in the request to update instance configuration to ensure that their change is applied to the same version of the instance configuration. If no etag is provided in the call to update the instance configuration, then the existing instance configuration is overwritten blindly.
freeInstanceAvailability	string	Output only. Describes whether free instances are available to be created in this instance configuration.
labels	object	Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources into groups that reflect a customer's organizational needs and deployment strategies. Cloud Labels can be used to filter collections of resources. They can be used to control how resource metrics are aggregated. And they can be used as arguments to policy management rules (e.g. route, firewall, load balancing, etc.). * Label keys must be between 1 and 63 characters long and must conform to the following regular expression: a-z{0,62}. * Label values must be between 0 and 63 characters long and must conform to the regular expression [a-z0-9_-]{0,63}. * No more than 64 labels can be associated with a given resource. See https://goo.gl/xmQnxf for more information on and examples of labels. If you plan to use labels in your own code, please note that additional characters may be allowed in the future. Therefore, you are advised to use an internal label representation, such as JSON, which doesn't rely upon specific characters being disallowed. For example, representing labels as the string: name + "" + value would prove problematic if we were to allow "" in a future release.
leaderOptions	array	Allowed values of the "default_leader" schema option for databases in instances that use this instance configuration.
optionalReplicas	array	Output only. The available optional replicas to choose from for user-managed configurations. Populated for Google-managed configurations.
quorumType	string	Output only. The QuorumType of the instance configuration.
reconciling	boolean	Output only. If true, the instance configuration is being created or updated. If false, there are no ongoing operations for the instance configuration.
replicas	array	The geographic placement of nodes in this instance configuration and their replication properties. To create user-managed configurations, input replicas must include all replicas in replicas of the base_config and include one or more replicas in the optional_replicas of the base_config.
state	string	Output only. The current instance configuration state. Applicable only for USER_MANAGED configurations.
storageLimitPerProcessingUnit	string (int64)	Output only. The storage limit in bytes per processing unit.

projects_instance_configs_list

Successful response

Name	Datatype	Description
name	string	A unique identifier for the instance configuration. Values are of the form projects//instanceConfigs/a-z*. User instance configuration must start with custom-.
baseConfig	string	Base configuration name, e.g. projects//instanceConfigs/nam3, based on which this configuration is created. Only set for user-managed configurations. base_config must refer to a configuration of type GOOGLE_MANAGED in the same project as this configuration.
configType	string	Output only. Whether this instance configuration is a Google-managed or user-managed configuration.
displayName	string	The name of this instance configuration as it appears in UIs.
etag	string	etag is used for optimistic concurrency control as a way to help prevent simultaneous updates of a instance configuration from overwriting each other. It is strongly suggested that systems make use of the etag in the read-modify-write cycle to perform instance configuration updates in order to avoid race conditions: An etag is returned in the response which contains instance configurations, and systems are expected to put that etag in the request to update instance configuration to ensure that their change is applied to the same version of the instance configuration. If no etag is provided in the call to update the instance configuration, then the existing instance configuration is overwritten blindly.
freeInstanceAvailability	string	Output only. Describes whether free instances are available to be created in this instance configuration.
labels	object	Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources into groups that reflect a customer's organizational needs and deployment strategies. Cloud Labels can be used to filter collections of resources. They can be used to control how resource metrics are aggregated. And they can be used as arguments to policy management rules (e.g. route, firewall, load balancing, etc.). * Label keys must be between 1 and 63 characters long and must conform to the following regular expression: a-z{0,62}. * Label values must be between 0 and 63 characters long and must conform to the regular expression [a-z0-9_-]{0,63}. * No more than 64 labels can be associated with a given resource. See https://goo.gl/xmQnxf for more information on and examples of labels. If you plan to use labels in your own code, please note that additional characters may be allowed in the future. Therefore, you are advised to use an internal label representation, such as JSON, which doesn't rely upon specific characters being disallowed. For example, representing labels as the string: name + "" + value would prove problematic if we were to allow "" in a future release.
leaderOptions	array	Allowed values of the "default_leader" schema option for databases in instances that use this instance configuration.
optionalReplicas	array	Output only. The available optional replicas to choose from for user-managed configurations. Populated for Google-managed configurations.
quorumType	string	Output only. The QuorumType of the instance configuration.
reconciling	boolean	Output only. If true, the instance configuration is being created or updated. If false, there are no ongoing operations for the instance configuration.
replicas	array	The geographic placement of nodes in this instance configuration and their replication properties. To create user-managed configurations, input replicas must include all replicas in replicas of the base_config and include one or more replicas in the optional_replicas of the base_config.
state	string	Output only. The current instance configuration state. Applicable only for USER_MANAGED configurations.
storageLimitPerProcessingUnit	string (int64)	Output only. The storage limit in bytes per processing unit.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
projects_instance_configs_get	select	projectsId, instanceConfigsId		Gets information about a particular instance configuration.
projects_instance_configs_list	select	projectsId	pageSize, pageToken	Lists the supported instance configurations for a given project. Returns both Google-managed configurations and user-managed configurations.
projects_instance_configs_create	insert	projectsId		Creates an instance configuration and begins preparing it to be used. The returned long-running operation can be used to track the progress of preparing the new instance configuration. The instance configuration name is assigned by the caller. If the named instance configuration already exists, CreateInstanceConfig returns ALREADY_EXISTS. Immediately after the request returns: * The instance configuration is readable via the API, with all requested attributes. The instance configuration's reconciling field is set to true. Its state is CREATING. While the operation is pending: * Cancelling the operation renders the instance configuration immediately unreadable via the API. * Except for deleting the creating resource, all other attempts to modify the instance configuration are rejected. Upon completion of the returned operation: * Instances can be created using the instance configuration. * The instance configuration's reconciling field becomes false. Its state becomes READY. The returned long-running operation will have a name of the format /operations/ and can be used to track creation of the instance configuration. The metadata field type is CreateInstanceConfigMetadata. The response field type is InstanceConfig, if successful. Authorization requires spanner.instanceConfigs.create permission on the resource parent.
projects_instance_configs_patch	update	projectsId, instanceConfigsId		Updates an instance configuration. The returned long-running operation can be used to track the progress of updating the instance. If the named instance configuration does not exist, returns NOT_FOUND. Only user-managed configurations can be updated. Immediately after the request returns: * The instance configuration's reconciling field is set to true. While the operation is pending: * Cancelling the operation sets its metadata's cancel_time. The operation is guaranteed to succeed at undoing all changes, after which point it terminates with a CANCELLED status. * All other attempts to modify the instance configuration are rejected. * Reading the instance configuration via the API continues to give the pre-request values. Upon completion of the returned operation: * Creating instances using the instance configuration uses the new values. * The new values of the instance configuration are readable via the API. * The instance configuration's reconciling field becomes false. The returned long-running operation will have a name of the format /operations/ and can be used to track the instance configuration modification. The metadata field type is UpdateInstanceConfigMetadata. The response field type is InstanceConfig, if successful. Authorization requires spanner.instanceConfigs.update permission on the resource name.
projects_instance_configs_delete	delete	projectsId, instanceConfigsId	etag, validateOnly	Deletes the instance configuration. Deletion is only allowed when no instances are using the configuration. If any instances are using the configuration, returns FAILED_PRECONDITION. Only user-managed configurations can be deleted. Authorization requires spanner.instanceConfigs.delete permission on the resource name.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
instanceConfigsId	string
projectsId	string
etag	string
pageSize	integer (int32)
pageToken	string
validateOnly	boolean

SELECT examples

projects_instance_configs_get

Gets information about a particular instance configuration.

SELECT
name,
baseConfig,
configType,
displayName,
etag,
freeInstanceAvailability,
labels,
leaderOptions,
optionalReplicas,
quorumType,
reconciling,
replicas,
state,
storageLimitPerProcessingUnit
FROM google.spanner.instance_configs
WHERE projectsId = '{{ projectsId }}' -- required
AND instanceConfigsId = '{{ instanceConfigsId }}' -- required;

projects_instance_configs_list

Lists the supported instance configurations for a given project. Returns both Google-managed configurations and user-managed configurations.

SELECT
name,
baseConfig,
configType,
displayName,
etag,
freeInstanceAvailability,
labels,
leaderOptions,
optionalReplicas,
quorumType,
reconciling,
replicas,
state,
storageLimitPerProcessingUnit
FROM google.spanner.instance_configs
WHERE projectsId = '{{ projectsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}';

INSERT examples

projects_instance_configs_create

Creates an instance configuration and begins preparing it to be used. The returned long-running operation can be used to track the progress of preparing the new instance configuration. The instance configuration name is assigned by the caller. If the named instance configuration already exists, CreateInstanceConfig returns ALREADY_EXISTS. Immediately after the request returns: * The instance configuration is readable via the API, with all requested attributes. The instance configuration's reconciling field is set to true. Its state is CREATING. While the operation is pending: * Cancelling the operation renders the instance configuration immediately unreadable via the API. * Except for deleting the creating resource, all other attempts to modify the instance configuration are rejected. Upon completion of the returned operation: * Instances can be created using the instance configuration. * The instance configuration's reconciling field becomes false. Its state becomes READY. The returned long-running operation will have a name of the format /operations/ and can be used to track creation of the instance configuration. The metadata field type is CreateInstanceConfigMetadata. The response field type is InstanceConfig, if successful. Authorization requires spanner.instanceConfigs.create permission on the resource parent.

INSERT INTO google.spanner.instance_configs (
data__instanceConfigId,
data__instanceConfig,
data__validateOnly,
projectsId
)
SELECT 
'{{ instanceConfigId }}',
'{{ instanceConfig }}',
{{ validateOnly }},
'{{ projectsId }}'
RETURNING
name,
done,
error,
metadata,
response
;

Manifest

# Description fields are for documentation purposes
- name: instance_configs
  props:
    - name: projectsId
      value: string
      description: Required parameter for the instance_configs resource.
    - name: instanceConfigId
      value: string
      description: >
        Required. The ID of the instance configuration to create. Valid identifiers are of the form `custom-[-a-z0-9]*[a-z0-9]` and must be between 2 and 64 characters in length. The `custom-` prefix is required to avoid name conflicts with Google-managed configurations.
        
    - name: instanceConfig
      value: object
      description: >
        A possible configuration for a Cloud Spanner instance. Configurations define the geographic placement of nodes and their replication.
        
    - name: validateOnly
      value: boolean
      description: >
        An option to validate, but not actually execute, a request, and provide the same response.
        

UPDATE examples

projects_instance_configs_patch

Updates an instance configuration. The returned long-running operation can be used to track the progress of updating the instance. If the named instance configuration does not exist, returns NOT_FOUND. Only user-managed configurations can be updated. Immediately after the request returns: * The instance configuration's reconciling field is set to true. While the operation is pending: * Cancelling the operation sets its metadata's cancel_time. The operation is guaranteed to succeed at undoing all changes, after which point it terminates with a CANCELLED status. * All other attempts to modify the instance configuration are rejected. * Reading the instance configuration via the API continues to give the pre-request values. Upon completion of the returned operation: * Creating instances using the instance configuration uses the new values. * The new values of the instance configuration are readable via the API. * The instance configuration's reconciling field becomes false. The returned long-running operation will have a name of the format /operations/ and can be used to track the instance configuration modification. The metadata field type is UpdateInstanceConfigMetadata. The response field type is InstanceConfig, if successful. Authorization requires spanner.instanceConfigs.update permission on the resource name.

UPDATE google.spanner.instance_configs
SET 
data__instanceConfig = '{{ instanceConfig }}',
data__updateMask = '{{ updateMask }}',
data__validateOnly = {{ validateOnly }}
WHERE 
projectsId = '{{ projectsId }}' --required
AND instanceConfigsId = '{{ instanceConfigsId }}' --required
RETURNING
name,
done,
error,
metadata,
response;

DELETE examples

projects_instance_configs_delete

Deletes the instance configuration. Deletion is only allowed when no instances are using the configuration. If any instances are using the configuration, returns FAILED_PRECONDITION. Only user-managed configurations can be deleted. Authorization requires spanner.instanceConfigs.delete permission on the resource name.

DELETE FROM google.spanner.instance_configs
WHERE projectsId = '{{ projectsId }}' --required
AND instanceConfigsId = '{{ instanceConfigsId }}' --required
AND etag = '{{ etag }}'
AND validateOnly = '{{ validateOnly }}';