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
The following commit(s) were added to refs/heads/master by this push:
new 7b36b313 describe workflow-entity and set-sensor name[item]
7b36b313 is described below
commit 7b36b3137ed722166bcc4c4214b4f22ddc9a2b01
Author: Alex Heneveld <[email protected]>
AuthorDate: Tue Dec 6 15:23:02 2022 +0000
describe workflow-entity and set-sensor name[item]
---
guide/blueprints/workflow/defining.md | 135 +++++++++++++++++++++++++++--
guide/blueprints/workflow/steps/steps.yaml | 6 +-
guide/blueprints/workflow/variables.md | 2 +
3 files changed, 134 insertions(+), 9 deletions(-)
diff --git a/guide/blueprints/workflow/defining.md
b/guide/blueprints/workflow/defining.md
index c674fb31..d848a619 100644
--- a/guide/blueprints/workflow/defining.md
+++ b/guide/blueprints/workflow/defining.md
@@ -5,7 +5,7 @@ layout: website-normal
Let's start by discussing _why_ workflow is introduced and where it can and
should be used.
-The Apache Brooklyn Workflow is designed to make it easy to describe behaviour
of effectors, sensors, and policies in blueprints.
+The Apache Brooklyn Workflow is designed to make it easy to describe behaviour
of entities, effectors, sensors, and policies in blueprints.
It has the sophistication of a programming language including [conditions,
loops, and error-handling](common.md) and [variables](variables.md),
but more important are the [steps](steps/) which delegate to other systems,
such as containers or SSH or HTTP endpoints.
@@ -125,13 +125,134 @@ The `steps` must also be defined, as per above,
and the same common configuration is supported.
+### Initializer
+
+A workflow can be made to run when an entity is created using a
`workflow-initializer`.
+This can do any custom entity setup, including the above tasks using
`add-policy` or `apply-initializer` steps,
+as follows:
+
+```
+- type: some-entity
+ brooklyn.initializers:
+ - type: workflow-initializer
+ brooklyn.config:
+ name: initializer-to-say-hi-then-add-effector-and-sensor
+ steps:
+ - log Hi this workflow initializer will run at entity creation
+ - step: add-policy
+ blueprint:
+ type: workflow-policy
+ brooklyn.config:
+ name: invoke-effector-other_sensor-is-published
+ triggers:
+ - other_sensor
+ steps:
+ - invoke-effector say-hi-and-publish-sensor
+ - step: apply-initializer
+ blueprint:
+ type: workflow-effector
+ brooklyn.config:
+ name: say-hi-and-publish-sensor
+ steps:
+ - log Hi
+ - set-sensor boolean said_hi = true
+```
+
+The `workflow-initializer` takes the same config as `workflow-effector` with
the exception of `parameters`.
+
+
+### Workflow Entities
+
+New entities can be written to use workflow for their start and stop behavior
by extending the
+type `workflow-entity`. This requires a `start` and `stop` configuration to
be supplied
+defining the workflow for those steps. Optionally `restart` can be supplied,
which if omitted
+will default to stopping then starting.
+
+```
+- type: workflow-entity
+ brooklyn.config:
+ start:
+ steps:
+ - log Starting up
+ stop:
+ steps:
+ - log Stopping
+```
+
+The `workflow-entity` will automatically set the `service.isUp` and
`service.state` sensors
+based on invocation of `start` and `stop` and the success of the workflow.
+
+It will also take into consideration the map sensors `service.problems` and
`service.notUp.indicators`,
+where any entry in the former will cause `service.state` to show as "on-fire"
if it is meant to be running,
+and any entry in the latter will cause `service.isUp` to become false (which
will trigger an
+entry in `service.problems` if it is meant to be running). Thus liveness and
health checks can,
+and often should, be added, such as in the following getting the `status_code`
from the `main.uri`,
+and setting a `service.problems` if it is unavailable:
+
+```
+- type: workflow-entity
+ brooklyn.config:
+ start:
+ steps:
+ - ... # start the service, e.g. using container or http call
+
+ - clear-sensor status_code
+ - set-sensor main.uri = ... # get the URL from the previous; this
will trigger sensor feed
+ - step: wait ${entity.sensor.status_code}
+ timeout: 5m
+ stop:
+ # omitted
+
+ brooklyn.initializers:
+ - type: workflow-sensor
+ brooklyn.config:
+ sensor: status_code
+ period: 1m
+ triggers:
+ - main.uri
+ steps:
+ - step: http ${main.uri}
+ on-error:
+ - set-sensor service.problems['endpoint-live'] = ${error}
+ - fail rethrow message Endpoint is not accessible
+ - clear-sensor service.problems['endpoint-live']
+ - return ${status_code}
+```
+
+The workflow entity does not automatically start or stop children.
+If this is required, it should be part of the start/stop workflow, as follows:
+
+```
+- type: workflow-entity
+ brooklyn.config:
+ start:
+ steps:
+ - ... # start this
+ # now start children
+ - type: workflow
+ target: children
+ steps:
+ - invoke-effector start
+
+ stop:
+ steps:
+ # stop children first
+ - type: workflow
+ target: children
+ steps:
+ - invoke-effector stop
+ - ... # then stop this
+```
+
+
### Workflow Software Process Entities
-Entities that run software or another machine-based process can be defined
using workflow for the
-install, customize, launch, check-running, and stop phases.
-These entities will provision a machine if required (e.g. if given a cloud or
machine provisioning
-location, rather than a machine), and use the same latches and pre/post phase
on-box commands,
-but for the key phases it will take a `workflow` object including at minimum
`steps`.
+Entities that run software or another machine-based process can also be
defined,
+relying on Apache Brooklyn to provision a machine if required, then
+using workflow for the install, customize, launch, check-running, and stop
phases.
+These entities will provision a machine if if given a cloud or machine
provisioning
+location, and use the same latches and pre/post phase on-box commands as the
ofther `SoftwareProcess` entities,
+but for the key phases it will take a `workflow` object as for
`workflow-entity`.
The `steps` will often run `ssh` and possibly `set-sensor`, and
they can access the run dir and install dir using Freemarker
@@ -147,7 +268,7 @@ Brooklyn's automatic PID detection can be used.
As an example:
```
-- type: org.apache.brooklyn.entity.software.base.WorkflowSoftwareProcess
+- type: workflow-software-process
brooklyn.config:
install.workflow:
steps:
diff --git a/guide/blueprints/workflow/steps/steps.yaml
b/guide/blueprints/workflow/steps/steps.yaml
index 70abdfba..ebc5f725 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -342,7 +342,8 @@
* `sensor`: either a string, being the sensor name, or a map,
containing the `name` and
optionally the `type` (defaulting to the declared type of the
sensor, if present, or to `Object`)
and/or the `entity` where the sensor should be set (defaulting to
the entity where the workflow is running);
- the value will be coerced to the given type, e.g. to force
conversion to an integer or to a bean registered type
+ the value will be coerced to the given type, e.g. to force
conversion to an integer or to a bean registered type;
+ if the `name` contains bracketed portions, these are treated as keys
in a map or positions in list to be set
* `value`: the value to set
* `require`: a condition to evaluate against the sensor value while
holding the lock on the sensor,
used to enable atomic operations similar to the `lock` workflow
setting
@@ -362,7 +363,8 @@
shorthand: '`clear-sensor [TYPE] SENSOR_NAME`'
input: |
* `sensor`: a string being the sensor name or a map containing the
`name` and
- optionally the `entity` where the sensor should be cleared
(defaulting to the entity where the workflow is running)
+ optionally the `entity` where the sensor should be cleared
(defaulting to the entity where the workflow is running);
+ as with `set-sensor`, the `name` can include bracketed portions to
remove an entry from a map or list
output: the output from the previous step, or null if this is the first
step
- name: deploy-application
diff --git a/guide/blueprints/workflow/variables.md
b/guide/blueprints/workflow/variables.md
index 8065dae4..b1121e10 100644
--- a/guide/blueprints/workflow/variables.md
+++ b/guide/blueprints/workflow/variables.md
@@ -57,6 +57,8 @@ The interpolated reference `${workflow.<KEY>}` can be used to
access workflow in
* `error_handler.<KEY>` - info on the current error handler, as above, if in
an on-error step
* `step.<ID>.<KEY>` - info on the last invocation of the step with declared
`id` matching `<ID>`, as above
* `var.<VAR>` - return the value of `<VAR>` which should be a workflow-scoped
variable (set with `let`)
+* `util.<UTIL>` - access a utility pseudo-variable, either `random` for a
random between 0 and 1,
+ `now` for milliseconds since 1970, `now_iso` for ISO 8601 date string,
`now_nice` or `now_stamp` for a human readable date format
In the step contexts, the following is also supported after `workflow.`:
