From c8eabd53a9b3fa0fcd4fada9d561c5b5ad9f736b Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Fri, 28 Feb 2020 13:54:55 -0600 Subject: [PATCH 1/2] Clarify pending status, introduce running The current definition for the pending (previously underway) status is difficult to understand when it is acceptable to use and what it really means about the state of the installation. It's described as both a long term state and temporary. It is also described as "to be avoided". We would like to redefine the state to make it more clear on what the state means, and to make it acceptable for tools to use. Pending now means that the operation has been requested (most likely queued) but has not begun executing. Tools that are immediately executing commands as they are issued would most likely choose to not use this state. However solutions that accept bundle operations from many users at once, for example a cnab operator, may choose to use this state. This also introduces a new state: running. Tools may use this state to indicate that a bundle is currently executing an operation. This can be used by tools to provide operational insight into the activity of the system. For example, when an upgrade takes 30 minutes and people don't know that it's already running, it could easily be initiated more than once by multiple people on the same installation. Allowing tools to make the current status of the installation visible, helps avoid this situation. Signed-off-by: Carolyn Van Slyck --- 400-claims.md | 9 +++++---- schema/claim.schema.json | 1 + 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/400-claims.md b/400-claims.md index 48839b5c..5a56a243 100644 --- a/400-claims.md +++ b/400-claims.md @@ -98,10 +98,11 @@ The fields above are defined as follows: - `revision` (REQUIRED): An [ULID](https://github.com/ulid/spec) that MUST change each time the claim is modified. It MUST NOT change when a [non-modifying operation](https://github.com/cnabio/cnab-spec/blob/master/101-bundle-json.md#custom-actions) is performed on an installation. - `started` (OPTIONAL): A timestamp indicating when execution of the operation started. - `status` (REQUIRED): Indicates the status of the last phase transition. Valid statuses are: - - `failure`: failed before completion - - `pending`: in progress. This should only be used if the invocation container MUST exit before it can determine whether all operations are complete. Note that `pending` is a _long term status_ that indicates that the installation's final state cannot be determined by the system. For this reason, it should be avoided. When used, `pending` should be considered a temporary status, and the runtime SHOULD work to resolve this to either `failure` or `success`. - - `unknown`: the state is unknown. This is an error condition. - - `success`: completed successfully + - `failure`: Failed before completion. + - `pending`: Execution has been requested and has not begun. + - `running`: Execution is in progress and has not completed. + - `unknown`: The state is unknown. This is an error condition. + - `success`: Completed successfully. - `stopped` (OPTIONAL): A timestamp indicating when the execution of the operation stopped. > Note that credential data is _never_ stored in a claim. For this reason, a claim is not considered _trivially repeatable_. Credentials MUST be supplied on each action. Implementations of the claims specification are expected to retrieve the credential requirements from the `bundle` field. diff --git a/schema/claim.schema.json b/schema/claim.schema.json index a7685cde..2698bdab 100644 --- a/schema/claim.schema.json +++ b/schema/claim.schema.json @@ -29,6 +29,7 @@ "failure", "success", "pending", + "running", "unknown" ], "type": "string" From fbbed9e006a53c38eff1ef87c74c7ee071e6bad6 Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Mon, 2 Mar 2020 11:40:53 -0600 Subject: [PATCH 2/2] Clarify that running and pending are temporary still. Signed-off-by: Carolyn Van Slyck --- 400-claims.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/400-claims.md b/400-claims.md index 5a56a243..110e1b51 100644 --- a/400-claims.md +++ b/400-claims.md @@ -99,8 +99,8 @@ The fields above are defined as follows: - `started` (OPTIONAL): A timestamp indicating when execution of the operation started. - `status` (REQUIRED): Indicates the status of the last phase transition. Valid statuses are: - `failure`: Failed before completion. - - `pending`: Execution has been requested and has not begun. - - `running`: Execution is in progress and has not completed. + - `pending`: Execution has been requested and has not begun. This should be considered a temporary status, and the runtime SHOULD work to resolve this to either `failure` or `success`. + - `running`: Execution is in progress and has not completed. This should be considered a temporary status, and the runtime SHOULD work to resolve this to either `failure` or `success`. - `unknown`: The state is unknown. This is an error condition. - `success`: Completed successfully. - `stopped` (OPTIONAL): A timestamp indicating when the execution of the operation stopped.