Index
InstanceAdmin
(interface)CreateInstanceConfigMetadata
(message)CreateInstanceConfigRequest
(message)CreateInstanceMetadata
(message)CreateInstanceRequest
(message)DeleteInstanceConfigRequest
(message)DeleteInstanceRequest
(message)FreeInstanceMetadata
(message)FreeInstanceMetadata.ExpireBehavior
(enum)GetInstanceConfigRequest
(message)GetInstanceRequest
(message)Instance
(message)Instance.InstanceType
(enum)Instance.State
(enum)InstanceConfig
(message)InstanceConfig.FreeInstanceAvailability
(enum)InstanceConfig.State
(enum)InstanceConfig.Type
(enum)ListInstanceConfigOperationsRequest
(message)ListInstanceConfigOperationsResponse
(message)ListInstanceConfigsRequest
(message)ListInstanceConfigsResponse
(message)ListInstancesRequest
(message)ListInstancesResponse
(message)OperationProgress
(message)ReplicaInfo
(message)ReplicaInfo.ReplicaType
(enum)UpdateInstanceConfigMetadata
(message)UpdateInstanceConfigRequest
(message)UpdateInstanceMetadata
(message)UpdateInstanceRequest
(message)
InstanceAdmin
Cloud Spanner Instance Admin API
The Cloud Spanner Instance Admin API can be used to create, delete, modify and list instances. Instances are dedicated Cloud Spanner serving and storage resources to be used by Cloud Spanner databases.
Each instance has a "configuration", which dictates where the serving resources for the Cloud Spanner instance are located (e.g., US-central, Europe). Configurations are created by Google based on resource availability.
Cloud Spanner billing is based on the instances that exist and their sizes. After an instance exists, there are no additional per-database or per-operation charges for use of the instance (though there may be additional network bandwidth charges). Instances offer isolation: problems with databases in one instance will not affect other instances. However, within an instance databases can affect each other. For example, if one database in an instance receives a lot of requests and consumes most of the instance resources, fewer resources are available for other databases in that instance, and their performance may suffer.
CreateInstance |
---|
Creates an instance and begins preparing it to begin serving. The returned Immediately upon completion of this request:
Until completion of the returned operation:
Upon completion of the returned operation:
The returned
|
CreateInstanceConfig |
---|
Creates an instance config and begins preparing it to be used. The returned Immediately after the request returns:
While the operation is pending:
Upon completion of the returned operation:
The returned Authorization requires
|
DeleteInstance |
---|
Deletes an instance. Immediately upon completion of the request:
Soon afterward:
|
DeleteInstanceConfig |
---|
Deletes the instance config. Deletion is only allowed when no instances are using the configuration. If any instances are using the config, returns Only user managed configurations can be deleted. Authorization requires
|
GetIamPolicy |
---|
Gets the access control policy for an instance resource. Returns an empty policy if an instance exists but does not have a policy set. Authorization requires
|
GetInstance |
---|
Gets information about a particular instance.
|
GetInstanceConfig |
---|
Gets information about a particular instance configuration.
|
ListInstanceConfigOperations |
---|
Lists the user-managed instance config
|
ListInstanceConfigs |
---|
Lists the supported instance configurations for a given project.
|
ListInstances |
---|
Lists all instances in the given project.
|
SetIamPolicy |
---|
Sets the access control policy on an instance resource. Replaces any existing policy. Authorization requires
|
TestIamPermissions |
---|
Returns permissions that the caller has on the specified instance resource. Attempting this RPC on a non-existent Cloud Spanner instance resource will result in a NOT_FOUND error if the user has
|
UpdateInstance |
---|
Updates an instance, and begins allocating or releasing resources as requested. The returned Immediately upon completion of this request:
Until completion of the returned operation:
Upon completion of the returned operation:
The returned Authorization requires
|
UpdateInstanceConfig |
---|
Updates an instance config. The returned Only user managed configurations can be updated. Immediately after the request returns:
While the operation is pending:
Upon completion of the returned operation:
The returned Authorization requires
|
CreateInstanceConfigMetadata
Metadata type for the operation returned by CreateInstanceConfig
.
Fields | |
---|---|
instance_config |
The target instance config end state. |
progress |
The progress of the |
cancel_time |
The time at which this operation was cancelled. |
CreateInstanceConfigRequest
The request for [CreateInstanceConfigRequest][InstanceAdmin.CreateInstanceConfigRequest].
Fields | |
---|---|
parent |
Required. The name of the project in which to create the instance config. Values are of the form Authorization requires the following IAM permission on the specified resource
|
instance_config_id |
Required. The ID of the instance config to create. Valid identifiers are of the form |
instance_config |
Required. The InstanceConfig proto of the configuration to create. instance_config.name must be |
validate_only |
An option to validate, but not actually execute, a request, and provide the same response. |
CreateInstanceMetadata
Metadata type for the operation returned by CreateInstance
.
Fields | |
---|---|
instance |
The instance being created. |
start_time |
The time at which the |
cancel_time |
The time at which this operation was cancelled. If set, this operation is in the process of undoing itself (which is guaranteed to succeed) and cannot be cancelled again. |
end_time |
The time at which this operation failed or was completed successfully. |
CreateInstanceRequest
The request for CreateInstance
.
Fields | |
---|---|
parent |
Required. The name of the project in which to create the instance. Values are of the form Authorization requires the following IAM permission on the specified resource
|
instance_id |
Required. The ID of the instance to create. Valid identifiers are of the form |
instance |
Required. The instance to create. The name may be omitted, but if specified must be |
DeleteInstanceConfigRequest
The request for [DeleteInstanceConfigRequest][InstanceAdmin.DeleteInstanceConfigRequest].
Fields | |
---|---|
name |
Required. The name of the instance configuration to be deleted. Values are of the form Authorization requires the following IAM permission on the specified resource
|
etag |
Used for optimistic concurrency control as a way to help prevent simultaneous deletes of an instance config from overwriting each other. If not empty, the API only deletes the instance config when the etag provided matches the current status of the requested instance config. Otherwise, deletes the instance config without checking the current status of the requested instance config. |
validate_only |
An option to validate, but not actually execute, a request, and provide the same response. |
DeleteInstanceRequest
The request for DeleteInstance
.
Fields | |
---|---|
name |
Required. The name of the instance to be deleted. Values are of the form Authorization requires the following IAM permission on the specified resource
|
FreeInstanceMetadata
Free instance specific metadata that is kept even after an instance has been upgraded for tracking purposes.
Fields | |
---|---|
expire_time |
Output only. Timestamp after which the instance will either be upgraded or scheduled for deletion after a grace period. ExpireBehavior is used to choose between upgrading or scheduling the free instance for deletion. This timestamp is set during the creation of a free instance. |
upgrade_time |
Output only. If present, the timestamp at which the free instance was upgraded to a provisioned instance. |
expire_behavior |
Specifies the expiration behavior of a free instance. The default of ExpireBehavior is |
ExpireBehavior
Allows users to change behavior when a free instance expires.
Enums | |
---|---|
EXPIRE_BEHAVIOR_UNSPECIFIED |
Not specified. |
FREE_TO_PROVISIONED |
When the free instance expires, upgrade the instance to a provisioned instance. |
REMOVE_AFTER_GRACE_PERIOD |
When the free instance expires, disable the instance, and delete it after the grace period passes if it has not been upgraded. |
GetInstanceConfigRequest
The request for GetInstanceConfigRequest
.
Fields | |
---|---|
name |
Required. The name of the requested instance configuration. Values are of the form Authorization requires the following IAM permission on the specified resource
|
GetInstanceRequest
The request for GetInstance
.
Fields | |
---|---|
name |
Required. The name of the requested instance. Values are of the form Authorization requires the following IAM permission on the specified resource
|
field_mask |
If field_mask is present, specifies the subset of |
Instance
An isolated set of Cloud Spanner resources on which databases can be hosted.
Fields | |
---|---|
name |
Required. A unique identifier for the instance, which cannot be changed after the instance is created. Values are of the form |
config |
Required. The name of the instance's configuration. Values are of the form |
display_name |
Required. The descriptive name for this instance as it appears in UIs. Must be unique per project and between 4 and 30 characters in length. |
node_count |
The number of nodes allocated to this instance. At most one of either node_count or processing_units should be present in the message. This may be zero in API responses for instances that are not yet in state See the documentation for more information about nodes and processing units. |
processing_units |
The number of processing units allocated to this instance. At most one of processing_units or node_count should be present in the message. This may be zero in API responses for instances that are not yet in state See the documentation for more information about nodes and processing units. |
state |
Output only. The current instance state. For |
labels |
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.).
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. And so 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. |
instance_type |
The |
endpoint_uris[] |
Deprecated. This field is not populated. |
create_time |
Output only. The time at which the instance was created. |
update_time |
Output only. The time at which the instance was most recently updated. |
free_instance_metadata |
Free instance metadata. Only populated for free instances. |
InstanceType
The type of this instance. The type can be used to distinguish product variants, that can affect aspects like: usage restrictions, quotas and billing. Currently this is used to distinguish FREE_INSTANCE vs PROVISIONED instances.
Enums | |
---|---|
INSTANCE_TYPE_UNSPECIFIED |
Not specified. |
PROVISIONED |
Provisioned instances have dedicated resources, standard usage limits and support. |
FREE_INSTANCE |
Free instances provide no guarantee for dedicated resources, [node_count, processing_units] should be 0. They come with stricter usage limits and limited support. |
State
Indicates the current state of the instance.
Enums | |
---|---|
STATE_UNSPECIFIED |
Not specified. |
CREATING |
The instance is still being created. Resources may not be available yet, and operations such as database creation may not work. |
READY |
The instance is fully created and ready to do work such as creating databases. |
InstanceConfig
A possible configuration for a Cloud Spanner instance. Configurations define the geographic placement of nodes and their replication.
Fields | |
---|---|
name |
A unique identifier for the instance configuration. Values are of the form |
display_name |
The name of this instance configuration as it appears in UIs. |
config_type |
Output only. Whether this instance config is a Google or User Managed Configuration. |
replicas[] |
The geographic placement of nodes in this instance configuration and their replication properties. |
optional_replicas[] |
Output only. The available optional replicas to choose from for user managed configurations. Populated for Google managed configurations. |
base_config |
Base configuration name, e.g. projects/ |
labels |
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.).
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. |
etag |
etag is used for optimistic concurrency control as a way to help prevent simultaneous updates of a instance config from overwriting each other. It is strongly suggested that systems make use of the etag in the read-modify-write cycle to perform instance config updates in order to avoid race conditions: An etag is returned in the response which contains instance configs, and systems are expected to put that etag in the request to update instance config to ensure that their change will be applied to the same version of the instance config. If no etag is provided in the call to update instance config, then the existing instance config is overwritten blindly. |
leader_options[] |
Allowed values of the "default_leader" schema option for databases in instances that use this instance configuration. |
reconciling |
Output only. If true, the instance config is being created or updated. If false, there are no ongoing operations for the instance config. |
state |
Output only. The current instance config state. |
free_instance_availability |
Output only. Describes whether free instances are available to be created in this instance config. |
FreeInstanceAvailability
Describes the availability for free instances to be created in an instance config.
Enums | |
---|---|
FREE_INSTANCE_AVAILABILITY_UNSPECIFIED |
Not specified. |
AVAILABLE |
Indicates that free instances are available to be created in this instance config. |
UNSUPPORTED |
Indicates that free instances are not supported in this instance config. |
DISABLED |
Indicates that free instances are currently not available to be created in this instance config. |
QUOTA_EXCEEDED |
Indicates that additional free instances cannot be created in this instance config because the project has reached its limit of free instances. |
State
Indicates the current state of the instance config.
Enums | |
---|---|
STATE_UNSPECIFIED |
Not specified. |
CREATING |
The instance config is still being created. |
READY |
The instance config is fully created and ready to be used to create instances. |
Type
The type of this configuration.
Enums | |
---|---|
TYPE_UNSPECIFIED |
Unspecified. |
GOOGLE_MANAGED |
Google managed configuration. |
USER_MANAGED |
User managed configuration. |
ListInstanceConfigOperationsRequest
The request for ListInstanceConfigOperations
.
Fields | |
---|---|
parent |
Required. The project of the instance config operations. Values are of the form Authorization requires the following IAM permission on the specified resource
|
filter |
An expression that filters the list of returned operations. A filter expression consists of a field name, a comparison operator, and a value for filtering. The value must be a string, a number, or a boolean. The comparison operator must be one of: The following fields in the
You can combine multiple expressions by enclosing each expression in parentheses. By default, expressions are combined with AND logic. However, you can specify AND, OR, and NOT logic explicitly. Here are a few examples:
|
page_size |
Number of operations to be returned in the response. If 0 or less, defaults to the server's maximum allowed page size. |
page_token |
If non-empty, |
ListInstanceConfigOperationsResponse
The response for ListInstanceConfigOperations
.
Fields | |
---|---|
operations[] |
The list of matching instance config |
next_page_token |
|
ListInstanceConfigsRequest
The request for ListInstanceConfigs
.
Fields | |
---|---|
parent |
Required. The name of the project for which a list of supported instance configurations is requested. Values are of the form Authorization requires the following IAM permission on the specified resource
|
page_size |
Number of instance configurations to be returned in the response. If 0 or less, defaults to the server's maximum allowed page size. |
page_token |
If non-empty, |
ListInstanceConfigsResponse
The response for ListInstanceConfigs
.
Fields | |
---|---|
instance_configs[] |
The list of requested instance configurations. |
next_page_token |
|
ListInstancesRequest
The request for ListInstances
.
Fields | |
---|---|
parent |
Required. The name of the project for which a list of instances is requested. Values are of the form Authorization requires the following IAM permission on the specified resource
|
page_size |
Number of instances to be returned in the response. If 0 or less, defaults to the server's maximum allowed page size. |
page_token |
If non-empty, |
filter |
An expression for filtering the results of the request. Filter rules are case insensitive. The fields eligible for filtering are:
Some examples of using filters are:
|
instance_deadline |
Deadline used while retrieving metadata for instances. Instances whose metadata cannot be retrieved within this deadline will be added to |
ListInstancesResponse
The response for ListInstances
.
Fields | |
---|---|
instances[] |
The list of requested instances. |
next_page_token |
|
unreachable[] |
The list of unreachable instances. It includes the names of instances whose metadata could not be retrieved within |
OperationProgress
Encapsulates progress related information for a Cloud Spanner long running instance operations.
Fields | |
---|---|
progress_percent |
Percent completion of the operation. Values are between 0 and 100 inclusive. |
start_time |
Time the request was received. |
end_time |
If set, the time at which this operation failed or was completed successfully. |
ReplicaInfo
Fields | |
---|---|
location |
The location of the serving resources, e.g. "us-central1". |
type |
The type of replica. |
default_leader_location |
If true, this location is designated as the default leader location where leader replicas are placed. See the region types documentation for more details. |
ReplicaType
Indicates the type of replica. See the replica types documentation for more details.
Enums | |
---|---|
TYPE_UNSPECIFIED |
Not specified. |
READ_WRITE |
Read-write replicas support both reads and writes. These replicas:
|
READ_ONLY |
Read-only replicas only support reads (not writes). Read-only replicas:
|
WITNESS |
Witness replicas don't support reads but do participate in voting to commit writes. Witness replicas:
|
UpdateInstanceConfigMetadata
Metadata type for the operation returned by UpdateInstanceConfig
.
Fields | |
---|---|
instance_config |
The desired instance config after updating. |
progress |
The progress of the |
cancel_time |
The time at which this operation was cancelled. |
UpdateInstanceConfigRequest
The request for [UpdateInstanceConfigRequest][InstanceAdmin.UpdateInstanceConfigRequest].
Fields | |
---|---|
instance_config |
Required. The user instance config to update, which must always include the instance config name. Otherwise, only fields mentioned in Authorization requires the following IAM permission on the specified resource
|
update_mask |
Required. A mask specifying which fields in |
validate_only |
An option to validate, but not actually execute, a request, and provide the same response. |
UpdateInstanceMetadata
Metadata type for the operation returned by UpdateInstance
.
Fields | |
---|---|
instance |
The desired end state of the update. |
start_time |
The time at which |
cancel_time |
The time at which this operation was cancelled. If set, this operation is in the process of undoing itself (which is guaranteed to succeed) and cannot be cancelled again. |
end_time |
The time at which this operation failed or was completed successfully. |
UpdateInstanceRequest
The request for UpdateInstance
.
Fields | |
---|---|
instance |
Required. The instance to update, which must always include the instance name. Otherwise, only fields mentioned in Authorization requires the following IAM permission on the specified resource
|
field_mask |
Required. A mask specifying which fields in |