feat: add metadata exchange support for AlloyDB connectors

feat: adds metadata field describing an AlloyDB backup's quantity based retention

PiperOrigin-RevId: 547600058

google/cloud/alloydb/connectors/v1alpha/alloydb_v1alpha.yaml

@@ -0,0 +1,222 @@
+type: google.api.Service
+config_version: 3
+name: alloydb.googleapis.com
+title: AlloyDB API
+
+apis:
+- name: google.cloud.alloydb.v1alpha.AlloyDBAdmin
+- name: google.cloud.location.Locations
+- name: google.iam.v1.IAMPolicy
+- name: google.longrunning.Operations
+
+types:
+- name: google.cloud.alloydb.connectors.v1alpha.MetadataExchangeRequest
+- name: google.cloud.alloydb.connectors.v1alpha.MetadataExchangeResponse
+- name: google.cloud.alloydb.v1alpha.BatchCreateInstancesResponse
+- name: google.cloud.alloydb.v1alpha.OperationMetadata
+
+documentation:
+  summary: |-
+    AlloyDB for PostgreSQL is an open source-compatible database service that
+    provides a powerful option for migrating, modernizing, or building
+    commercial-grade applications. It offers full compatibility with standard
+    PostgreSQL, and is more than 4x faster for transactional workloads and up
+    to 100x faster for analytical queries than standard PostgreSQL in our
+    performance tests. AlloyDB for PostgreSQL offers a 99.99 percent
+    availability SLA inclusive of maintenance. <br><br> AlloyDB is optimized
+    for the most demanding use cases, allowing you to build new applications
+    that require high transaction throughput, large database sizes, or
+    multiple read resources; scale existing PostgreSQL workloads with no
+    application changes; and modernize legacy proprietary databases.
+  rules:
+  - selector: google.cloud.location.Locations.GetLocation
+    description: Gets information about a location.
+
+  - selector: google.cloud.location.Locations.ListLocations
+    description: Lists information about the supported locations for this service.
+
+  - selector: google.iam.v1.IAMPolicy.GetIamPolicy
+    description: |-
+      Gets the access control policy for a resource. Returns an empty policy
+      if the resource exists and does not have a policy set.
+
+  - selector: google.iam.v1.IAMPolicy.SetIamPolicy
+    description: |-
+      Sets the access control policy on the specified resource. Replaces
+      any existing policy.
+
+      Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED`
+      errors.
+
+  - selector: google.iam.v1.IAMPolicy.TestIamPermissions
+    description: |-
+      Returns permissions that a caller has on the specified resource. If the
+      resource does not exist, this will return an empty set of
+      permissions, not a `NOT_FOUND` error.
+
+      Note: This operation is designed to be used for building
+      permission-aware UIs and command-line tools, not for authorization
+      checking. This operation may "fail open" without warning.
+
+backend:
+  rules:
+  - selector: 'google.cloud.alloydb.v1alpha.AlloyDBAdmin.*'
+    deadline: 60.0
+  - selector: google.cloud.location.Locations.GetLocation
+    deadline: 60.0
+  - selector: google.cloud.location.Locations.ListLocations
+    deadline: 60.0
+  - selector: 'google.iam.v1.IAMPolicy.*'
+    deadline: 60.0
+  - selector: 'google.longrunning.Operations.*'
+    deadline: 60.0
+
+http:
+  rules:
+  - selector: google.cloud.location.Locations.GetLocation
+    get: '/v1alpha/{name=projects/*/locations/*}'
+  - selector: google.cloud.location.Locations.ListLocations
+    get: '/v1alpha/{name=projects/*}/locations'
+  - selector: google.longrunning.Operations.CancelOperation
+    post: '/v1alpha/{name=projects/*/locations/*/operations/*}:cancel'
+    body: '*'
+  - selector: google.longrunning.Operations.DeleteOperation
+    delete: '/v1alpha/{name=projects/*/locations/*/operations/*}'
+  - selector: google.longrunning.Operations.GetOperation
+    get: '/v1alpha/{name=projects/*/locations/*/operations/*}'
+  - selector: google.longrunning.Operations.ListOperations
+    get: '/v1alpha/{name=projects/*/locations/*}/operations'
+
+authentication:
+  rules:
+  - selector: 'google.cloud.alloydb.v1alpha.AlloyDBAdmin.*'
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
+  - selector: google.cloud.location.Locations.GetLocation
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
+  - selector: google.cloud.location.Locations.ListLocations
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
+  - selector: 'google.iam.v1.IAMPolicy.*'
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
+  - selector: 'google.longrunning.Operations.*'
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
+
+publishing:
+  new_issue_uri: https://issuetracker.google.com/issues/new?component=1194526&template=1689942
+  documentation_uri: https://cloud.google.com/alloydb/docs
+  api_short_name: alloydb
+  github_label: 'api: alloydb'
+  doc_tag_prefix: alloydb
+  organization: CLOUD
+  library_settings:
+  - version: google.cloud.alloydb.v1
+    launch_stage: GA
+    java_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    cpp_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    php_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    python_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    node_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    dotnet_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    ruby_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    go_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+  - version: google.cloud.alloydb.v1beta
+    launch_stage: BETA
+    java_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    cpp_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    php_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    python_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    node_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    dotnet_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    ruby_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    go_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+  - version: google.cloud.alloydb.v1alpha
+    launch_stage: ALPHA
+    java_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    cpp_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    php_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    python_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    node_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    dotnet_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    ruby_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    go_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER

google/cloud/alloydb/connectors/v1alpha/resources.proto

@@ -0,0 +1,80 @@
+// Copyright 2023 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.cloud.alloydb.connectors.v1alpha;
+
+import "google/api/field_behavior.proto";
+
+option csharp_namespace = "Google.Cloud.AlloyDb.Connectors.V1Alpha";
+option go_package = "cloud.google.com/go/alloydb/connectors/apiv1alpha/connectorspb;connectorspb";
+option java_multiple_files = true;
+option java_outer_classname = "ResourcesProto";
+option java_package = "com.google.cloud.alloydb.connectors.v1alpha";
+option php_namespace = "Google\\Cloud\\AlloyDb\\Connectors\\V1alpha";
+option ruby_package = "Google::Cloud::AlloyDb::Connectors::V1alpha";
+
+// Message used by AlloyDB connectors to exchange client and connection metadata
+// with the server after a successful TLS handshake. This metadata includes an
+// IAM token, which is used to authenticate users based on their IAM identity.
+// The sole purpose of this message is for the use of AlloyDB connectors.
+// Clients should not rely on this message directly as there can be breaking
+// changes in the future.
+message MetadataExchangeRequest {
+  // AuthType contains all supported authentication types.
+  enum AuthType {
+    // Authentication type is unspecified and DB_NATIVE is used by default
+    AUTH_TYPE_UNSPECIFIED = 0;
+
+    // Database native authentication (user/password)
+    DB_NATIVE = 1;
+
+    // Automatic IAM authentication
+    AUTO_IAM = 2;
+  }
+
+  // Optional. Connector information.
+  string user_agent = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Authentication type.
+  AuthType auth_type = 2;
+
+  // IAM token used for both IAM user authentiation and
+  // `alloydb.instances.connect` permission check.
+  string oauth2_token = 3;
+}
+
+// Message for response to metadata exchange request. The sole purpose of this
+// message is for the use of AlloyDB connectors. Clients should not rely on this
+// message directly as there can be breaking changes in the future.
+message MetadataExchangeResponse {
+  // Response code.
+  enum ResponseCode {
+    // Unknown response code
+    RESPONSE_CODE_UNSPECIFIED = 0;
+
+    // Success
+    OK = 1;
+
+    // Failure
+    ERROR = 2;
+  }
+
+  // Response code.
+  ResponseCode response_code = 1;
+
+  // Optional. Error message.
+  string error = 2 [(google.api.field_behavior) = OPTIONAL];
+}

google/cloud/alloydb/v1alpha/resources.proto

@@ -308,9 +308,9 @@ message ContinuousBackupConfig {
   // Whether ContinuousBackup is enabled.
   optional bool enabled = 1;
 
-  // The number of days backups and logs will be retained, which determines the
-  // window of time that data is recoverable for. If not set, it defaults to 14
-  // days.
+  // The number of days that are eligible to restore from using PITR. To support
+  // the entire recovery window, backups and logs are retained for one day more
+  // than the recovery window. If not set, defaults to 14 days.
   int32 recovery_window_days = 4;
 
   // The encryption config can be specified to encrypt the
@@ -529,11 +529,11 @@ message Cluster {
   // the cluster (i.e. `CreateCluster` vs. `CreateSecondaryCluster`
   ClusterType cluster_type = 24 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The database engine major version. This is an output-only
-  // field and it's populated at the Cluster creation time. This field cannot be
-  // changed after cluster creation.
-  DatabaseVersion database_version = 9
-      [(google.api.field_behavior) = OUTPUT_ONLY];
+  // Optional. The database engine major version. This is an optional field and
+  // it is populated at the Cluster creation time. If a database version is not
+  // supplied at cluster creation time, then a default database version will
+  // be used.
+  DatabaseVersion database_version = 9 [(google.api.field_behavior) = OPTIONAL];
 
   NetworkConfig network_config = 29 [(google.api.field_behavior) = OPTIONAL];
 
@@ -603,6 +603,9 @@ message Cluster {
 
   // Output only. Cross Region replication config specific to PRIMARY cluster.
   PrimaryConfig primary_config = 23 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Reserved for future use.
+  bool satisfies_pzs = 30;
 }
 
 // An Instance is a computing unit that an end customer can connect to.
@@ -871,6 +874,9 @@ message Instance {
   // To use a non-default update policy, you must
   // specify explicitly specify the value in each update request.
   UpdatePolicy update_policy = 22;
+
+  // Reserved for future use.
+  bool satisfies_pzs = 24;
 }
 
 // ConnectionInfo singleton resource.
@@ -907,6 +913,29 @@ message Backup {
     style: DECLARATIVE_FRIENDLY
   };
 
+  // A backup's position in a quantity-based retention queue, of backups with
+  // the same source cluster and type, with length, retention, specified by the
+  // backup's retention policy.
+  // Once the position is greater than the retention, the backup is eligible to
+  // be garbage collected.
+  //
+  // Example: 5 backups from the same source cluster and type with a
+  // quantity-based retention of 3 and denoted by backup_id (position,
+  // retention).
+  //
+  // Safe: backup_5 (1, 3), backup_4, (2, 3), backup_3 (3, 3).
+  // Awaiting garbage collection: backup_2 (4, 3), backup_1 (5, 3)
+  message QuantityBasedExpiry {
+    // Output only. The backup's position among its backups with the same source
+    // cluster and type, by descending chronological order create time(i.e.
+    // newest first).
+    int32 retention_count = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+    // Output only. The length of the quantity-based queue, specified by the
+    // backup's retention policy.
+    int32 total_retention_count = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+  }
+
   // Backup State
   enum State {
     // The state of the backup is unknown.
@@ -1029,6 +1058,15 @@ message Backup {
   // added to the backup's create_time.
   google.protobuf.Timestamp expiry_time = 19
       [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The QuantityBasedExpiry of the backup, specified by the
+  // backup's retention policy. Once the expiry quantity is over retention, the
+  // backup is eligible to be garbage collected.
+  QuantityBasedExpiry expiry_quantity = 20
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Reserved for future use.
+  bool satisfies_pzs = 21;
 }
 
 // SupportedDatabaseFlag gives general information about a database flag,