xref: /aosp_15_r20/external/googleapis/google/spanner/admin/instance/v1/spanner_instance_admin.proto (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9)

// 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.
// 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/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.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";
import "google/spanner/admin/instance/v1/common.proto";

option csharp_namespace = "Google.Cloud.Spanner.Admin.Instance.V1";
option go_package = "cloud.google.com/go/spanner/admin/instance/apiv1/instancepb;instancepb";
option java_multiple_files = true;
option java_outer_classname = "SpannerInstanceAdminProto";
option java_package = "com.google.spanner.admin.instance.v1";
option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Instance\\V1";
option ruby_package = "Google::Cloud::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 {
  option (google.api.default_host) = "spanner.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/spanner.admin";

  // Lists the supported instance configurations for a given project.
  rpc ListInstanceConfigs(ListInstanceConfigsRequest)
      returns (ListInstanceConfigsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=projects/*}/instanceConfigs"
    };
    option (google.api.method_signature) = "parent";
  }

  // Gets information about a particular instance configuration.
  rpc GetInstanceConfig(GetInstanceConfigRequest) returns (InstanceConfig) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/instanceConfigs/*}"
    };
    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
  // `<instance_config_name>/operations/<operation_id>` 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
  // `<instance_config_name>/operations/<operation_id>` 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/<project>/instanceConfigs/<instance_config>/operations/<operation>`.
  // 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) = {
      get: "/v1/{parent=projects/*}/instances"
    };
    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) = {
      get: "/v1/{name=projects/*/instances/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // 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: "*"
    };
    option (google.api.method_signature) = "parent,instance_id,instance";
    option (google.longrunning.operation_info) = {
      response_type: "google.spanner.admin.instance.v1.Instance"
      metadata_type: "google.spanner.admin.instance.v1.CreateInstanceMetadata"
    };
  }

  // 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
  // the 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: "*"
    };
    option (google.api.method_signature) = "instance,field_mask";
    option (google.longrunning.operation_info) = {
      response_type: "google.spanner.admin.instance.v1.Instance"
      metadata_type: "google.spanner.admin.instance.v1.UpdateInstanceMetadata"
    };
  }

  // 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/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // 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: "*"
    };
    option (google.api.method_signature) = "resource,policy";
  }

  // 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: "*"
    };
    option (google.api.method_signature) = "resource";
  }

  // 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: "*"
    };
    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
  // `<instance_partition_name>/operations/<operation_id>` 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
  // `<instance_partition_name>/operations/<operation_id>` 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/<project>/instances/<instance>/instancePartitions/<instance_partition>/operations/<operation>`.
  // 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 {
  // Indicates the type of replica.  See the [replica types
  // documentation](https://cloud.google.com/spanner/docs/replication#replica_types)
  // for more details.
  enum ReplicaType {
    // Not specified.
    TYPE_UNSPECIFIED = 0;

    // Read-write replicas support both reads and writes. These replicas:
    //
    // * Maintain a full copy of your data.
    // * Serve reads.
    // * Can vote whether to commit a write.
    // * Participate in leadership election.
    // * Are eligible to become a leader.
    READ_WRITE = 1;

    // Read-only replicas only support reads (not writes). Read-only replicas:
    //
    // * Maintain a full copy of your data.
    // * Serve reads.
    // * Do not participate in voting to commit writes.
    // * Are not eligible to become a leader.
    READ_ONLY = 2;

    // Witness replicas don't support reads but do participate in voting to
    // commit writes. Witness replicas:
    //
    // * Do not maintain a full copy of data.
    // * Do not serve reads.
    // * Vote whether to commit writes.
    // * Participate in leader election but are not eligible to become leader.
    WITNESS = 3;
  }

  // The location of the serving resources, e.g. "us-central1".
  string location = 1;

  // The type of replica.
  ReplicaType type = 2;

  // If true, this location is designated as the default leader location where
  // leader replicas are placed. See the [region types
  // documentation](https://cloud.google.com/spanner/docs/instances#region_types)
  // for more details.
  bool default_leader_location = 3;
}

