feat: added new restore scope options

feat: added transformation rules for restore
feat: added BackupPlan and RestorePlan state information

These features aim to do the following:
1. Improve flexibility of restore with new options to define new kinds of scope configurations.
2. Improve flexibility of restore by supporting Transformation Rules, which enable the removal and addition of spec fields of restored resources prior to their creation.
3. Improve observability by revealing the state information of BackupPlan and RestorePlan.

PiperOrigin-RevId: 543605700

google/cloud/gkebackup/v1/BUILD.bazel

@@ -348,7 +348,7 @@ load(
 
 csharp_proto_library(
     name = "gkebackup_csharp_proto",
-    extra_opts = [],
+    extra_opts = [""],
     deps = [":gkebackup_proto"],
 )
 

google/cloud/gkebackup/v1/backup_plan.proto

@@ -77,7 +77,7 @@ message BackupPlan {
     bool locked = 3;
   }
 
-  // Schedule defines scheduling parameters for automatically creating Backups
+  // Defines scheduling parameters for automatically creating Backups
   // via this BackupPlan.
   message Schedule {
     // A standard [cron](https://wikipedia.com/wiki/cron) string that defines a
@@ -134,6 +134,30 @@ message BackupPlan {
     EncryptionKey encryption_key = 6;
   }
 
+  // State
+  enum State {
+    // Default first value for Enums.
+    STATE_UNSPECIFIED = 0;
+
+    // Waiting for cluster state to be RUNNING.
+    CLUSTER_PENDING = 1;
+
+    // The BackupPlan is in the process of being created.
+    PROVISIONING = 2;
+
+    // The BackupPlan has successfully been created and is ready for Backups.
+    READY = 3;
+
+    // BackupPlan creation has failed.
+    FAILED = 4;
+
+    // The BackupPlan has been deactivated.
+    DEACTIVATED = 5;
+
+    // The BackupPlan is in the process of being deleted.
+    DELETING = 6;
+  }
+
   // Output only. The full name of the BackupPlan resource.
   // Format: `projects/*/locations/*/backupPlans/*`
   string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -201,4 +225,14 @@ message BackupPlan {
   // Output only. The number of Kubernetes Pods backed up in the
   // last successful Backup created via this BackupPlan.
   int32 protected_pod_count = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. State of the BackupPlan. This State field reflects the
+  // various stages a BackupPlan can be in
+  // during the Create operation. It will be set to "DEACTIVATED"
+  // if the BackupPlan is deactivated on an Update
+  State state = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Human-readable description of why BackupPlan is in the current
+  // `state`
+  string state_reason = 15 [(google.api.field_behavior) = OUTPUT_ONLY];
 }

google/cloud/gkebackup/v1/restore.proto

@@ -157,7 +157,7 @@ message Restore {
 }
 
 // Configuration of a restore.
-// Next id: 9
+// Next id: 12
 message RestoreConfig {
   // Defines how volume data should be restored.
   enum VolumeDataRestorePolicy {
@@ -257,6 +257,21 @@ message RestoreConfig {
     // backup. If specified, only the selected resources will be restored.
     // Mutually exclusive to any other field in the message.
     repeated GroupKind selected_group_kinds = 1;
+
+    // A list of cluster-scoped resource group kinds to NOT restore from the
+    // backup. If specified, all valid cluster-scoped resources will be
+    // restored except for those specified in the list.
+    // Mutually exclusive to any other field in the message.
+    repeated GroupKind excluded_group_kinds = 2;
+
+    // If True, all valid cluster-scoped resources will be restored.
+    // Mutually exclusive to any other field in the message.
+    bool all_group_kinds = 3;
+
+    // If True, no cluster-scoped resources will be restored.
+    // This has the same restore scope as if the message is not defined.
+    // Mutually exclusive to any other field in the message.
+    bool no_group_kinds = 4;
   }
 
   // A transformation rule to be applied against Kubernetes resources as they
@@ -305,6 +320,111 @@ message RestoreConfig {
     string new_value = 5;
   }
 
+  // TransformationRuleAction defines a TransformationRule action based on the
+  // JSON Patch RFC (https://www.rfc-editor.org/rfc/rfc6902)
+  message TransformationRuleAction {
+    // Possible values for operations of a transformation rule action.
+    enum Op {
+      // Unspecified operation
+      OP_UNSPECIFIED = 0;
+
+      // The "remove" operation removes the value at the target location.
+      REMOVE = 1;
+
+      // The "move" operation removes the value at a specified location and
+      // adds it to the target location.
+      MOVE = 2;
+
+      // The "copy" operation copies the value at a specified location to the
+      // target location.
+      COPY = 3;
+
+      // The "add" operation performs one of the following functions,
+      // depending upon what the target location references:
+      // 1. If the target location specifies an array index, a new value is
+      // inserted into the array at the specified index.
+      // 2. If the target location specifies an object member that does not
+      // already exist, a new member is added to the object.
+      // 3. If the target location specifies an object member that does exist,
+      // that member's value is replaced.
+      ADD = 4;
+
+      // The "test" operation tests that a value at the target location is
+      // equal to a specified value.
+      TEST = 5;
+
+      // The "replace" operation replaces the value at the target location
+      // with a new value.  The operation object MUST contain a "value" member
+      // whose content specifies the replacement value.
+      REPLACE = 6;
+    }
+
+    // Required. op specifies the operation to perform.
+    Op op = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // A string containing a JSON Pointer value that references the location in
+    // the target document to move the value from.
+    string from_path = 2;
+
+    // A string containing a JSON-Pointer value that references a location
+    // within the target document where the operation is performed.
+    string path = 3;
+
+    // A string that specifies the desired value in string format to
+    // use for transformation.
+    string value = 4;
+  }
+
+  // ResourceFilter specifies matching criteria to limit the scope of a
+  // change to a specific set of kubernetes resources that are selected for
+  // restoration from a backup.
+  message ResourceFilter {
+    // (Filtering parameter) Any resource subject to transformation must be
+    // contained within one of the listed Kubernetes Namespace in the Backup.
+    // If this field is not provided, no namespace filtering will be performed
+    // (all resources in all Namespaces, including all cluster-scoped resources,
+    // will be candidates for transformation).
+    // To mix cluster-scoped and namespaced resources in the same rule, use an
+    // empty string ("") as one of the target namespaces.
+    repeated string namespaces = 1;
+
+    // (Filtering parameter) Any resource subject to transformation must belong
+    // to one of the listed "types". If this field is not provided, no type
+    // filtering will be performed (all resources of all types matching previous
+    // filtering parameters will be candidates for transformation).
+    repeated GroupKind group_kinds = 2;
+
+    // This is a [JSONPath]
+    // (https://github.com/json-path/JsonPath/blob/master/README.md)
+    // expression that matches specific fields of candidate
+    // resources and it operates as a filtering parameter (resources that
+    // are not matched with this expression will not be candidates for
+    // transformation).
+    string json_path = 3;
+  }
+
+  // A transformation rule to be applied against Kubernetes resources as they
+  // are selected for restoration from a Backup. A rule contains both filtering
+  // logic (which resources are subject to transform) and transformation logic.
+  message TransformationRule {
+    // Required. A list of transformation rule actions to take against candidate
+    // resources. Actions are executed in order defined - this order matters, as
+    // they could potentially interfere with each other and the first operation
+    // could affect the outcome of the second operation.
+    repeated TransformationRuleAction field_actions = 1
+        [(google.api.field_behavior) = REQUIRED];
+
+    // This field is used to specify a set of fields that should be used to
+    // determine which resources in backup should be acted upon by the supplied
+    // transformation rule actions, and this will ensure that only specific
+    // resources are affected by transformation rule actions.
+    ResourceFilter resource_filter = 2;
+
+    // The description is a user specified string description of the
+    // transformation rule.
+    string description = 3;
+  }
+
   // Specifies the mechanism to be used to restore volume data.
   // Default: VOLUME_DATA_RESTORE_POLICY_UNSPECIFIED (will be treated as
   // NO_VOLUME_DATA_RESTORATION).
@@ -348,6 +468,14 @@ message RestoreConfig {
     // ProtectedApplications and all the resources to which they refer will be
     // restored.
     NamespacedNames selected_applications = 7;
+
+    // Do not restore any namespaced resources if set to "True".
+    // Specifying this field to "False" is not allowed.
+    bool no_namespaces = 9;
+
+    // A list of selected namespaces excluded from restoration. All
+    // namespaces except those in this list will be restored.
+    Namespaces excluded_namespaces = 10;
   }
 
   // A list of transformation rules to be applied against Kubernetes resources
@@ -356,4 +484,11 @@ message RestoreConfig {
   // the filtering logic of subsequent rules. An empty list means no
   // substitution will occur.
   repeated SubstitutionRule substitution_rules = 8;
+
+  // A list of transformation rules to be applied against Kubernetes resources
+  // as they are selected for restoration from a Backup. Rules are executed in
+  // order defined - this order matters, as changes made by a rule may impact
+  // the filtering logic of subsequent rules. An empty list means no
+  // transformation will occur.
+  repeated TransformationRule transformation_rules = 11;
 }

google/cloud/gkebackup/v1/restore_plan.proto

@@ -31,13 +31,31 @@ option ruby_package = "Google::Cloud::GkeBackup::V1";
 
 // The configuration of a potential series of Restore operations to be performed
 // against Backups belong to a particular BackupPlan.
-// Next id: 11
+// Next id: 13
 message RestorePlan {
   option (google.api.resource) = {
     type: "gkebackup.googleapis.com/RestorePlan"
     pattern: "projects/{project}/locations/{location}/restorePlans/{restore_plan}"
   };
 
+  // State
+  enum State {
+    // Default first value for Enums.
+    STATE_UNSPECIFIED = 0;
+
+    // Waiting for cluster state to be RUNNING.
+    CLUSTER_PENDING = 1;
+
+    // The RestorePlan has successfully been created and is ready for Restores.
+    READY = 2;
+
+    // RestorePlan creation has failed.
+    FAILED = 3;
+
+    // The RestorePlan is in the process of being deleted.
+    DELETING = 4;
+  }
+
   // Output only. The full name of the RestorePlan resource.
   // Format: `projects/*/locations/*/restorePlans/*`.
   string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -100,4 +118,13 @@ message RestorePlan {
   // `UpdateRestorePlan` or `DeleteRestorePlan` to ensure that their change
   // will be applied to the same version of the resource.
   string etag = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. State of the RestorePlan. This State field reflects the
+  // various stages a RestorePlan can be in
+  // during the Create operation.
+  State state = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Human-readable description of why RestorePlan is in the
+  // current `state`
+  string state_reason = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
 }