diff options
Diffstat (limited to 'third_party/googleapis/google/spanner/admin/instance/v1/spanner_instance_admin.proto')
| -rw-r--r-- | third_party/googleapis/google/spanner/admin/instance/v1/spanner_instance_admin.proto | 446 |
1 files changed, 446 insertions, 0 deletions
diff --git a/third_party/googleapis/google/spanner/admin/instance/v1/spanner_instance_admin.proto b/third_party/googleapis/google/spanner/admin/instance/v1/spanner_instance_admin.proto new file mode 100644 index 0000000000..d85d781e63 --- /dev/null +++ b/third_party/googleapis/google/spanner/admin/instance/v1/spanner_instance_admin.proto @@ -0,0 +1,446 @@ +// Copyright 2017 Google Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.spanner.admin.instance.v1; + +import "google/api/annotations.proto"; +import "google/api/auth.proto"; +import "google/iam/v1/iam_policy.proto"; +import "google/iam/v1/policy.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Spanner.Admin.Instance.V1"; +option go_package = "google.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance"; +option java_multiple_files = true; +option java_outer_classname = "SpannerInstanceAdminProto"; +option java_package = "com.google.spanner.admin.instance.v1"; + + +// 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. +service InstanceAdmin { + // Lists the supported instance configurations for a given project. + rpc ListInstanceConfigs(ListInstanceConfigsRequest) returns (ListInstanceConfigsResponse) { + option (google.api.http) = { get: "/v1/{parent=projects/*}/instanceConfigs" }; + } + + // Gets information about a particular instance configuration. + rpc GetInstanceConfig(GetInstanceConfigRequest) returns (InstanceConfig) { + option (google.api.http) = { get: "/v1/{name=projects/*/instanceConfigs/*}" }; + } + + // Lists all instances in the given project. + rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) { + option (google.api.http) = { get: "/v1/{parent=projects/*}/instances" }; + } + + // Gets information about a particular instance. + rpc GetInstance(GetInstanceRequest) returns (Instance) { + option (google.api.http) = { get: "/v1/{name=projects/*/instances/*}" }; + } + + // Creates an instance and begins preparing it to begin serving. The + // returned [long-running operation][google.longrunning.Operation] + // can be used to track the progress of preparing the new + // instance. The instance name is assigned by the caller. If the + // named instance already exists, `CreateInstance` returns + // `ALREADY_EXISTS`. + // + // Immediately upon completion of this request: + // + // * The instance 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 immediately unreadable + // via the API. + // * The instance can be deleted. + // * All other attempts to modify the instance 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 be created in the instance. + // * The instance's allocated resource levels are readable via the API. + // * The instance's state becomes `READY`. + // + // The returned [long-running operation][google.longrunning.Operation] will + // have a name of the format `<instance_name>/operations/<operation_id>` and + // can be used to track creation of the instance. The + // [metadata][google.longrunning.Operation.metadata] field type is + // [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) { + option (google.api.http) = { post: "/v1/{parent=projects/*}/instances" body: "*" }; + } + + // Updates an instance, 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. If the named instance does not + // exist, returns `NOT_FOUND`. + // + // Immediately upon completion of this request: + // + // * For resource types for which a decrease in the instance'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.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 + // 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's + // tables. + // * The instance's new resource levels are readable via the API. + // + // The returned [long-running operation][google.longrunning.Operation] will + // have a name of the format `<instance_name>/operations/<operation_id>` and + // can be used to track the instance modification. The + // [metadata][google.longrunning.Operation.metadata] field type is + // [UpdateInstanceMetadata][google.spanner.admin.instance.v1.UpdateInstanceMetadata]. + // The [response][google.longrunning.Operation.response] field type is + // [Instance][google.spanner.admin.instance.v1.Instance], if successful. + // + // Authorization requires `spanner.instances.update` permission on + // resource [name][google.spanner.admin.instance.v1.Instance.name]. + rpc UpdateInstance(UpdateInstanceRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { patch: "/v1/{instance.name=projects/*/instances/*}" body: "*" }; + } + + // Deletes an instance. + // + // Immediately upon completion of the request: + // + // * Billing ceases for all of the instance's reserved resources. + // + // Soon afterward: + // + // * The instance and *all of its databases* immediately and + // irrevocably disappear from the API. All data in the databases + // is permanently deleted. + rpc DeleteInstance(DeleteInstanceRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { delete: "/v1/{name=projects/*/instances/*}" }; + } + + // Sets the access control policy on an instance resource. Replaces any + // existing policy. + // + // Authorization requires `spanner.instances.setIamPolicy` on + // [resource][google.iam.v1.SetIamPolicyRequest.resource]. + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { + option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:setIamPolicy" body: "*" }; + } + + // 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 `spanner.instances.getIamPolicy` on + // [resource][google.iam.v1.GetIamPolicyRequest.resource]. + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { + option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:getIamPolicy" body: "*" }; + } + + // 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 `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) { + option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:testIamPermissions" body: "*" }; + } +} + +// A possible configuration for a Cloud Spanner instance. Configurations +// define the geographic placement of nodes and their replication. +message InstanceConfig { + // A unique identifier for the instance configuration. Values + // are of the form + // `projects/<project>/instanceConfigs/[a-z][-a-z0-9]*` + string name = 1; + + // The name of this instance configuration as it appears in UIs. + string display_name = 2; +} + +// An isolated set of Cloud Spanner resources on which databases can be hosted. +message Instance { + // Indicates the current state of the instance. + enum State { + // Not specified. + STATE_UNSPECIFIED = 0; + + // The instance is still being created. Resources may not be + // available yet, and operations such as database creation may not + // work. + CREATING = 1; + + // The instance is fully created and ready to do work such as + // creating databases. + READY = 2; + } + + // Required. A unique identifier for the instance, which cannot be changed + // after the instance is created. Values are of the form + // `projects/<project>/instances/[a-z][-a-z0-9]*[a-z0-9]`. The final + // segment of the name must be between 6 and 30 characters in length. + string name = 1; + + // Required. The name of the instance's configuration. Values are of the form + // `projects/<project>/instanceConfigs/<configuration>`. See + // also [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig] and + // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. + string config = 2; + + // 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. + string display_name = 3; + + // Required. The number of nodes allocated to this instance. + int32 node_count = 5; + + // 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`. + State state = 6; + + // 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]*[a-z0-9])?`. + // * Label values must be between 0 and 63 characters long and must conform + // to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`. + // * 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. 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. + map<string, string> labels = 7; +} + +// 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 + // `projects/<project>`. + string parent = 1; + + // Number of instance configurations 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.ListInstanceConfigsResponse.next_page_token] + // 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]. +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. + string next_page_token = 2; +} + +// The request for +// [GetInstanceConfigRequest][google.spanner.admin.instance.v1.InstanceAdmin.GetInstanceConfig]. +message GetInstanceConfigRequest { + // Required. The name of the requested instance configuration. Values are of + // the form `projects/<project>/instanceConfigs/<config>`. + string name = 1; +} + +// 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/<project>/instances/<instance>`. + string name = 1; +} + +// 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/<project>`. + string parent = 1; + + // Required. The ID of the instance to create. Valid identifiers are of the + // form `[a-z][-a-z0-9]*[a-z0-9]` and must be between 6 and 30 characters in + // length. + string instance_id = 2; + + // Required. The instance to create. The name may be omitted, but if + // specified must be `<parent>/instances/<instance_id>`. + Instance instance = 3; +} + +// 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/<project>`. + string parent = 1; + + // Number of instances 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.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 + // case insensitive. The fields eligible for filtering are: + // + // * name + // * display_name + // * labels.key where key is the name of a label + // + // Some examples of using filters are: + // + // * name:* --> The instance has a name. + // * name:Howl --> The instance's name contains the string "howl". + // * name:HOWL --> Equivalent to above. + // * NAME:howl --> Equivalent to above. + // * labels.env:* --> The instance has the label "env". + // * labels.env:dev --> The instance has the label "env" and the value of + // the label contains the string "dev". + // * name:howl labels.env:dev --> The instance's name contains "howl" and + // it has the label "env" with its value + // containing "dev". + string filter = 4; +} + +// 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. + string next_page_token = 2; +} + +// 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 [][google.spanner.admin.instance.v1.UpdateInstanceRequest.field_mask] need be included. + Instance instance = 1; + + // Required. A mask specifying which fields in [][google.spanner.admin.instance.v1.UpdateInstanceRequest.instance] should be updated. + // The field mask must always be specified; this prevents any future fields in + // [][google.spanner.admin.instance.v1.Instance] from being erased accidentally by clients that do not know + // about them. + google.protobuf.FieldMask field_mask = 2; +} + +// 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/<project>/instances/<instance>` + string name = 1; +} + +// Metadata type for the operation returned by +// [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance]. +message CreateInstanceMetadata { + // The instance being created. + Instance instance = 1; + + // The time at which the + // [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 + // 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; +} + +// Metadata type for the operation returned by +// [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance]. +message UpdateInstanceMetadata { + // The desired end state of the update. + Instance instance = 1; + + // The time at which [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance] + // 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; +} |