This is an automated email from the ASF dual-hosted git repository. heneveld pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
commit f10501afcdfdf7f5d4c58fe13f8b241223e3ce1e Author: Alex Heneveld <[email protected]> AuthorDate: Mon Oct 31 17:02:36 2022 +0000 add new step types and minor other changes/details --- guide/blueprints/workflow/common.md | 16 +++++------ .../ansible-bash/example-ansible-and-bash.yaml | 2 +- guide/blueprints/workflow/steps/steps.yaml | 33 ++++++++++++++++++++++ guide/blueprints/workflow/variables.md | 15 ++++++---- 4 files changed, 52 insertions(+), 14 deletions(-) diff --git a/guide/blueprints/workflow/common.md b/guide/blueprints/workflow/common.md index 9953c67b..3edb99a6 100644 --- a/guide/blueprints/workflow/common.md +++ b/guide/blueprints/workflow/common.md @@ -40,11 +40,11 @@ steps: ``` Shorthand can be combined as part of a map by providing the step shorthand string in a key -`s` (or `shorthand`). The type must be included as the first word, and the `type` key must not be used. +`step` (or `s` or `shorthand`). The type must be included as the first word, and the `type` key must not be used. ``` steps: -- s: ssh echo today is `DATE` +- step: ssh echo today is `DATE` condition: target: ${scratch.skip_date} not: { equals: true } @@ -103,13 +103,13 @@ steps: target: ${scratch.skip_date} equals: true -- s: ssh echo today is `date` +- step: ssh echo today is `date` name: Doing SSH next: end - id: skipping-ssh-date name: Not doing SSH - s: log skipping ssh date command + step: log skipping ssh date command ``` @@ -122,24 +122,24 @@ It is also possible to customize the output from a step using an `output` block. For example: ``` -- s: let target = aws +- step: let target = aws condition: target: location tag: aws next: picked-target -- s: let target = azure +- step: let target = azure condition: target: location tag: azure next: picked-target - input: location_name: ${entity.location.name} - s: log Unrecognized cloud ${location_name}, using default + step: log Unrecognized cloud ${location_name}, using default output: cloud: default next: end - id: picked-target - s: log Picked target ${target} + step: log Picked target ${target} output: cloud: ${target} ``` diff --git a/guide/blueprints/workflow/examples/ansible-bash/example-ansible-and-bash.yaml b/guide/blueprints/workflow/examples/ansible-bash/example-ansible-and-bash.yaml index b95f7661..0df75e9d 100644 --- a/guide/blueprints/workflow/examples/ansible-bash/example-ansible-and-bash.yaml +++ b/guide/blueprints/workflow/examples/ansible-bash/example-ansible-and-bash.yaml @@ -47,7 +47,7 @@ services: - set-sensor main.uri = http://${entity.sensor['host.address']}/ checkRunning.workflow: steps: - - s: http ${entity.sensor['main.uri']} + - step: http ${entity.sensor['main.uri']} timeout: 10s on-error: - return false diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml index 835aef36..1e5e0a7f 100644 --- a/guide/blueprints/workflow/steps/steps.yaml +++ b/guide/blueprints/workflow/steps/steps.yaml @@ -67,6 +67,39 @@ the value once available if a `variable` is not being set, or if a variable is being set either the output from the previous step or null if this is the first step + - name: fail + summary: Fails the workflow, throwing an exception which can be handled by an `on-error` block or returned to the user + shorthand: '`fail [ "rethrow" ] [ "message" MESSAGE ]`' + input: | + * `message`: a string to report in the exception + * `rethrow`: whether to include any error in scope (if being used within an `on-error` step) + output: _none_ (throws exception) + + - name: retry + summary: Retries from an appropriate point with a configurable delay and back-off + shorthand: '`retry [ "replay" ] [ "from" NEXT ] [ "limit" LIMIT_COUNT [ "in" LIMIT_TIME ] ] [ "backoff" BACKOFF ] [ "timeout" TIMEOUT ]`' + input: | + * `replay`: whether to replay or not; XXX + * `limit`: a list of limit definitions, e.g. `[ "10", "2 in 1 min" ]` to restrict to 10 retries total with + an additional limit of 2 in any 1 minute period; as shorthand, per the syntax above, it takes one such limit + * `backoff`: a specification of how to delay, of the form `INITIAL [ "increasing" FACTOR ] [ "up to" MAX ]`, + where `INITIAL` is one or more durations applied to the respective iteration, and the last value applying to all + unless `FACTOR` is supplied; `FACTOR` as either a number followed by `x` to multiply, a number followed by by `%` to add a percentage each time, + or a duration to increase linearly; and `MAX` to specify a maximum duration; for example, + `backoff 1s 1s 10s` will retry after 1 second the first two times, then after 10 seconds on subsequent instances; + and `backoff 1s 2s backoff 3x max 1m` will retry after 1 second then 2s then 6s then 18s then 54s then 60s each subsequent time + * `key`: an optional key to identify related retries in a workflow; all retry blocks with the same `key` will share counts + for the purpose of counting limits, although the limits themselves are as per the definition in each retry block + * `next` and `timeout` per the [common](../common.md) step properties + output: the output from the previous step, or null if this is the first step + + - name: goto + summary: Moves execution to another step indicated by its ID + shorthand: '`goto NEXT`' + input: | + * `next` per the [common](../common.md) step properties + output: the output from the previous step, or null if this is the first step + - name: workflow summary: | Runs nested workflow, optionally over an indicated target. diff --git a/guide/blueprints/workflow/variables.md b/guide/blueprints/workflow/variables.md index 835c89cc..fcd6061f 100644 --- a/guide/blueprints/workflow/variables.md +++ b/guide/blueprints/workflow/variables.md @@ -13,7 +13,7 @@ For example, you can write: - log Starting workflow: ${workflow.name} - let integer x = 1 - id: log - s: log The value for x is now ${x} + step: log The value for x is now ${x} - let x = ${x} + 1 next: log condition: @@ -107,13 +107,18 @@ so it is a bad idea to call a workflow variable `workflow`, as an attempt to eva (You could still access such a variable, using `${workflow.var.workflow}`.) -### Evaluation for `let` and `wait` +### Unavailable Variables and `let ... ??` -It is an error if a variable not available or is null, including access to a sensor which has not yet been published. +To guard against mistakes in variable names or state, workflow execution will typically throw an error if +a referenced variable is unavailable or null, including access to a sensor which has not yet been published. +There are three exceptions: -You can cause workflow to block until a sensor becomes available using the `wait` step. +* the `let` step supports the `??` operator for this case, as described below below +* the `wait` step will block until a sensor becomes available +* `condition` blocks can reference a null or unavailable value in the `target`, + and check for absence using `when: absent_or_null` -Where it is necessary to allow a null value or a potentially unavilable variable, +Where it is necessary to allow a null value or a potentially unavilable variable in other contexts, the "nullish coalescing" operator `??` can be used within `let` statements: ```
