diff --git a/google/spanner/admin/instance/v1/spanner_instance_admin.proto b/google/spanner/admin/instance/v1/spanner_instance_admin.proto index 58051df00f17f..836b9063fb399 100644 --- a/google/spanner/admin/instance/v1/spanner_instance_admin.proto +++ b/google/spanner/admin/instance/v1/spanner_instance_admin.proto @@ -1,4 +1,4 @@ -// Copyright 2022 Google LLC +// Copyright 2024 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -235,6 +235,15 @@ service InstanceAdmin { option (google.api.method_signature) = "parent"; } + // Lists all instance partitions for the given instance. + rpc ListInstancePartitions(ListInstancePartitionsRequest) + returns (ListInstancePartitionsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/instances/*}/instancePartitions" + }; + option (google.api.method_signature) = "parent"; + } + // Gets information about a particular instance. rpc GetInstance(GetInstanceRequest) returns (Instance) { option (google.api.http) = { @@ -403,6 +412,161 @@ service InstanceAdmin { }; option (google.api.method_signature) = "resource,permissions"; } + + // Gets information about a particular instance partition. + rpc GetInstancePartition(GetInstancePartitionRequest) + returns (InstancePartition) { + option (google.api.http) = { + get: "/v1/{name=projects/*/instances/*/instancePartitions/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Creates an instance partition and begins preparing it to be used. The + // returned [long-running operation][google.longrunning.Operation] + // can be used to track the progress of preparing the new instance partition. + // The instance partition name is assigned by the caller. If the named + // instance partition already exists, `CreateInstancePartition` returns + // `ALREADY_EXISTS`. + // + // Immediately upon completion of this request: + // + // * The instance partition is readable via the API, with all requested + // attributes but no allocated resources. Its state is `CREATING`. + // + // Until completion of the returned operation: + // + // * Cancelling the operation renders the instance partition immediately + // unreadable via the API. + // * The instance partition can be deleted. + // * All other attempts to modify the instance partition are rejected. + // + // Upon completion of the returned operation: + // + // * Billing for all successfully-allocated resources begins (some types + // may have lower than the requested levels). + // * Databases can start using this instance partition. + // * The instance partition's allocated resource levels are readable via the + // API. + // * The instance partition's state becomes `READY`. + // + // The returned [long-running operation][google.longrunning.Operation] will + // have a name of the format + // `/operations/` and can be used to + // track creation of the instance partition. The + // [metadata][google.longrunning.Operation.metadata] field type is + // [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata]. + // The [response][google.longrunning.Operation.response] field type is + // [InstancePartition][google.spanner.admin.instance.v1.InstancePartition], if + // successful. + rpc CreateInstancePartition(CreateInstancePartitionRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/instances/*}/instancePartitions" + body: "*" + }; + option (google.api.method_signature) = + "parent,instance_partition,instance_partition_id"; + option (google.longrunning.operation_info) = { + response_type: "google.spanner.admin.instance.v1.InstancePartition" + metadata_type: "google.spanner.admin.instance.v1.CreateInstancePartitionMetadata" + }; + } + + // Deletes an existing instance partition. Requires that the + // instance partition is not used by any database or backup and is not the + // default instance partition of an instance. + // + // Authorization requires `spanner.instancePartitions.delete` permission on + // the resource + // [name][google.spanner.admin.instance.v1.InstancePartition.name]. + rpc DeleteInstancePartition(DeleteInstancePartitionRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/instances/*/instancePartitions/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Updates an instance partition, and begins allocating or releasing resources + // as requested. The returned [long-running + // operation][google.longrunning.Operation] can be used to track the + // progress of updating the instance partition. If the named instance + // partition does not exist, returns `NOT_FOUND`. + // + // Immediately upon completion of this request: + // + // * For resource types for which a decrease in the instance partition's + // allocation has been requested, billing is based on the newly-requested + // level. + // + // Until completion of the returned operation: + // + // * Cancelling the operation sets its metadata's + // [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], + // and begins restoring resources to their pre-request values. The + // operation is guaranteed to succeed at undoing all resource changes, + // after which point it terminates with a `CANCELLED` status. + // * All other attempts to modify the instance partition are rejected. + // * Reading the instance partition via the API continues to give the + // pre-request resource levels. + // + // Upon completion of the returned operation: + // + // * Billing begins for all successfully-allocated resources (some types + // may have lower than the requested levels). + // * All newly-reserved resources are available for serving the instance + // partition's tables. + // * The instance partition's new resource levels are readable via the API. + // + // The returned [long-running operation][google.longrunning.Operation] will + // have a name of the format + // `/operations/` and can be used to + // track the instance partition modification. The + // [metadata][google.longrunning.Operation.metadata] field type is + // [UpdateInstancePartitionMetadata][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata]. + // The [response][google.longrunning.Operation.response] field type is + // [InstancePartition][google.spanner.admin.instance.v1.InstancePartition], if + // successful. + // + // Authorization requires `spanner.instancePartitions.update` permission on + // the resource + // [name][google.spanner.admin.instance.v1.InstancePartition.name]. + rpc UpdateInstancePartition(UpdateInstancePartitionRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + patch: "/v1/{instance_partition.name=projects/*/instances/*/instancePartitions/*}" + body: "*" + }; + option (google.api.method_signature) = "instance_partition,field_mask"; + option (google.longrunning.operation_info) = { + response_type: "google.spanner.admin.instance.v1.InstancePartition" + metadata_type: "google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata" + }; + } + + // Lists instance partition [long-running + // operations][google.longrunning.Operation] in the given instance. + // An instance partition operation has a name of the form + // `projects//instances//instancePartitions//operations/`. + // The long-running operation + // [metadata][google.longrunning.Operation.metadata] field type + // `metadata.type_url` describes the type of the metadata. Operations returned + // include those that have completed/failed/canceled within the last 7 days, + // and pending operations. Operations returned are ordered by + // `operation.metadata.value.start_time` in descending order starting from the + // most recently started operation. + // + // Authorization requires `spanner.instancePartitionOperations.list` + // permission on the resource + // [parent][google.spanner.admin.instance.v1.ListInstancePartitionOperationsRequest.parent]. + rpc ListInstancePartitionOperations(ListInstancePartitionOperationsRequest) + returns (ListInstancePartitionOperationsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/instances/*}/instancePartitionOperations" + }; + option (google.api.method_signature) = "parent"; + } } message ReplicaInfo { @@ -1041,6 +1205,14 @@ message ListInstancesRequest { // it has the label "env" with its value // containing "dev". string filter = 4; + + // Deadline used while retrieving metadata for instances. + // Instances whose metadata cannot be retrieved within this deadline will be + // added to + // [unreachable][google.spanner.admin.instance.v1.ListInstancesResponse.unreachable] + // in + // [ListInstancesResponse][google.spanner.admin.instance.v1.ListInstancesResponse]. + google.protobuf.Timestamp instance_deadline = 5; } // The response for @@ -1053,6 +1225,12 @@ message ListInstancesResponse { // [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances] // call to fetch more of the matching instances. string next_page_token = 2; + + // The list of unreachable instances. + // It includes the names of instances whose metadata could not be retrieved + // within + // [instance_deadline][google.spanner.admin.instance.v1.ListInstancesRequest.instance_deadline]. + repeated string unreachable = 3; } // The request for @@ -1155,3 +1333,381 @@ message UpdateInstanceConfigMetadata { // The time at which this operation was cancelled. google.protobuf.Timestamp cancel_time = 3; } + +// An isolated set of Cloud Spanner resources that databases can define +// placements on. +message InstancePartition { + option (google.api.resource) = { + type: "spanner.googleapis.com/InstancePartition" + pattern: "projects/{project}/instances/{instance}/instancePartitions/{instance_partition}" + }; + + // Indicates the current state of the instance partition. + enum State { + // Not specified. + STATE_UNSPECIFIED = 0; + + // The instance partition is still being created. Resources may not be + // available yet, and operations such as creating placements using this + // instance partition may not work. + CREATING = 1; + + // The instance partition is fully created and ready to do work such as + // creating placements and using in databases. + READY = 2; + } + + // Required. A unique identifier for the instance partition. Values are of the + // form + // `projects//instances//instancePartitions/[a-z][-a-z0-9]*[a-z0-9]`. + // The final segment of the name must be between 2 and 64 characters in + // length. An instance partition's name cannot be changed after the instance + // partition is created. + string name = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The name of the instance partition's configuration. Values are of + // the form `projects//instanceConfigs/`. See also + // [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig] and + // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. + string config = 2 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/InstanceConfig" + } + ]; + + // Required. The descriptive name for this instance partition as it appears in + // UIs. Must be unique per project and between 4 and 30 characters in length. + string display_name = 3 [(google.api.field_behavior) = REQUIRED]; + + // Compute capacity defines amount of server and storage resources that are + // available to the databases in an instance partition. At most one of either + // node_count or processing_units should be present in the message. See [the + // documentation](https://cloud.google.com/spanner/docs/compute-capacity) + // for more information about nodes and processing units. + oneof compute_capacity { + // The number of nodes allocated to this instance partition. + // + // Users can set the node_count field to specify the target number of nodes + // allocated to the instance partition. + // + // This may be zero in API responses for instance partitions that are not + // yet in state `READY`. + int32 node_count = 5; + + // The number of processing units allocated to this instance partition. + // + // Users can set the processing_units field to specify the target number of + // processing units allocated to the instance partition. + // + // This may be zero in API responses for instance partitions that are not + // yet in state `READY`. + int32 processing_units = 6; + } + + // Output only. The current instance partition state. + State state = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The time at which the instance partition was created. + google.protobuf.Timestamp create_time = 8 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The time at which the instance partition was most recently + // updated. + google.protobuf.Timestamp update_time = 9 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The names of the databases that reference this + // instance partition. Referencing databases should share the parent instance. + // The existence of any referencing database prevents the instance partition + // from being deleted. + repeated string referencing_databases = 10 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The names of the backups that reference this instance + // partition. Referencing backups should share the parent instance. The + // existence of any referencing backup prevents the instance partition from + // being deleted. + repeated string referencing_backups = 11 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Used for optimistic concurrency control as a way + // to help prevent simultaneous updates of a instance partition from + // overwriting each other. It is strongly suggested that systems make use of + // the etag in the read-modify-write cycle to perform instance partition + // updates in order to avoid race conditions: An etag is returned in the + // response which contains instance partitions, and systems are expected to + // put that etag in the request to update instance partitions to ensure that + // their change will be applied to the same version of the instance partition. + // If no etag is provided in the call to update instance partition, then the + // existing instance partition is overwritten blindly. + string etag = 12; +} + +// Metadata type for the operation returned by +// [CreateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstancePartition]. +message CreateInstancePartitionMetadata { + // The instance partition being created. + InstancePartition instance_partition = 1; + + // The time at which the + // [CreateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstancePartition] + // request was received. + google.protobuf.Timestamp start_time = 2; + + // 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. + google.protobuf.Timestamp cancel_time = 3; + + // The time at which this operation failed or was completed successfully. + google.protobuf.Timestamp end_time = 4; +} + +// The request for +// [CreateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstancePartition]. +message CreateInstancePartitionRequest { + // Required. The name of the instance in which to create the instance + // partition. Values are of the form + // `projects//instances/`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Instance" + } + ]; + + // Required. The ID of the instance partition to create. Valid identifiers are + // of the form `[a-z][-a-z0-9]*[a-z0-9]` and must be between 2 and 64 + // characters in length. + string instance_partition_id = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. The instance partition to create. The instance_partition.name may + // be omitted, but if specified must be + // `/instancePartitions/`. + InstancePartition instance_partition = 3 + [(google.api.field_behavior) = REQUIRED]; +} + +// The request for +// [DeleteInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstancePartition]. +message DeleteInstancePartitionRequest { + // Required. The name of the instance partition to be deleted. + // Values are of the form + // `projects/{project}/instances/{instance}/instancePartitions/{instance_partition}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/InstancePartition" + } + ]; + + // Optional. If not empty, the API only deletes the instance partition when + // the etag provided matches the current status of the requested instance + // partition. Otherwise, deletes the instance partition without checking the + // current status of the requested instance partition. + string etag = 2; +} + +// The request for +// [GetInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.GetInstancePartition]. +message GetInstancePartitionRequest { + // Required. The name of the requested instance partition. Values are of + // the form + // `projects/{project}/instances/{instance}/instancePartitions/{instance_partition}`. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/InstancePartition" + } + ]; +} + +// The request for +// [UpdateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstancePartition]. +message UpdateInstancePartitionRequest { + // Required. The instance partition to update, which must always include the + // instance partition name. Otherwise, only fields mentioned in + // [field_mask][google.spanner.admin.instance.v1.UpdateInstancePartitionRequest.field_mask] + // need be included. + InstancePartition instance_partition = 1 + [(google.api.field_behavior) = REQUIRED]; + + // Required. A mask specifying which fields in + // [InstancePartition][google.spanner.admin.instance.v1.InstancePartition] + // should be updated. The field mask must always be specified; this prevents + // any future fields in + // [InstancePartition][google.spanner.admin.instance.v1.InstancePartition] + // from being erased accidentally by clients that do not know about them. + google.protobuf.FieldMask field_mask = 2 + [(google.api.field_behavior) = REQUIRED]; +} + +// Metadata type for the operation returned by +// [UpdateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstancePartition]. +message UpdateInstancePartitionMetadata { + // The desired end state of the update. + InstancePartition instance_partition = 1; + + // The time at which + // [UpdateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstancePartition] + // request was received. + google.protobuf.Timestamp start_time = 2; + + // 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. + google.protobuf.Timestamp cancel_time = 3; + + // The time at which this operation failed or was completed successfully. + google.protobuf.Timestamp end_time = 4; +} + +// The request for +// [ListInstancePartitions][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitions]. +message ListInstancePartitionsRequest { + // Required. The instance whose instance partitions should be listed. Values + // are of the form `projects//instances/`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Instance" + } + ]; + + // Number of instance partitions to be returned in the response. If 0 or less, + // defaults to the server's maximum allowed page size. + int32 page_size = 2; + + // If non-empty, `page_token` should contain a + // [next_page_token][google.spanner.admin.instance.v1.ListInstancePartitionsResponse.next_page_token] + // from a previous + // [ListInstancePartitionsResponse][google.spanner.admin.instance.v1.ListInstancePartitionsResponse]. + string page_token = 3; + + // Optional. Deadline used while retrieving metadata for instance partitions. + // Instance partitions whose metadata cannot be retrieved within this deadline + // will be added to + // [unreachable][google.spanner.admin.instance.v1.ListInstancePartitionsResponse.unreachable] + // in + // [ListInstancePartitionsResponse][google.spanner.admin.instance.v1.ListInstancePartitionsResponse]. + google.protobuf.Timestamp instance_partition_deadline = 4 + [(google.api.field_behavior) = OPTIONAL]; +} + +// The response for +// [ListInstancePartitions][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitions]. +message ListInstancePartitionsResponse { + // The list of requested instancePartitions. + repeated InstancePartition instance_partitions = 1; + + // `next_page_token` can be sent in a subsequent + // [ListInstancePartitions][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitions] + // call to fetch more of the matching instance partitions. + string next_page_token = 2; + + // The list of unreachable instance partitions. + // It includes the names of instance partitions whose metadata could + // not be retrieved within + // [instance_partition_deadline][google.spanner.admin.instance.v1.ListInstancePartitionsRequest.instance_partition_deadline]. + repeated string unreachable = 3; +} + +// The request for +// [ListInstancePartitionOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitionOperations]. +message ListInstancePartitionOperationsRequest { + // Required. The parent instance of the instance partition operations. + // Values are of the form `projects//instances/`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Instance" + } + ]; + + // Optional. 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: `<`, `>`, `<=`, `>=`, `!=`, `=`, or `:`. + // Colon `:` is the contains operator. Filter rules are not case sensitive. + // + // The following fields in the [Operation][google.longrunning.Operation] + // are eligible for filtering: + // + // * `name` - The name of the long-running operation + // * `done` - False if the operation is in progress, else true. + // * `metadata.@type` - the type of metadata. For example, the type string + // for + // [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata] + // is + // `type.googleapis.com/google.spanner.admin.instance.v1.CreateInstancePartitionMetadata`. + // * `metadata.` - any field in metadata.value. + // `metadata.@type` must be specified first, if filtering on metadata + // fields. + // * `error` - Error associated with the long-running operation. + // * `response.@type` - the type of response. + // * `response.` - any field in response.value. + // + // 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: + // + // * `done:true` - The operation is complete. + // * `(metadata.@type=` \ + // `type.googleapis.com/google.spanner.admin.instance.v1.CreateInstancePartitionMetadata) + // AND` \ + // `(metadata.instance_partition.name:custom-instance-partition) AND` \ + // `(metadata.start_time < \"2021-03-28T14:50:00Z\") AND` \ + // `(error:*)` - Return operations where: + // * The operation's metadata type is + // [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata]. + // * The instance partition name contains "custom-instance-partition". + // * The operation started before 2021-03-28T14:50:00Z. + // * The operation resulted in an error. + string filter = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Number of operations to be returned in the response. If 0 or + // less, defaults to the server's maximum allowed page size. + int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If non-empty, `page_token` should contain a + // [next_page_token][google.spanner.admin.instance.v1.ListInstancePartitionOperationsResponse.next_page_token] + // from a previous + // [ListInstancePartitionOperationsResponse][google.spanner.admin.instance.v1.ListInstancePartitionOperationsResponse] + // to the same `parent` and with the same `filter`. + string page_token = 4 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Deadline used while retrieving metadata for instance partition + // operations. Instance partitions whose operation metadata cannot be + // retrieved within this deadline will be added to + // [unreachable][ListInstancePartitionOperationsResponse.unreachable] in + // [ListInstancePartitionOperationsResponse][google.spanner.admin.instance.v1.ListInstancePartitionOperationsResponse]. + google.protobuf.Timestamp instance_partition_deadline = 5 + [(google.api.field_behavior) = OPTIONAL]; +} + +// The response for +// [ListInstancePartitionOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitionOperations]. +message ListInstancePartitionOperationsResponse { + // The list of matching instance partition [long-running + // operations][google.longrunning.Operation]. Each operation's name will be + // prefixed by the instance partition's name. The operation's + // [metadata][google.longrunning.Operation.metadata] field type + // `metadata.type_url` describes the type of the metadata. + repeated google.longrunning.Operation operations = 1; + + // `next_page_token` can be sent in a subsequent + // [ListInstancePartitionOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitionOperations] + // call to fetch more of the matching metadata. + string next_page_token = 2; + + // The list of unreachable instance partitions. + // It includes the names of instance partitions whose operation metadata could + // not be retrieved within + // [instance_partition_deadline][google.spanner.admin.instance.v1.ListInstancePartitionOperationsRequest.instance_partition_deadline]. + repeated string unreachable_instance_partitions = 3; +}