From 83e1f25c54a7049b15eee34200d035ecfe9460d7 Mon Sep 17 00:00:00 2001 From: Rajat Bhatta Date: Thu, 24 Mar 2022 06:08:33 +0000 Subject: [PATCH] feat: add proto file as reference. --- .../instance/v1/spanner_instance_admin.proto | 443 +++++++++++++++++- 1 file changed, 442 insertions(+), 1 deletion(-) diff --git a/proto-google-cloud-spanner-admin-instance-v1/src/main/proto/google/spanner/admin/instance/v1/spanner_instance_admin.proto b/proto-google-cloud-spanner-admin-instance-v1/src/main/proto/google/spanner/admin/instance/v1/spanner_instance_admin.proto index 0e6bf63feb0..be28d3d7d53 100644 --- a/proto-google-cloud-spanner-admin-instance-v1/src/main/proto/google/spanner/admin/instance/v1/spanner_instance_admin.proto +++ b/proto-google-cloud-spanner-admin-instance-v1/src/main/proto/google/spanner/admin/instance/v1/spanner_instance_admin.proto @@ -78,6 +78,152 @@ 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][CreateInstanceConfigRequest.parent]. + rpc CreateInstanceConfig(CreateInstanceConfigRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=projects/*}/instanceConfigs" + body: "instance_config" + }; + option (google.api.method_signature) = + "parent,instance_config,instance_config_id"; + option (google.longrunning.operation_info) = { + response_type: "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][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: "instance_config" + }; + option (google.api.method_signature) = "instance_config,update_mask"; + option (google.longrunning.operation_info) = { + response_type: "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) = { @@ -315,13 +461,107 @@ message InstanceConfig { // The name of this instance configuration as it appears in UIs. string display_name = 2; + // The type of this configuration. + enum Type { + // Unspecified. + TYPE_UNSPECIFIED = 0; + // Google managed configuration. + GOOGLE_MANAGED = 1; + // User managed configuration. + USER_MANAGED = 2; + } + // 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. + // (-- TODO(b/193081755): 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`. --) repeated ReplicaInfo replicas = 3; - // Allowed values of the “default_leader” schema option for databases in + // 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. + 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; + + // 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 + ]; + + // 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. + // (-- api-linter: core::0216::value-synonyms=disabled + // aip.dev/not-precedent: To be consistent with Instance State. --) + READY = 2; + } + + // 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. @@ -460,6 +700,176 @@ message GetInstanceConfigRequest { ]; } +// The request for +// [CreateInstanceConfigRequest][InstanceAdmin.CreateInstanceConfigRequest]. +message CreateInstanceConfigRequest { + // 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" + ]; + + // 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 + ]; + + // The InstanceConfig proto of the configuration to create. + // instance_config.name must be + // `/instanceConfigs/`. + // instance_config.base_config must be a Google managed configuration id, e.g. + // us-east1, 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 { + // The user instance config to update, which must always include the instance + // config name. Otherwise, only fields mentioned in [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 + ]; + + // 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 { + // 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][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][] is + // `type.googleapis.com/google.spanner.admin.database.v1.CreateInstanceConfigMetadata`. + // * `metadata.` - any field in metadata.value. + // * `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][]. + // * 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][ListInstanceConfigOperationsResponse.next_page_token] + // from a previous [ListInstanceConfigOperationsResponse][] to the + // same `parent` and with the same `filter`. + string page_token = 4; +} + +// The response for +// [ListInstanceConfigOperations][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. + // (-- go/not-api-precedent: It is not generally recommended to return + // google.longrunning.Operation objects in a list because it requires + // custom code from client libraries in every language. --) + // (-- api-linter: core::0132::response-unknown-fields=disabled + // aip.dev/not-precedent: This is the correct field type. --) + repeated google.longrunning.Operation operations = 1; + + // `next_page_token` can be sent in a subsequent + // [ListInstanceConfigOperations][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 @@ -614,3 +1024,34 @@ 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 time at which + // [CreateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstanceConfig] request was + // received. + google.protobuf.Timestamp start_time = 2; + // The time at which this operation was cancelled. + google.protobuf.Timestamp cancel_time = 3; + // The time at which this operation failed or was completed successfully. + google.protobuf.Timestamp end_time = 4; +} + +// 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 time at which + // [UpdateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstanceConfig] request was + // received. + google.protobuf.Timestamp start_time = 2; + // The time at which this operation was cancelled. + google.protobuf.Timestamp cancel_time = 3; + // The time at which this operation failed or was completed successfully. + google.protobuf.Timestamp end_time = 4; +}