// A possible configuration for a Cloud Spanner instance. Configurations
// define the geographic placement of nodes and their replication.
message InstanceConfig {
  option (google.api.resource) = {
    type: "spanner.googleapis.com/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/<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;

  // 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/<project_name>/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<string, string> 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];
}

// Autoscaling config for an instance.
message AutoscalingConfig {
  // The autoscaling limits for the instance. Users can define the minimum and
  // maximum compute capacity allocated to the instance, and the autoscaler will
  // only scale within that range. Users can either use nodes or processing
  // units to specify the limits, but should use the same unit to set both the
  // min_limit and max_limit.
  message AutoscalingLimits {
    // The minimum compute capacity for the instance.
    oneof min_limit {
      // Minimum number of nodes allocated to the instance. If set, this number
      // should be greater than or equal to 1.
      int32 min_nodes = 1;

      // Minimum number of processing units allocated to the instance. If set,
      // this number should be multiples of 1000.
      int32 min_processing_units = 2;
    }

    // The maximum compute capacity for the instance. The maximum compute
    // capacity should be less than or equal to 10X the minimum compute
    // capacity.
    oneof max_limit {
      // Maximum number of nodes allocated to the instance. If set, this number
      // should be greater than or equal to min_nodes.
      int32 max_nodes = 3;

      // Maximum number of processing units allocated to the instance. If set,
      // this number should be multiples of 1000 and be greater than or equal to
      // min_processing_units.
      int32 max_processing_units = 4;
    }
  }

  // The autoscaling targets for an instance.
  message AutoscalingTargets {
    // Required. The target high priority cpu utilization percentage that the
    // autoscaler should be trying to achieve for the instance. This number is
    // on a scale from 0 (no utilization) to 100 (full utilization). The valid
    // range is [10, 90] inclusive.
    int32 high_priority_cpu_utilization_percent = 1
        [(google.api.field_behavior) = REQUIRED];

    // Required. The target storage utilization percentage that the autoscaler
    // should be trying to achieve for the instance. This number is on a scale
    // from 0 (no utilization) to 100 (full utilization). The valid range is
    // [10, 100] inclusive.
    int32 storage_utilization_percent = 2
        [(google.api.field_behavior) = REQUIRED];
  }

  // Required. Autoscaling limits for an instance.
  AutoscalingLimits autoscaling_limits = 1
      [(google.api.field_behavior) = REQUIRED];

  // Required. The autoscaling targets for an instance.
  AutoscalingTargets autoscaling_targets = 2
      [(google.api.field_behavior) = REQUIRED];
}

// An isolated set of Cloud Spanner resources on which databases can be hosted.
message Instance {
  option (google.api.resource) = {
    type: "spanner.googleapis.com/Instance"
    pattern: "projects/{project}/instances/{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 2 and 64 characters in length.
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // 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 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "spanner.googleapis.com/InstanceConfig"
    }
  ];

  // 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 [(google.api.field_behavior) = REQUIRED];

  // The number of nodes allocated to this instance. At most one of either
  // node_count or processing_units should be present in the message.
  //
  // Users can set the node_count field to specify the target number of nodes
  // allocated to the instance.
  //
  // This may be zero in API responses for instances that are not yet in state
  // `READY`.
  //
  // See [the
  // documentation](https://cloud.google.com/spanner/docs/compute-capacity)
  // for more information about nodes and processing units.
  int32 node_count = 5;

  // The number of processing units allocated to this instance. At most one of
  // processing_units or node_count should be present in the message.
  //
  // Users can set the processing_units field to specify the target number of
  // processing units allocated to the instance.
  //
  // This may be zero in API responses for instances that are not yet in state
  // `READY`.
  //
  // See [the
  // documentation](https://cloud.google.com/spanner/docs/compute-capacity)
  // for more information about nodes and processing units.
  int32 processing_units = 9;

  // Optional. The autoscaling configuration. Autoscaling is enabled if this
  // field is set. When autoscaling is enabled, node_count and processing_units
  // are treated as OUTPUT_ONLY fields and reflect the current compute capacity
  // allocated to the instance.
  AutoscalingConfig autoscaling_config = 17
      [(google.api.field_behavior) = OPTIONAL];

  // 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 [(google.api.field_behavior) = OUTPUT_ONLY];

  // 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. 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;

  // Deprecated. This field is not populated.
  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];

  // Output only. The time at which the instance was most recently updated.
  google.protobuf.Timestamp update_time = 12
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// 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 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/Project"
    }
  ];

  // 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 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "spanner.googleapis.com/InstanceConfig"
    }
  ];
}

// 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/<project>`.
  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
  // `<parent>/instanceConfigs/<instance_config_id>`.
  // instance_config.base_config must be a Google managed configuration name,
  // e.g. <parent>/instanceConfigs/us-east1, <parent>/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/<project>/instanceConfigs/<instance_config>`
  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/<project>`.
  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.<field_name>` - 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.<field_name>` - 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/<project>/instances/<instance>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "spanner.googleapis.com/Instance"
    }
  ];

  // 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].
message CreateInstanceRequest {
  // Required. The name of the project in which to create the instance. Values
  // are of the form `projects/<project>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/Project"
    }
  ];

  // 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 2 and 64 characters in
  // length.
  string instance_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The instance to create.  The name may be omitted, but if
  // specified must be `<parent>/instances/<instance_id>`.
  Instance instance = 3 [(google.api.field_behavior) = REQUIRED];
}

// 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 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/Project"
    }
  ];

  // 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;

  // 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].
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 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
// [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.
  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.
  // 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];
}

// 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 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "spanner.googleapis.com/Instance"
    }
  ];
}

// 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;

  // The expected fulfillment period of this create operation.
  FulfillmentPeriod expected_fulfillment_period = 5;
}

// 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;

  // The expected fulfillment period of this update operation.
  FulfillmentPeriod expected_fulfillment_period = 5;
}

// 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.
  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.
  OperationProgress progress = 2;

  // 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/<project>/instances/<instance>/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/<project>/instanceConfigs/<configuration>`. 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/<project>/instances/<instance>`.
  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
  // `<parent>/instancePartitions/<instance_partition_id>`.
  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/<project>/instances/<instance>`.
  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/<project>/instances/<instance>`.
  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.<field_name>` - 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.<field_name>` - 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;
}