From 45e7792a969ac47b91b4e549ff259b70e70e0484 Mon Sep 17 00:00:00 2001 From: Gautham V Kidiyoor Date: Wed, 20 Sep 2023 15:30:54 -0700 Subject: [PATCH 1/7] Add commit confirmed extension --- rpc/gnmi/gnmi-commit-confirmed.md | 58 +++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 rpc/gnmi/gnmi-commit-confirmed.md diff --git a/rpc/gnmi/gnmi-commit-confirmed.md b/rpc/gnmi/gnmi-commit-confirmed.md new file mode 100644 index 0000000..6493d2f --- /dev/null +++ b/rpc/gnmi/gnmi-commit-confirmed.md @@ -0,0 +1,58 @@ +# gNMI Commit Confirmed Extension + +**Contributors:** Gautham V Kidiyoor, Rob Shakir, Vinit Kanvinde, Priyadeep Bangalore Lokesh + +**Date:** September 20, 2023 + +**Version:** 0.1.0 + +# 1. Purpose + +In certain deployments, client and server is seperated by a complex network, +hence we cannot assume +- The pushed configuration will not break connectivity to the network device. +- The network device have out-of-band access. + +This feature provides a way to auto rollback the applied configuration after a +centain duration if a bad configuration was pushed. + +# 2. Definition + +A `Commit` message is embedded the Extension message of the SetRequest proto. + +## 2.1 Proto + +``` +message Commit { + google.protobuf.Duration rollback_duration = 1; + bool confirm = 2; +} +``` + +## 2.2 SetRequest handling + +### 2.2.1 Commit +If the *rollback_duration* field is set in SetRequest RPC, the server shall commit the configuration and wait until the +specified duration to initiate a rollback of the configuration unless there is another SetRequest RPC with *confirm* set +to true. If the second call is not received with confirm set to true the server shall rollback the committed +configuration. + +### 2.2.2 Confirm + +During the *confirm* call the client should send the same configuration in the SetRequest spec along with +the *confirm* field set to true. + +If the confirm call is issued with a different configuration, a FAILED_PRECONDITION error is returned. + +The confirm call can only be issued if the server is waiting for confirmation. If a SetRequest RPC is received with the +*confirm* field set to true but the server is not waiting for a confirmation then an FAILED_PRECONDITION error is +returned. + +### 2.2.3 Multiple SetRequest + +If a subsequent SetRequest RPC is received with the *rollback_duration* field set, whilst an existing rollback counter +is running, the server shall return a FAILED_PRECONDITION error. + +If a SetRequest call is made without extension whilst the existing rollback counter is running then a +FAILED PRECONDITION error is returned. + From f4dad34afdeb2ad6b1d13fc7770739c79201f381 Mon Sep 17 00:00:00 2001 From: Gautham V Kidiyoor Date: Wed, 11 Oct 2023 11:58:53 -0700 Subject: [PATCH 2/7] Update gnmi-commit-confirmed.md as per #197 Updating the proposal as per the Proposal-1 of in [#197](https://github.com/openconfig/reference/issues/197) --- rpc/gnmi/gnmi-commit-confirmed.md | 58 ++++++++++++++++++++----------- 1 file changed, 37 insertions(+), 21 deletions(-) diff --git a/rpc/gnmi/gnmi-commit-confirmed.md b/rpc/gnmi/gnmi-commit-confirmed.md index 6493d2f..19c7238 100644 --- a/rpc/gnmi/gnmi-commit-confirmed.md +++ b/rpc/gnmi/gnmi-commit-confirmed.md @@ -16,43 +16,59 @@ hence we cannot assume This feature provides a way to auto rollback the applied configuration after a centain duration if a bad configuration was pushed. -# 2. Definition +# 2. Summary +The proposed proto has a subset of confirmed commit functionality as defined in +NETCONF protocol([RFC6241](https://datatracker.ietf.org/doc/html/rfc6241#section-8.4)). The proposal has a healthy disregard to few functionality +defined in the RFC with the intention that most of the gRPC API clients are going to +be automated systems and the proto should facilitate a simpler implementation of +client workflows and server implementation. + +The server can be viewed as a singleton resource, at any given point in time there +can be only one commit active. This commit can be either confirmed or canceled +before a new commit can begin. Client is expected to provide full configuration +during the commit request, the commit cannot be amended once issued. + +# 3. Definition A `Commit` message is embedded the Extension message of the SetRequest proto. -## 2.1 Proto +## 3.1 Proto ``` message Commit { google.protobuf.Duration rollback_duration = 1; - bool confirm = 2; + oneof id { + string commit_id = 2; + string confirm_id = 3; + string cancel_id = 4; + } } ``` -## 2.2 SetRequest handling +## 3.2 SetRequest handling -### 2.2.1 Commit -If the *rollback_duration* field is set in SetRequest RPC, the server shall commit the configuration and wait until the -specified duration to initiate a rollback of the configuration unless there is another SetRequest RPC with *confirm* set -to true. If the second call is not received with confirm set to true the server shall rollback the committed -configuration. +### 3.2.1 Commit +A commit can be initiated by setting the `rollback_duration` field and `commit_id` in the extension. +If `commit_id` is passed without `rollback_duration` a default duration of 10min is chosen. -### 2.2.2 Confirm +If the server is already waiting for a confirmation, the server returns with FAILED_PRECONDITION error. -During the *confirm* call the client should send the same configuration in the SetRequest spec along with -the *confirm* field set to true. +If `rollback_duration` is passed without `commit_id`, an INVALID_ARGUMENT error is returned. -If the confirm call is issued with a different configuration, a FAILED_PRECONDITION error is returned. +If a SetRequest call is made without extension whilst the existing rollback counter is running then a +FAILED PRECONDITION error is returned. -The confirm call can only be issued if the server is waiting for confirmation. If a SetRequest RPC is received with the -*confirm* field set to true but the server is not waiting for a confirmation then an FAILED_PRECONDITION error is -returned. +### 3.2.2 Confirm -### 2.2.3 Multiple SetRequest +Confirmation can be issued by setting the `confirm_id` to a value equivalent to the commit id of the +on-going commit which needs confirmation. -If a subsequent SetRequest RPC is received with the *rollback_duration* field set, whilst an existing rollback counter -is running, the server shall return a FAILED_PRECONDITION error. +If the server is not waiting for a confirmation or if the value doesn’t match the on-going commit then +FAILED_PRECONDITION or INVALID_ARGUMENT error is returned respectively. -If a SetRequest call is made without extension whilst the existing rollback counter is running then a -FAILED PRECONDITION error is returned. +### 3.2.3 Cancel +Cancellation can be issued by setting the `cancel_id` to a value equivalent to the commit id of the +on-going commit. +If the server is not waiting for a confirmation or if the value doesn’t match the on-going commit +then FAILED_PRECONDITION or INVALID_ARGUMENT error is returned respectively. From 3f8cce5dadce2d9829e52549a892aa180b46277e Mon Sep 17 00:00:00 2001 From: Gautham V Kidiyoor Date: Fri, 20 Oct 2023 13:27:20 -0700 Subject: [PATCH 3/7] Explicitly define oneof actions for concise client behavior Moving rollback_duration inside *CommitRequest* action eliminates wrong client usage of passing rollback_duration during confirm or cancel call. --- rpc/gnmi/gnmi-commit-confirmed.md | 59 ++++++++++++++++++++++--------- 1 file changed, 43 insertions(+), 16 deletions(-) diff --git a/rpc/gnmi/gnmi-commit-confirmed.md b/rpc/gnmi/gnmi-commit-confirmed.md index 19c7238..09d8d7c 100644 --- a/rpc/gnmi/gnmi-commit-confirmed.md +++ b/rpc/gnmi/gnmi-commit-confirmed.md @@ -35,40 +35,67 @@ A `Commit` message is embedded the Extension message of the SetRequest proto. ## 3.1 Proto ``` +// Commit confirmed extension allows automated revert of a configuration after +// certain duration if an explicit confirmation is not issued. This duration can +// be used to verify the configuration. +// It also allows explicit cancellation of the commit during the time window of rollback +// duration if client determine that the configuration needs to be reverted. +// The document about gNMI commit confirmed can be found at +// https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-commit-confirmed.md message Commit { - google.protobuf.Duration rollback_duration = 1; - oneof id { - string commit_id = 2; - string confirm_id = 3; - string cancel_id = 4; + oneof action { + CommitRequest commit = 1; + CommitConfirm confirm = 2; + CommitCancel cancel = 3; } } + +// Create a new commit request. +message CommitRequest { + // Commit id for the request. + string id = 1; + // Maximum duration to wait for a confirmaton before reverting the commit. + google.protobuf.Duration rollback_duration = 2; +} + +// Confirm an on-going commit. +message CommitConfirm { + // Commit id that requires confirmation. + string id = 1; +} + +// Cancel an on-going commit. +message CommitCancel { + // Commit id that requires cancellation. + string id = 1; +} ``` ## 3.2 SetRequest handling ### 3.2.1 Commit -A commit can be initiated by setting the `rollback_duration` field and `commit_id` in the extension. -If `commit_id` is passed without `rollback_duration` a default duration of 10min is chosen. - -If the server is already waiting for a confirmation, the server returns with FAILED_PRECONDITION error. +A commit can be initiated by setting `CommitRequest` as action in the extension. A commit `id` needs +to be provided which will be used during confirmation or cancellation. `rollback_duration` can be used +to override the default rollback duration which is 10min. If a confirmation call is not received before +the rollback duration then the configuration is reverted. -If `rollback_duration` is passed without `commit_id`, an INVALID_ARGUMENT error is returned. +If a commit is issued whilst an existing rollback counter is running then the server returns with +FAILED_PRECONDITION error. -If a SetRequest call is made without extension whilst the existing rollback counter is running then a +If a SetRequest call is made without extension whilst an existing rollback counter is running then a FAILED PRECONDITION error is returned. ### 3.2.2 Confirm -Confirmation can be issued by setting the `confirm_id` to a value equivalent to the commit id of the -on-going commit which needs confirmation. +Confirmation can be issued by setting `ConfirmRequest` as action in the extension. The value of `id` +should be equivalent to the commit id of the on-going commit which needs confirmation. If the server is not waiting for a confirmation or if the value doesn’t match the on-going commit then FAILED_PRECONDITION or INVALID_ARGUMENT error is returned respectively. ### 3.2.3 Cancel -Cancellation can be issued by setting the `cancel_id` to a value equivalent to the commit id of the -on-going commit. +Cancellation can be issued by setting `CancelRequest` as action in the extension. The value of `id` +should be equivalent to the commit id of the on-going commit which needs cancellation. -If the server is not waiting for a confirmation or if the value doesn’t match the on-going commit +If the server is not waiting for a cancellation or if the value doesn’t match the on-going commit then FAILED_PRECONDITION or INVALID_ARGUMENT error is returned respectively. From 876f98a197be338682e345f9c28b3f2f38f12c9b Mon Sep 17 00:00:00 2001 From: Gautham V Kidiyoor Date: Thu, 26 Oct 2023 11:01:40 -0700 Subject: [PATCH 4/7] Update gnmi-commit-confirmed.md --- rpc/gnmi/gnmi-commit-confirmed.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/rpc/gnmi/gnmi-commit-confirmed.md b/rpc/gnmi/gnmi-commit-confirmed.md index 09d8d7c..8c5faeb 100644 --- a/rpc/gnmi/gnmi-commit-confirmed.md +++ b/rpc/gnmi/gnmi-commit-confirmed.md @@ -50,9 +50,10 @@ message Commit { } } -// Create a new commit request. +// Create a new commit confirmed request. message CommitRequest { - // Commit id for the request. + // Commit id for the request. ID must be generated at the client side, it can be used + // to confirm or cancel the request without the rollback_duration interval. string id = 1; // Maximum duration to wait for a confirmaton before reverting the commit. google.protobuf.Duration rollback_duration = 2; @@ -60,13 +61,13 @@ message CommitRequest { // Confirm an on-going commit. message CommitConfirm { - // Commit id that requires confirmation. + // Commit id of the on-going commit that requires confirmation. string id = 1; } // Cancel an on-going commit. message CommitCancel { - // Commit id that requires cancellation. + // Commit id of the on-going commit that requires cancellation. string id = 1; } ``` From 45bcbcd88b132364589dae59a413927c35c436b8 Mon Sep 17 00:00:00 2001 From: Gautham V Kidiyoor Date: Thu, 2 Nov 2023 11:51:07 -0700 Subject: [PATCH 5/7] Update gnmi-commit-confirmed.md --- rpc/gnmi/gnmi-commit-confirmed.md | 72 ++++++++++++++++--------------- 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/rpc/gnmi/gnmi-commit-confirmed.md b/rpc/gnmi/gnmi-commit-confirmed.md index 8c5faeb..73dff1e 100644 --- a/rpc/gnmi/gnmi-commit-confirmed.md +++ b/rpc/gnmi/gnmi-commit-confirmed.md @@ -1,6 +1,6 @@ # gNMI Commit Confirmed Extension -**Contributors:** Gautham V Kidiyoor, Rob Shakir, Vinit Kanvinde, Priyadeep Bangalore Lokesh +**Contributors:** Gautham V Kidiyoor, Roman Dodin, Rob Shakir, Vinit Kanvinde, Priyadeep Bangalore Lokesh **Date:** September 20, 2023 @@ -35,50 +35,54 @@ A `Commit` message is embedded the Extension message of the SetRequest proto. ## 3.1 Proto ``` -// Commit confirmed extension allows automated revert of a configuration after -// certain duration if an explicit confirmation is not issued. This duration can -// be used to verify the configuration. -// It also allows explicit cancellation of the commit during the time window of rollback -// duration if client determine that the configuration needs to be reverted. +// Commit confirmed extension allows automated revert of the configuration after +// certain duration if an explicit confirmation is not issued. It allows explicit +// cancellation of the commit during the rollback window. There cannot be more +// than one commit active at a given time. // The document about gNMI commit confirmed can be found at // https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-commit-confirmed.md message Commit { + // ID is provided by the client during the commit request. During confirm and cancel + // actions the provided ID should match the ID provided during commit. + // If ID is not passed in any actions server shall return error. + // Required. + string id = 1; oneof action { - CommitRequest commit = 1; - CommitConfirm confirm = 2; - CommitCancel cancel = 3; + // commit action creates a new commit. If a commit is on-going, server returns error. + CommitRequest commit = 2; + // confirm action will confirm an on-going commit, the ID provided during confirm + // should match the on-going commit ID. + CommitConfirm confirm = 3; + // cancel action will cancel an on-going commit, the ID provided during cancel + // should match the on-going commit ID. + CommitCancel cancel = 4; } } -// Create a new commit confirmed request. +// CommitRequest is used to create a new confirmed commit. It hold additional +// parameter requried for commit action. message CommitRequest { - // Commit id for the request. ID must be generated at the client side, it can be used - // to confirm or cancel the request without the rollback_duration interval. - string id = 1; // Maximum duration to wait for a confirmaton before reverting the commit. - google.protobuf.Duration rollback_duration = 2; + google.protobuf.Duration rollback_duration = 1; } -// Confirm an on-going commit. -message CommitConfirm { - // Commit id of the on-going commit that requires confirmation. - string id = 1; -} +// CommitConfirm is used to confirm an on-going commit. It hold additional +// parameter requried for confirm action. +message CommitConfirm {} -// Cancel an on-going commit. -message CommitCancel { - // Commit id of the on-going commit that requires cancellation. - string id = 1; -} +// CommitCancel is used to cancel an on-going commit. It hold additional +// parameter requried for cancel action. +message CommitCancel {} ``` ## 3.2 SetRequest handling ### 3.2.1 Commit -A commit can be initiated by setting `CommitRequest` as action in the extension. A commit `id` needs -to be provided which will be used during confirmation or cancellation. `rollback_duration` can be used -to override the default rollback duration which is 10min. If a confirmation call is not received before -the rollback duration then the configuration is reverted. +A commit can be initiated by providing `CommitRequest` as action in the extension. A `id` must to be +provided by the client. The server shall associate the commit with the provided `id`. +During confirm or cancel action the provided `id` must match the `id` of the on-going commit. +`rollback_duration` can be used to override the default rollback duration which is 10min. +If a confirmation call is not received before the rollback duration then the configuration is reverted. If a commit is issued whilst an existing rollback counter is running then the server returns with FAILED_PRECONDITION error. @@ -88,15 +92,15 @@ FAILED PRECONDITION error is returned. ### 3.2.2 Confirm -Confirmation can be issued by setting `ConfirmRequest` as action in the extension. The value of `id` -should be equivalent to the commit id of the on-going commit which needs confirmation. +Confirmation can be issued by providing `ConfirmRequest` as action in the extension. The value of `id` +should be equivalent to the `id` of the on-going commit. -If the server is not waiting for a confirmation or if the value doesn’t match the on-going commit then +If the server is not waiting for confirmation or if the value doesn’t match the on-going commit then FAILED_PRECONDITION or INVALID_ARGUMENT error is returned respectively. ### 3.2.3 Cancel -Cancellation can be issued by setting `CancelRequest` as action in the extension. The value of `id` -should be equivalent to the commit id of the on-going commit which needs cancellation. +Cancellation can be issued by providing `CancelRequest` as action in the extension. The value of `id` +should be equivalent to the id of the on-going commit. -If the server is not waiting for a cancellation or if the value doesn’t match the on-going commit +If the server is not waiting for cancellation or if the value doesn’t match the on-going commit then FAILED_PRECONDITION or INVALID_ARGUMENT error is returned respectively. From 4377df2c18ee9cfee82180e30f007638d2a58e5e Mon Sep 17 00:00:00 2001 From: Gautham V Kidiyoor Date: Tue, 21 Nov 2023 11:08:31 -0800 Subject: [PATCH 6/7] Update gnmi-commit-confirmed.md --- rpc/gnmi/gnmi-commit-confirmed.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/rpc/gnmi/gnmi-commit-confirmed.md b/rpc/gnmi/gnmi-commit-confirmed.md index 73dff1e..dae8683 100644 --- a/rpc/gnmi/gnmi-commit-confirmed.md +++ b/rpc/gnmi/gnmi-commit-confirmed.md @@ -81,10 +81,13 @@ message CommitCancel {} A commit can be initiated by providing `CommitRequest` as action in the extension. A `id` must to be provided by the client. The server shall associate the commit with the provided `id`. During confirm or cancel action the provided `id` must match the `id` of the on-going commit. -`rollback_duration` can be used to override the default rollback duration which is 10min. -If a confirmation call is not received before the rollback duration then the configuration is reverted. -If a commit is issued whilst an existing rollback counter is running then the server returns with +`rollback_duration` can be used to override the default rollback duration. In JSON format, the Duration +type is encoded as a string rather than an object where the string ends in the suffix "s" (indicating +seconds) Eg. "10s". object Server should maintain a default 10 minutes duration when `rollback_duration` is not present in the request. If a confirmation +call is not received before the rollback duration then the configuration is reverted. + +If a `CommitRequest` is issued whilst an existing rollback counter is running then the server returns with FAILED_PRECONDITION error. If a SetRequest call is made without extension whilst an existing rollback counter is running then a From 43af74f277781d79689da6990ce8245f703f8770 Mon Sep 17 00:00:00 2001 From: Gautham V Kidiyoor Date: Tue, 21 Nov 2023 11:09:16 -0800 Subject: [PATCH 7/7] Update gnmi-commit-confirmed.md --- rpc/gnmi/gnmi-commit-confirmed.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rpc/gnmi/gnmi-commit-confirmed.md b/rpc/gnmi/gnmi-commit-confirmed.md index dae8683..80aaa47 100644 --- a/rpc/gnmi/gnmi-commit-confirmed.md +++ b/rpc/gnmi/gnmi-commit-confirmed.md @@ -84,8 +84,9 @@ During confirm or cancel action the provided `id` must match the `id` of the on- `rollback_duration` can be used to override the default rollback duration. In JSON format, the Duration type is encoded as a string rather than an object where the string ends in the suffix "s" (indicating -seconds) Eg. "10s". object Server should maintain a default 10 minutes duration when `rollback_duration` is not present in the request. If a confirmation -call is not received before the rollback duration then the configuration is reverted. +seconds) Eg. "10s". object Server should maintain a default 10 minutes duration when `rollback_duration` +is not present in the request. If a confirmation call is not received before the rollback duration then +the configuration is reverted. If a `CommitRequest` is issued whilst an existing rollback counter is running then the server returns with FAILED_PRECONDITION error.