From 5440048987f623ea4c77ee2aea872c709eb7619b Mon Sep 17 00:00:00 2001 From: Google APIs Date: Mon, 12 Sep 2022 22:31:06 -0700 Subject: [PATCH] feat: Add custom instance config operations PiperOrigin-RevId: 473928081 --- google/spanner/admin/database/v1/BUILD.bazel | 6 + google/spanner/admin/instance/v1/BUILD.bazel | 3 + .../instance/v1/spanner_instance_admin.proto | 543 ++++++++++++++++-- 3 files changed, 511 insertions(+), 41 deletions(-) diff --git a/google/spanner/admin/database/v1/BUILD.bazel b/google/spanner/admin/database/v1/BUILD.bazel index 03448615d5f9e..8a4666860c4bf 100644 --- a/google/spanner/admin/database/v1/BUILD.bazel +++ b/google/spanner/admin/database/v1/BUILD.bazel @@ -173,6 +173,7 @@ load( "@com_google_googleapis_imports//:imports.bzl", "py_gapic_assembly_pkg", "py_gapic_library", + "py_proto_library", "py_test", ) @@ -207,6 +208,11 @@ py_gapic_assembly_pkg( ], ) +py_proto_library( + name = "database_py_proto", + deps = [":database_proto"], +) + ############################################################################## # PHP ############################################################################## diff --git a/google/spanner/admin/instance/v1/BUILD.bazel b/google/spanner/admin/instance/v1/BUILD.bazel index 462a1df38c676..f9a77aee7246e 100644 --- a/google/spanner/admin/instance/v1/BUILD.bazel +++ b/google/spanner/admin/instance/v1/BUILD.bazel @@ -22,6 +22,7 @@ proto_library( "//google/iam/v1:iam_policy_proto", "//google/iam/v1:policy_proto", "//google/longrunning:operations_proto", + "//google/spanner/admin/database/v1:database_proto", "@com_google_protobuf//:empty_proto", "@com_google_protobuf//:field_mask_proto", "@com_google_protobuf//:timestamp_proto", @@ -116,6 +117,7 @@ go_proto_library( "//google/api:annotations_go_proto", "//google/iam/v1:iam_go_proto", "//google/longrunning:longrunning_go_proto", + "//google/spanner/admin/database/v1:database_go_proto", ], ) @@ -172,6 +174,7 @@ py_gapic_library( ], deps = [ "//google/iam/v1:iam_policy_py_proto", + "//google/spanner/admin/database/v1:database_py_proto", ], ) diff --git a/google/spanner/admin/instance/v1/spanner_instance_admin.proto b/google/spanner/admin/instance/v1/spanner_instance_admin.proto index 3bde51d99d510..19e446544ade3 100644 --- a/google/spanner/admin/instance/v1/spanner_instance_admin.proto +++ b/google/spanner/admin/instance/v1/spanner_instance_admin.proto @@ -26,6 +26,7 @@ import "google/longrunning/operations.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/field_mask.proto"; import "google/protobuf/timestamp.proto"; +import "google/spanner/admin/database/v1/common.proto"; option csharp_namespace = "Google.Cloud.Spanner.Admin.Instance.V1"; option go_package = "google.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance"; @@ -63,7 +64,8 @@ service InstanceAdmin { "https://www.googleapis.com/auth/spanner.admin"; // Lists the supported instance configurations for a given project. - rpc ListInstanceConfigs(ListInstanceConfigsRequest) returns (ListInstanceConfigsResponse) { + rpc ListInstanceConfigs(ListInstanceConfigsRequest) + returns (ListInstanceConfigsResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*}/instanceConfigs" }; @@ -78,6 +80,153 @@ service InstanceAdmin { option (google.api.method_signature) = "name"; } + // Creates an instance config 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 config. The instance config name is assigned by the caller. If the + // named instance config already exists, `CreateInstanceConfig` returns + // `ALREADY_EXISTS`. + // + // Immediately after the request returns: + // + // * The instance config is readable via the API, with all requested + // attributes. The instance config's + // [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + // field is set to true. Its state is `CREATING`. + // + // While the operation is pending: + // + // * Cancelling the operation renders the instance config immediately + // unreadable via the API. + // * Except for deleting the creating resource, all other attempts to modify + // the instance config are rejected. + // + // Upon completion of the returned operation: + // + // * Instances can be created using the instance configuration. + // * The instance config's + // [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + // field becomes false. Its 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 config. The + // [metadata][google.longrunning.Operation.metadata] field type is + // [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata]. + // The [response][google.longrunning.Operation.response] field type is + // [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig], if + // successful. + // + // Authorization requires `spanner.instanceConfigs.create` permission on + // the resource + // [parent][google.spanner.admin.instance.v1.CreateInstanceConfigRequest.parent]. + rpc CreateInstanceConfig(CreateInstanceConfigRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=projects/*}/instanceConfigs" + body: "*" + }; + option (google.api.method_signature) = + "parent,instance_config,instance_config_id"; + option (google.longrunning.operation_info) = { + response_type: "google.spanner.admin.instance.v1.InstanceConfig" + metadata_type: "google.spanner.admin.instance.v1.CreateInstanceConfigMetadata" + }; + } + + // Updates an instance config. The returned + // [long-running operation][google.longrunning.Operation] can be used to track + // the progress of updating the instance. If the named instance config does + // not exist, returns `NOT_FOUND`. + // + // Only user managed configurations can be updated. + // + // Immediately after the request returns: + // + // * The instance config's + // [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + // field is set to true. + // + // While the operation is pending: + // + // * Cancelling the operation sets its metadata's + // [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.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 config are rejected. + // * Reading the instance config 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 instance config's new values are readable via the API. + // * The instance config's + // [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + // field becomes false. + // + // The returned [long-running operation][google.longrunning.Operation] will + // have a name of the format + // `/operations/` and can be used to track + // the instance config modification. The + // [metadata][google.longrunning.Operation.metadata] field type is + // [UpdateInstanceConfigMetadata][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata]. + // The [response][google.longrunning.Operation.response] field type is + // [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig], if + // successful. + // + // Authorization requires `spanner.instanceConfigs.update` permission on + // the resource [name][google.spanner.admin.instance.v1.InstanceConfig.name]. + rpc UpdateInstanceConfig(UpdateInstanceConfigRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + patch: "/v1/{instance_config.name=projects/*/instanceConfigs/*}" + body: "*" + }; + option (google.api.method_signature) = "instance_config,update_mask"; + option (google.longrunning.operation_info) = { + response_type: "google.spanner.admin.instance.v1.InstanceConfig" + metadata_type: "google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata" + }; + } + + // Deletes the instance config. Deletion is only allowed when no + // instances are using the configuration. If any instances are using + // the config, returns `FAILED_PRECONDITION`. + // + // Only user managed configurations can be deleted. + // + // Authorization requires `spanner.instanceConfigs.delete` permission on + // the resource [name][google.spanner.admin.instance.v1.InstanceConfig.name]. + rpc DeleteInstanceConfig(DeleteInstanceConfigRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/instanceConfigs/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Lists the user-managed instance config [long-running + // operations][google.longrunning.Operation] in the given project. An instance + // config operation has a name of the form + // `projects//instanceConfigs//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. + rpc ListInstanceConfigOperations(ListInstanceConfigOperationsRequest) + returns (ListInstanceConfigOperationsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*}/instanceConfigOperations" + }; + option (google.api.method_signature) = "parent"; + } + // Lists all instances in the given project. rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) { option (google.api.http) = { @@ -128,7 +277,8 @@ service InstanceAdmin { // [CreateInstanceMetadata][google.spanner.admin.instance.v1.CreateInstanceMetadata]. // The [response][google.longrunning.Operation.response] field type is // [Instance][google.spanner.admin.instance.v1.Instance], if successful. - rpc CreateInstance(CreateInstanceRequest) returns (google.longrunning.Operation) { + rpc CreateInstance(CreateInstanceRequest) + returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/{parent=projects/*}/instances" body: "*" @@ -154,9 +304,9 @@ service InstanceAdmin { // Until completion of the returned operation: // // * Cancelling the operation sets its metadata's - // [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], and begins - // restoring resources to their pre-request values. The operation - // is guaranteed to succeed at undoing all resource changes, + // [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.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 are rejected. // * Reading the instance via the API continues to give the pre-request @@ -180,7 +330,8 @@ service InstanceAdmin { // // Authorization requires `spanner.instances.update` permission on // the resource [name][google.spanner.admin.instance.v1.Instance.name]. - rpc UpdateInstance(UpdateInstanceRequest) returns (google.longrunning.Operation) { + rpc UpdateInstance(UpdateInstanceRequest) + returns (google.longrunning.Operation) { option (google.api.http) = { patch: "/v1/{instance.name=projects/*/instances/*}" body: "*" @@ -215,7 +366,8 @@ service InstanceAdmin { // // Authorization requires `spanner.instances.setIamPolicy` on // [resource][google.iam.v1.SetIamPolicyRequest.resource]. - rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) + returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:setIamPolicy" body: "*" @@ -228,7 +380,8 @@ service InstanceAdmin { // // Authorization requires `spanner.instances.getIamPolicy` on // [resource][google.iam.v1.GetIamPolicyRequest.resource]. - rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) + returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:getIamPolicy" body: "*" @@ -242,7 +395,8 @@ service InstanceAdmin { // result in a NOT_FOUND error if the user has `spanner.instances.list` // permission on the containing Google Cloud Project. Otherwise returns an // empty set of permissions. - rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) + returns (google.iam.v1.TestIamPermissionsResponse) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:testIamPermissions" body: "*" @@ -307,6 +461,31 @@ message InstanceConfig { pattern: "projects/{project}/instanceConfigs/{instance_config}" }; + // The type of this configuration. + enum Type { + // Unspecified. + TYPE_UNSPECIFIED = 0; + + // Google managed configuration. + GOOGLE_MANAGED = 1; + + // User managed configuration. + USER_MANAGED = 2; + } + + // Indicates the current state of the instance config. + enum State { + // Not specified. + STATE_UNSPECIFIED = 0; + + // The instance config is still being created. + CREATING = 1; + + // The instance config is fully created and ready to be used to create + // instances. + READY = 2; + } + // A unique identifier for the instance configuration. Values // are of the form // `projects//instanceConfigs/[a-z][-a-z0-9]*`. @@ -315,13 +494,72 @@ message InstanceConfig { // The name of this instance configuration as it appears in UIs. string display_name = 2; + // Output only. Whether this instance config is a Google or User Managed + // Configuration. + Type config_type = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; + // The geographic placement of nodes in this instance configuration and their // replication properties. repeated ReplicaInfo replicas = 3; + // Output only. The available optional replicas to choose from for user + // managed configurations. Populated for Google managed configurations. + repeated ReplicaInfo optional_replicas = 6 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // 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. + string base_config = 7 [(google.api.resource_reference) = { + type: "spanner.googleapis.com/InstanceConfig" + }]; + + // 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][a-z0-9_-]{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. + map labels = 8; + + // 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. + string etag = 9; + // Allowed values of the "default_leader" schema option for databases in // instances that use this instance configuration. repeated string leader_options = 4; + + // Output only. If true, the instance config is being created or updated. If + // false, there are no ongoing operations for the instance config. + bool reconciling = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The current instance config state. + State state = 11 [(google.api.field_behavior) = OUTPUT_ONLY]; } // An isolated set of Cloud Spanner resources on which databases can be hosted. @@ -387,10 +625,10 @@ message Instance { int32 processing_units = 9; // Output only. The current instance state. For - // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance], the state must be - // either omitted or set to `CREATING`. For - // [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance], the state must be - // either omitted or set to `READY`. + // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance], + // the state must be either omitted or set to `CREATING`. For + // [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance], + // the state must be either omitted or set to `READY`. State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; // Cloud Labels are a flexible and lightweight mechanism for organizing cloud @@ -420,13 +658,16 @@ message Instance { repeated string endpoint_uris = 8; // Output only. The time at which the instance was created. - google.protobuf.Timestamp create_time = 11 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp create_time = 11 + [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. The time at which the instance was most recently updated. - google.protobuf.Timestamp update_time = 12 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp update_time = 12 + [(google.api.field_behavior) = OUTPUT_ONLY]; } -// The request for [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. +// The request for +// [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. message ListInstanceConfigsRequest { // Required. The name of the project for which a list of supported instance // configurations is requested. Values are of the form @@ -444,18 +685,20 @@ message ListInstanceConfigsRequest { // If non-empty, `page_token` should contain a // [next_page_token][google.spanner.admin.instance.v1.ListInstanceConfigsResponse.next_page_token] - // from a previous [ListInstanceConfigsResponse][google.spanner.admin.instance.v1.ListInstanceConfigsResponse]. + // from a previous + // [ListInstanceConfigsResponse][google.spanner.admin.instance.v1.ListInstanceConfigsResponse]. string page_token = 3; } -// The response for [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. +// The response for +// [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. message ListInstanceConfigsResponse { // The list of requested instance configurations. repeated InstanceConfig instance_configs = 1; // `next_page_token` can be sent in a subsequent - // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs] call to - // fetch more of the matching instance configurations. + // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs] + // call to fetch more of the matching instance configurations. string next_page_token = 2; } @@ -472,7 +715,175 @@ message GetInstanceConfigRequest { ]; } -// The request for [GetInstance][google.spanner.admin.instance.v1.InstanceAdmin.GetInstance]. +// The request for +// [CreateInstanceConfigRequest][InstanceAdmin.CreateInstanceConfigRequest]. +message CreateInstanceConfigRequest { + // Required. The name of the project in which to create the instance config. + // Values are of the form `projects/`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "cloudresourcemanager.googleapis.com/Project" + } + ]; + + // Required. The ID of the instance config 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. + string instance_config_id = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. The InstanceConfig proto of the configuration to create. + // instance_config.name must be + // `/instanceConfigs/`. + // instance_config.base_config must be a Google managed configuration name, + // e.g. /instanceConfigs/us-east1, /instanceConfigs/nam3. + InstanceConfig instance_config = 3 [(google.api.field_behavior) = REQUIRED]; + + // An option to validate, but not actually execute, a request, + // and provide the same response. + bool validate_only = 4; +} + +// The request for +// [UpdateInstanceConfigRequest][InstanceAdmin.UpdateInstanceConfigRequest]. +message UpdateInstanceConfigRequest { + // Required. The user instance config to update, which must always include the + // instance config name. Otherwise, only fields mentioned in + // [update_mask][google.spanner.admin.instance.v1.UpdateInstanceConfigRequest.update_mask] + // need be included. To prevent conflicts of concurrent updates, + // [etag][google.spanner.admin.instance.v1.InstanceConfig.reconciling] can + // be used. + InstanceConfig instance_config = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. A mask specifying which fields in + // [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig] should be + // updated. 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. Only + // display_name and labels can be updated. + google.protobuf.FieldMask update_mask = 2 + [(google.api.field_behavior) = REQUIRED]; + + // An option to validate, but not actually execute, a request, + // and provide the same response. + bool validate_only = 3; +} + +// The request for +// [DeleteInstanceConfigRequest][InstanceAdmin.DeleteInstanceConfigRequest]. +message DeleteInstanceConfigRequest { + // Required. The name of the instance configuration to be deleted. + // Values are of the form + // `projects//instanceConfigs/` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/InstanceConfig" + } + ]; + + // 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. + string etag = 2; + + // An option to validate, but not actually execute, a request, + // and provide the same response. + bool validate_only = 3; +} + +// The request for +// [ListInstanceConfigOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigOperations]. +message ListInstanceConfigOperationsRequest { + // Required. The project of the instance config operations. + // Values are of the form `projects/`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "cloudresourcemanager.googleapis.com/Project" + } + ]; + + // 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 + // [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata] + // is + // `type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceConfigMetadata`. + // * `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.CreateInstanceConfigMetadata) + // AND` \ + // `(metadata.instance_config.name:custom-config) AND` \ + // `(metadata.progress.start_time < \"2021-03-28T14:50:00Z\") AND` \ + // `(error:*)` - Return operations where: + // * The operation's metadata type is + // [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata]. + // * The instance config name contains "custom-config". + // * The operation started before 2021-03-28T14:50:00Z. + // * The operation resulted in an error. + string filter = 2; + + // 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; + + // If non-empty, `page_token` should contain a + // [next_page_token][google.spanner.admin.instance.v1.ListInstanceConfigOperationsResponse.next_page_token] + // from a previous + // [ListInstanceConfigOperationsResponse][google.spanner.admin.instance.v1.ListInstanceConfigOperationsResponse] + // to the same `parent` and with the same `filter`. + string page_token = 4; +} + +// The response for +// [ListInstanceConfigOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigOperations]. +message ListInstanceConfigOperationsResponse { + // The list of matching instance config [long-running + // operations][google.longrunning.Operation]. Each operation's name will be + // prefixed by the instance config'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 + // [ListInstanceConfigOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigOperations] + // call to fetch more of the matching metadata. + string next_page_token = 2; +} + +// The request for +// [GetInstance][google.spanner.admin.instance.v1.InstanceAdmin.GetInstance]. message GetInstanceRequest { // Required. The name of the requested instance. Values are of the form // `projects//instances/`. @@ -483,13 +894,15 @@ message GetInstanceRequest { } ]; - // If field_mask is present, specifies the subset of [Instance][google.spanner.admin.instance.v1.Instance] fields that - // should be returned. - // If absent, all [Instance][google.spanner.admin.instance.v1.Instance] fields are returned. + // If field_mask is present, specifies the subset of + // [Instance][google.spanner.admin.instance.v1.Instance] fields that should be + // returned. If absent, all + // [Instance][google.spanner.admin.instance.v1.Instance] fields are returned. google.protobuf.FieldMask field_mask = 2; } -// The request for [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance]. +// The request for +// [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance]. message CreateInstanceRequest { // Required. The name of the project in which to create the instance. Values // are of the form `projects/`. @@ -510,7 +923,8 @@ message CreateInstanceRequest { Instance instance = 3 [(google.api.field_behavior) = REQUIRED]; } -// The request for [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. +// The request for +// [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. message ListInstancesRequest { // Required. The name of the project for which a list of instances is // requested. Values are of the form `projects/`. @@ -526,8 +940,9 @@ message ListInstancesRequest { int32 page_size = 2; // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.admin.instance.v1.ListInstancesResponse.next_page_token] from a - // previous [ListInstancesResponse][google.spanner.admin.instance.v1.ListInstancesResponse]. + // [next_page_token][google.spanner.admin.instance.v1.ListInstancesResponse.next_page_token] + // from a previous + // [ListInstancesResponse][google.spanner.admin.instance.v1.ListInstancesResponse]. string page_token = 3; // An expression for filtering the results of the request. Filter rules are @@ -550,33 +965,48 @@ 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 [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. +// The response for +// [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. message ListInstancesResponse { // The list of requested instances. repeated Instance instances = 1; // `next_page_token` can be sent in a subsequent - // [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances] call to fetch more - // of the matching instances. + // [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances] + // call to fetch more of the matching instances. string next_page_token = 2; } -// The request for [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance]. +// The request for +// [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance]. message UpdateInstanceRequest { // Required. The instance to update, which must always include the instance - // name. Otherwise, only fields mentioned in [field_mask][google.spanner.admin.instance.v1.UpdateInstanceRequest.field_mask] need be included. + // name. Otherwise, only fields mentioned in + // [field_mask][google.spanner.admin.instance.v1.UpdateInstanceRequest.field_mask] + // need be included. Instance instance = 1 [(google.api.field_behavior) = REQUIRED]; - // Required. A mask specifying which fields in [Instance][google.spanner.admin.instance.v1.Instance] should be updated. + // Required. A mask specifying which fields in + // [Instance][google.spanner.admin.instance.v1.Instance] should be updated. // The field mask must always be specified; this prevents any future fields in - // [Instance][google.spanner.admin.instance.v1.Instance] from being erased accidentally by clients that do not know - // about them. - google.protobuf.FieldMask field_mask = 2 [(google.api.field_behavior) = REQUIRED]; + // [Instance][google.spanner.admin.instance.v1.Instance] from being erased + // accidentally by clients that do not know about them. + google.protobuf.FieldMask field_mask = 2 + [(google.api.field_behavior) = REQUIRED]; } -// The request for [DeleteInstance][google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstance]. +// The request for +// [DeleteInstance][google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstance]. message DeleteInstanceRequest { // Required. The name of the instance to be deleted. Values are of the form // `projects//instances/` @@ -595,8 +1025,8 @@ message CreateInstanceMetadata { Instance instance = 1; // The time at which the - // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance] request was - // received. + // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance] + // request was received. google.protobuf.Timestamp start_time = 2; // The time at which this operation was cancelled. If set, this operation is @@ -614,7 +1044,8 @@ message UpdateInstanceMetadata { // The desired end state of the update. Instance instance = 1; - // The time at which [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance] + // The time at which + // [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance] // request was received. google.protobuf.Timestamp start_time = 2; @@ -626,3 +1057,33 @@ message UpdateInstanceMetadata { // The time at which this operation failed or was completed successfully. google.protobuf.Timestamp end_time = 4; } + +// Metadata type for the operation returned by +// [CreateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstanceConfig]. +message CreateInstanceConfigMetadata { + // The target instance config end state. + InstanceConfig instance_config = 1; + + // The progress of the + // [CreateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstanceConfig] + // operation. + google.spanner.admin.database.v1.OperationProgress progress = 2; + + // The time at which this operation was cancelled. + google.protobuf.Timestamp cancel_time = 3; +} + +// Metadata type for the operation returned by +// [UpdateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstanceConfig]. +message UpdateInstanceConfigMetadata { + // The desired instance config after updating. + InstanceConfig instance_config = 1; + + // The progress of the + // [UpdateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstanceConfig] + // operation. + google.spanner.admin.database.v1.OperationProgress progress = 2; + + // The time at which this operation was cancelled. + google.protobuf.Timestamp cancel_time = 3; +}