feat: Add the managed disaster recovery API(https://cloud.google.com/bigquery/docs/managed-disaster-recovery)

Google APIs · copybara-github · commit 4743cf9ecab3 · 2024-12-02T14:07:21.000-08:00
feat: Add a new field `is_flat_rate` to `.google.cloud.bigquery.reservation.v1.CapacityCommitment` to distinguish between flat rate and edition commitments
docs: Clarify that `Autoscale.current_slots` in message `.google.cloud.bigquery.reservation.v1.Reservation` can temporarily be larger than `Autoscale.max_slots` if users reduce `Autoscale.max_slots`
docs: Update comment for `slot_capacity` in message `.google.cloud.bigquery.reservation.v1.Reservation` to provide more clarity about reservation baselines, committed slots and autoscaler SKU charges when the baseline exceeds committed slots
docs: Update comments for `commitment_start_time` and `commitment_end_time` in message `.google.cloud.bigquery.reservation.v1.CapacityCommitment` to provide details on how these values are affected by commitment renewal

PiperOrigin-RevId: 702079972
diff --git a/google/cloud/bigquery/reservation/v1/bigqueryreservation_v1.yaml b/google/cloud/bigquery/reservation/v1/bigqueryreservation_v1.yaml
@@ -9,11 +9,6 @@ apis:
 documentation:
   summary: 'A service to modify your BigQuery flat-rate reservations.'
 
-backend:
-  rules:
-  - selector: 'google.cloud.bigquery.reservation.v1.ReservationService.*'
-    deadline: 300.0
-
 authentication:
   rules:
   - selector: 'google.cloud.bigquery.reservation.v1.ReservationService.*'
diff --git a/google/cloud/bigquery/reservation/v1/reservation.proto b/google/cloud/bigquery/reservation/v1/reservation.proto
@@ -99,6 +99,18 @@ service ReservationService {
     option (google.api.method_signature) = "reservation,update_mask";
   }
 
+  // Fail over a reservation to the secondary location. The operation should be
+  // done in the current secondary location, which will be promoted to the
+  // new primary location for the reservation.
+  // Attempting to failover a reservation in the current primary location will
+  // fail with the error code `google.rpc.Code.FAILED_PRECONDITION`.
+  rpc FailoverReservation(FailoverReservationRequest) returns (Reservation) {
+    option (google.api.http) = {
+      post: "/v1/{name=projects/*/locations/*/reservations/*}:failoverReservation"
+      body: "*"
+    };
+  }
+
   // Creates a new capacity commitment resource.
   rpc CreateCapacityCommitment(CreateCapacityCommitmentRequest)
       returns (CapacityCommitment) {
@@ -401,7 +413,10 @@ message Reservation {
   // Auto scaling settings.
   message Autoscale {
     // Output only. The slot capacity added to this reservation when autoscale
-    // happens. Will be between [0, max_slots].
+    // happens. Will be between [0, max_slots]. Note: after users reduce
+    // max_slots, it may take a while before it can be propagated, so
+    // current_slots may stay in the original value and could be larger than
+    // max_slots for that brief period (less than one minute)
     int64 current_slots = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 
     // Number of slots to be scaled when needed.
@@ -415,20 +430,26 @@ message Reservation {
   // maximum length is 64 characters.
   string name = 1;
 
-  // Minimum slots available to this reservation. A slot is a unit of
+  // Baseline slots available to this reservation. A slot is a unit of
   // computational power in BigQuery, and serves as the unit of parallelism.
   //
   // Queries using this reservation might use more slots during runtime if
-  // ignore_idle_slots is set to false.
-  //
-  // If total slot_capacity of the reservation and its siblings
-  // exceeds the total slot_count of all capacity commitments, the request will
-  // fail with `google.rpc.Code.RESOURCE_EXHAUSTED`.
+  // ignore_idle_slots is set to false, or autoscaling is enabled.
   //
+  // If edition is EDITION_UNSPECIFIED and total slot_capacity of the
+  // reservation and its siblings exceeds the total slot_count of all capacity
+  // commitments, the request will fail with
+  // `google.rpc.Code.RESOURCE_EXHAUSTED`.
   //
-  // NOTE: for reservations in US or EU multi-regions, slot capacity constraints
-  // are checked separately for default and auxiliary regions. See
-  // multi_region_auxiliary flag for more details.
+  // If edition is any value but EDITION_UNSPECIFIED, then the above requirement
+  // is not needed. The total slot_capacity of the reservation and its siblings
+  // may exceed the total slot_count of capacity commitments. In that case, the
+  // exceeding slots will be charged with the autoscale SKU. You can increase
+  // the number of baseline slots in a reservation every few minutes. If you
+  // want to decrease your baseline slots, you are limited to once an hour if
+  // you have recently changed your baseline slot capacity and your baseline
+  // slots exceed your committed slots. Otherwise, you can decrease your
+  // baseline slots every few minutes.
   int64 slot_capacity = 2;
 
   // If false, any query or pipeline job using this reservation will use idle
@@ -437,8 +458,7 @@ message Reservation {
   // capacity specified in the slot_capacity field at most.
   bool ignore_idle_slots = 4;
 
-  // The configuration parameters for the auto scaling feature. Note this is an
-  // alpha feature.
+  // The configuration parameters for the auto scaling feature.
   Autoscale autoscale = 7;
 
   // Job concurrency target which sets a soft upper bound on the number of jobs
@@ -447,8 +467,8 @@ message Reservation {
   // queries.
   // Default value is 0 which means that concurrency target will be
   // automatically computed by the system.
-  // NOTE: this field is exposed as `target_job_concurrency` in the Information
-  // Schema, DDL and BQ CLI.
+  // NOTE: this field is exposed as target job concurrency in the Information
+  // Schema, DDL and BigQuery CLI.
   int64 concurrency = 16;
 
   // Output only. Creation time of the reservation.
@@ -472,6 +492,38 @@ message Reservation {
 
   // Edition of the reservation.
   Edition edition = 17;
+
+  // Optional. The current location of the reservation's primary replica. This
+  // field is only set for reservations using the managed disaster recovery
+  // feature.
+  string primary_location = 18 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = {
+      type: "locations.googleapis.com/Location"
+    }
+  ];
+
+  // Optional. The current location of the reservation's secondary replica. This
+  // field is only set for reservations using the managed disaster recovery
+  // feature. Users can set this in create reservation calls
+  // to create a failover reservation or in update reservation calls to convert
+  // a non-failover reservation to a failover reservation(or vice versa).
+  string secondary_location = 19 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = {
+      type: "locations.googleapis.com/Location"
+    }
+  ];
+
+  // Optional. The location where the reservation was originally created. This
+  // is set only during the failover reservation's creation. All billing charges
+  // for the failover reservation will be applied to this location.
+  string original_primary_location = 20 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = {
+      type: "locations.googleapis.com/Location"
+    }
+  ];
 }
 
 // Capacity commitment is a way to purchase compute capacity for BigQuery jobs
@@ -510,7 +562,7 @@ message CapacityCommitment {
     // ACTIVE. After that, they are converted to a new commitment based on the
     // `renewal_plan`. Default `renewal_plan` for Trial commitment is Flex so
     // that it can be deleted right after committed period ends.
-    TRIAL = 5;
+    TRIAL = 5 [deprecated = true];
 
     // Monthly commitments have a committed period of 30 days after becoming
     // ACTIVE. After that, they are not in a committed period anymore and can be
@@ -579,12 +631,17 @@ message CapacityCommitment {
   State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The start of the current commitment period. It is applicable
-  // only for ACTIVE capacity commitments.
+  // only for ACTIVE capacity commitments. Note after the commitment is renewed,
+  // commitment_start_time won't be changed. It refers to the start time of the
+  // original commitment.
   google.protobuf.Timestamp commitment_start_time = 9
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The end of the current commitment period. It is applicable
-  // only for ACTIVE capacity commitments.
+  // only for ACTIVE capacity commitments. Note after renewal,
+  // commitment_end_time is the time the renewed commitment expires. So it would
+  // be at a time after commitment_start_time + committed period, because we
+  // don't change commitment_start_time ,
   google.protobuf.Timestamp commitment_end_time = 5
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
@@ -610,6 +667,10 @@ message CapacityCommitment {
 
   // Edition of the capacity commitment.
   Edition edition = 12;
+
+  // Output only. If true, the commitment is a flat-rate commitment, otherwise,
+  // it's an edition commitment.
+  bool is_flat_rate = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // The request for
@@ -699,6 +760,18 @@ message UpdateReservationRequest {
   google.protobuf.FieldMask update_mask = 2;
 }
 
+// The request for ReservationService.FailoverReservation.
+message FailoverReservationRequest {
+  // Required. Resource name of the reservation to failover. E.g.,
+  //    `projects/myproject/locations/US/reservations/team1-prod`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "bigqueryreservation.googleapis.com/Reservation"
+    }
+  ];
+}
+
 // The request for
 // [ReservationService.CreateCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.CreateCapacityCommitment].
 message CreateCapacityCommitmentRequest {
@@ -846,6 +919,8 @@ message Assignment {
   option (google.api.resource) = {
     type: "bigqueryreservation.googleapis.com/Assignment"
     pattern: "projects/{project}/locations/{location}/reservations/{reservation}/assignments/{assignment}"
+    plural: "assignments"
+    singular: "assignment"
   };
 
   // Types of job, which could be specified when using the reservation.
@@ -1172,6 +1247,6 @@ enum Edition {
   // Enterprise edition.
   ENTERPRISE = 2;
 
-  // Enterprise plus edition.
+  // Enterprise Plus edition.
   ENTERPRISE_PLUS = 3;
 }
