From 8a10b9a9e419ab9db61fca977f14c81ec630414c Mon Sep 17 00:00:00 2001 From: Scott Seago Date: Wed, 28 Sep 2022 13:58:15 -0400 Subject: [PATCH] RestoreItemAction v2 design Signed-off-by: Scott Seago --- design/riav2-design.md | 109 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 design/riav2-design.md diff --git a/design/riav2-design.md b/design/riav2-design.md new file mode 100644 index 000000000..f42af2750 --- /dev/null +++ b/design/riav2-design.md @@ -0,0 +1,109 @@ +# Design for RestoreItemAction v2 API + +## Abstract +This design includes the changes to the RestoreItemAction (RIA) api design as required by the [Item Action Progress Monitoring](general-progress-monitoring.md) feature. +It also includes changes as required by the [Wait For Additional Items](wait-for-additional-items.md) feature. +The BIA v2 interface will have three new methods, and the RestoreItemActionExecuteOutput() struct in the return from Execute() will have three optional fields added. +If there are any additional RIA API changes that are needed in the same Velero release cycle as this change, those can be added here as well. + +## Background +This API change is needed to facilitate long-running plugin actions that may not be complete when the Execute() method returns. +It is an optional feature, so plugins which don't need this feature can simply return an empty operation ID and the new methods can be no-ops. +This will allow long-running plugin actions to continue in the background while Velero moves on to the next plugin, the next item, etc. +The other change allows Velero to wait until newly-restored AdditionalItems returned by a RIA plugin are ready before moving on to restoring the current item. + +## Goals +- Allow for RIA Execute() to optionally initiate a long-running operation and report on operation status. +- Allow for RIA to allow Velero to call back into the plugin to wait until AdditionalItems are ready before continuing with restore. + +## Non Goals +- Allowing velero control over when the long-running operation begins. + + +## High-Level Design +As per the [Plugin Versioning](plugin-versioning.md) design, a new RIAv2 plugin `.proto` file will be created to define the GRPC interface. +v2 go files will also be created in `plugin/clientmgmt/restoreitemaction` and `plugin/framework/restoreitemaction`, and a new PluginKind will be created. +Changes to RestoreItemActionExecuteOutput will be made to the existing struct. +Since the new fields are optional elements of the struct, the new enlarged struct will work with both v1 and v2 plugins. +The velero Restore process will be modified to reference v2 plugins instead of v1 plugins. +An adapter will be created so that any existing RIA v1 plugin can be executed as a v2 plugin when executing a restore. + +## Detailed Design + +### proto changes (compiled into golang by protoc) + +The v2 RestoreItemAction.proto will be like the current v1 version with the following changes: +RestoreItemActionExecuteOutput gets three new fields (defined in the current (v1) RestoreItemAction.proto file: +``` +message RestoreItemActionExecuteResponse { + bytes item = 1; + repeated ResourceIdentifier additionalItems = 2; + bool skipRestore = 3; + string operationID = 4; + bool waitForAdditionalItems = 5; + google.protobuf.Duration additionalItemsReadyTimeout = 6; +} + +``` +The RestoreItemAction service gets three new rpc methods: +``` +service RestoreItemAction { + rpc AppliesTo(RestoreItemActionAppliesToRequest) returns (RestoreItemActionAppliesToResponse); + rpc Execute(RestoreItemActionExecuteRequest) returns (RestoreItemActionExecuteResponse); + rpc Progress(RestoreItemActionProgressRequest) returns (RestoreItemActionProgressResponse); + rpc Cancel(RestoreItemActionCancelRequest) returns (google.protobuf.Empty); + rpc AreAdditionalItemsReady(RestoreItemActionItemsReadyRequest) returns (RestoreItemActionItemsReadyResponse); +} + +``` +To support these new rpc methods, we define new request/response message types: +``` +message RestoreItemActionProgressRequest { + string plugin = 1; + string operationID = 2; + bytes restore = 3; +} + +message RestoreItemActionProgressResponse { + generated.OperationProgress progress = 1; +} + +message RestoreItemActionCancelRequest { + string plugin = 1; + string operationID = 2; + bytes restore = 3; +} + +message RestoreItemActionItemsReadyRequest { + string plugin = 1; + bytes restore = 2; + repeated ResourceIdentifier additionalItems = 3; +} +message RestoreItemActionItemsReadyResponse { + bool ready = 1; +} + +``` +One new shared message type will be needed, as defined in the v2 BackupItemAction design: +``` +message OperationProgress { + bool completed = 1; + string err = 2; + int64 completed = 3; + int64 total = 4; + string operationUnits = 5; + string description = 6; + google.protobuf.Timestamp started = 7; + google.protobuf.Timestamp updated = 8; +} +``` + +A new PluginKind, `RestoreItemActionV2`, will be created, and the restore process will be modified to use this plugin kind. +See [Plugin Versioning](plugin-versioning.md) for more details on implementation plans, including v1 adapters, etc. + + +## Compatibility +The included v1 adapter will allow any existing RestoreItemAction plugin to work as expected, with no-op AreAdditionalItemsReady(), Progress(), and Cancel() methods. + +## Implementation +This will be implemented during the Velero 1.11 development cycle.