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 1ee04f0f2913ea6546df05ee492b4b090f26ed24 Author: Alex Heneveld <[email protected]> AuthorDate: Mon Oct 31 16:31:17 2022 +0000 add indices for workflow steps --- _plugins/jsonball.rb | 55 +++-- guide/blueprints/workflow/index.md | 4 +- guide/blueprints/workflow/nested-workflow.md | 2 +- guide/blueprints/workflow/steps/index.md | 325 ++++----------------------- guide/blueprints/workflow/steps/steps.yaml | 271 ++++++++++++++++++++++ style/css/_util.scss | 6 + 6 files changed, 360 insertions(+), 303 deletions(-) diff --git a/_plugins/jsonball.rb b/_plugins/jsonball.rb index c12a4413..163eafb4 100644 --- a/_plugins/jsonball.rb +++ b/_plugins/jsonball.rb @@ -43,12 +43,16 @@ require 'json' # then e.g. {% for record in jsonball %} {{ record.name }} {% endfor %} # to print out all the name entries (or build a fancy TOC sidebar) -# and finally, if that json file might itself contain liquid tags, +# if that json file might itself contain liquid tags, # or need jekylling, treat it as a page and it will get jekylled # (we use this for toc.json reading from subdirs' toc.json files): # # {% jsonball foo from page toc.json %} +# YAML is support by inserting the keyword 'yaml' after from +# +# {% jsonball foo from yaml data { a: "b" } %} + module JekyllJsonball class JsonballTag < Liquid::Tag @@ -74,27 +78,50 @@ module JekyllJsonball context[$1] = JSON jekylled_page_relative_file_contents(context, $2.strip) return '' end + + if /(.+) from yaml var (.+)/.match(@text) + context[$1] = YAML.load( context[$2] ) + return '' + end + if /(.+) from yaml data (.+)/.match(@text) + context[$1] = YAML.load( $2 ) + return '' + end + if /(.+) from yaml file (.+)/.match(@text) + context[$1] = YAML.load( page_relative_file_contents(context, $2.strip) ) + return '' + end + if /(.+) from yaml page (.+)/.match(@text) + context[$1] = YAML.load( jekylled_page_relative_file_contents(context, $2.strip) ) + return '' + end + # syntax error return 'ERROR:bad_jsonball_syntax' end def page_relative_file_contents(context, filename) - jekyllSite = context.registers[:site] - dir = jekyllSite.source+'/'+File.dirname(context['page']['url']) - filename = context[filename] || filename - if !filename.match(/\/.*/) - filename = dir + '/' + filename - end - file = File.open(filename, "rb") - return file.read + jekyllSite = context.registers[:site] + dir = jekyllSite.source+'/'+dirname(context['page']['url']) + filename = context[filename] || filename + if !filename.match(/\/.*/) + filename = dir + '/' + filename + end + file = File.open(filename, "rb") + return file.read + end + + def dirname(path) + return path if path.end_with?("/") + return File.dirname(path) end def jekylled_page_relative_file_contents(context, filename) - jekyllSite = context.registers[:site] - filename = context[filename] || filename - targetPage = Jekyll::Page.new(jekyllSite, jekyllSite.source, File.dirname(context['page']['url']), filename) - targetPage.render(jekyllSite.layouts, jekyllSite.site_payload) - targetPage.output + jekyllSite = context.registers[:site] + filename = context[filename] || filename + targetPage = Jekyll::Page.new(jekyllSite, jekyllSite.source, File.dirname(context['page']['url']), filename) + targetPage.render(jekyllSite.layouts, jekyllSite.site_payload) + targetPage.output end end diff --git a/guide/blueprints/workflow/index.md b/guide/blueprints/workflow/index.md index 8a84c90e..9683020b 100644 --- a/guide/blueprints/workflow/index.md +++ b/guide/blueprints/workflow/index.md @@ -5,7 +5,7 @@ layout: website-normal children: - defining.md - common.md -- steps.md +- steps/ - variables.md - nested-workflow.md - examples/ @@ -27,6 +27,6 @@ brooklyn.initializers: This can be used within [most Apache Brooklyn resources](defining.md). The syntax supports [longhand, conditions, loops, error-handling](common.md), [variables](variables.md), -a large set of [built-in step types](steps.md), and the ability to [define custom step types](nested-workflow.md). +a large set of [built-in step types](steps/), and the ability to [define custom step types](nested-workflow.md). You can also get started by looking at a variety [examples](examples/). diff --git a/guide/blueprints/workflow/nested-workflow.md b/guide/blueprints/workflow/nested-workflow.md index 58bcf752..77c11482 100644 --- a/guide/blueprints/workflow/nested-workflow.md +++ b/guide/blueprints/workflow/nested-workflow.md @@ -4,7 +4,7 @@ layout: website-normal --- The `type: workflow` can be used to create new step types and save them to the Brooklyn type registry. -New step types can be used in the same way as the [standard step types](steps.md). +New step types can be used in the same way as the [standard step types](steps/). This allows common workflow logic to be saved and re-used as steps in other workflow. The usual properties of steps -- inputs, outputs, error handling -- are all supported, and it supports defining parameters and even custom shorthand templates. diff --git a/guide/blueprints/workflow/steps/index.md b/guide/blueprints/workflow/steps/index.md index 89b646b1..458d1d74 100644 --- a/guide/blueprints/workflow/steps/index.md +++ b/guide/blueprints/workflow/steps/index.md @@ -1,317 +1,70 @@ --- title: Workflow Steps layout: website-normal +children: +- { section: Workflow Control } +- { section: External Actions } +- { section: Application Models } +- { section: General Purpose } +- { section: Index of Step Types } --- +{% jsonball steps from yaml file steps.yaml %} +{% assign step_summaries = "" | split: ", " %} -### clear-config +{% for x in steps %} -Clears the value of a config key on an entity. +{% assign step_summaries = step_summaries | concat: x.steps %} -**Shorthand**: `clear-config [TYPE] CONFIG_KEY_NAME` +## {{ x.section_name }} -**Input parameters**: -* `config`: a string being the config key name or a map containing the `name` and - optionally the `entity` where the config should be set (defaulting to the entity where the workflow is running) - -**Output return value**: the output from the previous step, or null if this is the first step - - -### clear-sensor - -Clears the value of a sensor on an entity. - -**Shorthand**: `clear-sensor [TYPE] SENSOR_NAME` - -**Input parameters**: -* `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) - -**Output return value**: the output from the previous step, or null if this is the first step - - -### clear-workflow-variable - -Clears the value of a workflow internal variable. - -**Shorthand**: `clear-workflow-variable [TYPE] VARIABLE_NAME` - -**Input parameters**: -* `variable`: a string being the workflow variable name or a map containing the `name` - of the workflow variable which should be cleared - -**Output return value**: the output from the previous step, or null if this is the first step +{{ x.section_intro }} -### container +<div class="no-space-in-list" markdown="1" style="margin-top: 0; margin-bottom: 42px;"> + {% for step in x.steps %} +* [`{{ step.name }}`](#{{ step.name }}) + {% endfor %} -Runs a container with optional command and environment variables. +</div> -**Shorthand**: `container IMAGE [ COMMAND ]` -**Input parameters**: -* `image`: the image to run -* Optionally a command to pass to the image, at most one of: - * `command`: a command or script as a string, to pass to bash to be run - * `commands`: a list of commands to pass to bash to be run - * `raw-command`: a list containing the base executable in the first entry and any arguments as additional entries -* `env`: a map of string keys with values whose JSON is taken and passed to the command be executed -* `exit-code`: the word `any`, a number, or a predicate DSL expression (e.g. `less-than: 32`) - to require of the exit status code from the command, defaulting to `0` -* `pull-policy`: one of `IfNotPresent`, `Always`, or `Never`, whether to pull the image before running; - defaults to `IfNotPresent` + {% for step in x.steps %} -**Output return value**: -* `stdout` -* `stderr` -* `exit_code` +### `{{ step.name }}` +{{ step.summary }} -### http - -Sends an HTTPS (or HTTP) request and returns the response content and code. - -**Shorthand**: `http ENDPOINT` +{% if step.shorthand %} +**Shorthand**: {{ step.shorthand }} +{% endif %} +{% if step.input %} **Input parameters**: -* `endpoint`: the URL to connect to, optionally omitting the protocol and slash prefix if `https://` is intended - (e.g. just the host and any path); per URL standard any unusual characters such as query parameters should be URL-encoded, - so if e.g. passing parameters containing spaces, `params` should be used instead of `host/path?param=${value}` -* `query`: a map of query parameters to URL encode and add to the URL -* `body`: an object to be serialized and sent as the body (or just set as body if it is an array of bytes) -* `charset`: the character set to use to convert between byte arrays and strings for the request body and response content; - not applied if `body` is already a byte array, and not applied to the `content_bytes` output; - defaults to the system default -* `status-code`: the word `any`, a number, or a predicate DSL expression to require of the response status code, - defaulting to `{ less-than: 400, greater-than-or-equal-to: 200 }` -* `headers`: a map of header key-values to set on the request -* `method`: the HTTP method for the request, defaulting to `get` -* `username` and `password`: credentials to set on the request, e.g. for Basic auth - (other auth schemes can be implemented using `headers`) -* `config`: allows configuration of HTTPS, specifically a map of booleans `laxRedirect`, `trustAll`, and `trustSelfSigned`; - defaults to entity config or `brooklyn.properties` values of the same keys prefixed with - `brooklyn.https.config.`, and otherwise defaulting to `false` for each for security; - this allows e.g. configuration to work with self-signed hosts where the network is trusted +{{ step.input }} +{% endif %} +{% if step.output %} **Output return value**: -* `status_code`: integer status code, e.g. 200 -* `headers`: a map of header keys to a _list_ of values for that header on the response (as multiple values are permitted) -* `content`: the content, converted to a string using `charset` -* `content_bytes`: the content, as a raw byte array -* `duration`: how long the request took - - -### invoke-effector - -Invokes an effector. - -**Shorthand**: `invoke-effector EFFECTOR` - -**Input parameters**: -* `effector`: the name of the effector to invoke -* `entity`: optional entity or entity ID where the effector should be invoked -* `args`: map of argument names to values to pass to the effector - -**Output return value**: the returned object from the invoked effector - +{{ step.output }} +{% endif %} -### let +<div style="margin-bottom: 42px;"></div> -An alias for `set-workflow-variable`. + {% endfor %} -**Shorthand**: `let [ "trimmed" ] [ TYPE ] VARIABLE_NAME = VALUE` +{% endfor %} -### log -Logs a message. +## Index of Step Types -**Shorthand**: `log MESSAGE` +{% assign step_summaries = step_summaries | sort: "name" %} -**Input parameters**: -* `message`: the message to be logged - -**Output return value**: the output from the previous step, or null if this is the first step - - -### no-op - -Does nothing. It is mainly useful when setting a `next` point to jump to, -optionally with a `condition`. - -**Shorthand**: `no-op` - -**Input parameters**: _none_ - -**Output return value**: the output from the previous step, or null if this is the first step - - -### return - -Returns an indicated value and specifies that the workflow should end, -essentially equivalent to `{ type: no-op, output: VALUE, next: end }`. - -**Shorthand**: `return VALUE` - -**Input parameters**: -* `value`: the value to return - -**Output return value**: the value indicated - - -### set-config - -Sets the value of a config key on an entity. - -**Shorthand**: `set-config [TYPE] CONFIG_KEY_NAME = VALUE` - -**Input parameters**: -* `config`: a string being the config key name or a map containing the `name` and - optionally the `type` (defaulting to the declared type of the config key, if present, or to `Object`) - and/or the `entity` where the config should be set (defaulting to the entity where the workflow is running) -* `value`: the value to set - -**Output return value**: the output from the previous step, or null if this is the first step - - -### set-sensor - -Sets the value of a sensor on an entity. - -**Shorthand**: `set-sensor [TYPE] SENSOR_NAME = VALUE` - -**Input parameters**: -* `sensor`: 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) -* `value`: the value to set +<div class="no-space-in-list" markdown="1" style="margin-top: 0; margin-bottom: 42px;"> +{% for x in step_summaries %} -**Output return value**: the output from the previous step, or null if this is the first step - - -### set-workflow-variable - -Sets the value of a workflow internal variable. The step `let` is an alias for this. - -**Shorthand**: `set-workflow-variable ["trimmed"] [TYPE] VARIABLE_NAME = VALUE` - -**Input parameters**: -* `variable`: a string being the workflow variable name or a map containing the `name` and optionally the `type` - to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`) -* `value`: the value to set, with some limited evaluation as described [here](variables.md) -* `trim`: whether the value, if a string, should be trimmed after evaluation and prior to setting, as described [here](variables.md); - this can be set from shorthand if the first word after the step type is `trimmed` - -**Output return value**: the output from the previous step, or null if this is the first step - - -### sleep - -Causes execution to pause for a specified duration. - -**Shorthand**: `sleep DURATION` - -**Input parameters**: -* `duration`: how long to sleep for, e.g. `5s` for 5 seconds - -**Output return value**: the output from the previous step, or null if this is the first step - - -### ssh - -Runs a command over ssh. - -**Shorthand**: `ssh COMMAND` - -**Input parameters**: -* `command`: the command to run -* `env`: a map of string keys with values whose JSON is taken and passed to the command be executed -* `exit-code`: the word `any`, a number, or a predicate DSL expression (e.g. `less-than: 32`) - to require of the exit status code from the command, defaulting to `0` - -[//]: # (* `endpoint`: an alternative endpoint (format TODO); typically this is omitted and the SSH machine location of the entity is the target) -[//]: # (* `key`: a private key to use for the connection to the endpoint (TODO, again typically embedded in the SSH machine location of the entity)) - -**Output return value**: -* `stdout` -* `stderr` -* `exit_code` - - -### winrm - -Runs a command over winrm. - -**Shorthand**: `winrm COMMAND` - -**Input parameters**: -* `command`: the command to run -* `env`: a map of string keys with values whose JSON is taken and passed to the command be executed -* `exit-code`: the word `any`, a number, or a predicate DSL expression (e.g. `less-than: 32`) - to require of the exit status code from the command, defaulting to `0` - -[//]: # (* `endpoint`: an alternative endpoint (format TODO); typically this is omitted and the SSH machine location of the entity is the target) -[//]: # (* `key`: a private key to use for the connection to the endpoint (TODO, again typically embedded in the SSH machine location of the entity)) - -**Output return value**: -* `stdout` -* `stderr` -* `exit_code` - - -### wait - -Waits for a value which might not yet be resolved, or a task which might not have finished, -optionally setting the value or the task's result to a workflow variable. - -**Shorthand**: `wait [ [TYPE] VARIABLE_NAME = ] [MODE] VALUE` - -**Input parameters**: -* `variable`: a string being the workflow variable name or a map containing the `name` and optionally the `type` - to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`) -* `mode`: either `expression` (the default) or `task` to treat value as a task or task ID -* `value`: the expression to wait on and optionally set - -**Output return value**: 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 - - -### workflow - -Runs nested workflow, optionally over an indicated target. -This step type is described in more detail [here](nested-workflow.md). - -**Shorthand**: not supported - -**Input parameters**: -* `steps`: a list of steps to run, run in a separate context -* `target`: an optional target specifier (see below) - -**Output return value**: the output from the last step in the nested workflow - - -# Third-Party Software Steps - -### ansible-ssh - -Runs a playbook via Ansible by SSHing to the VM under management. -These playbooks will often target `localhost` but may target other servers. - -**Shorthand**: `ansible-ssh PLAYBOOK_NAME [ "from" PLAYBOOK_URL ]` - -**Input parameters**: -* `playbook_name`: name of the playbook to run; required -* `playbook_url`: URL for downloading the playbook; exactly one of this or `playbook_yaml` is required -* `playbook_yaml`: YAML for the playbook, embedded in the step -* `vars`: optional variables to pass to Ansible -* `run_dir`: the directory on the target system where playbooks should be installed and run; - defaults to an entity-specific folder -* `install`: whether to install Ansible if necessary, defaults to `true` -* `install_dir`: the directory on the target system from which Ansible should be downloaded and installed, - if `install` is not false, defaults to an entity-specific folder - -**Output return value**: -* `stdout` -* `stderr` -* `exit_code` +* [{% if x.shorthand %}`{{ x.name }}`{% else %}`{{ x.name }}`{% endif %}](#{{ x.name }}) +{% endfor %} +</div> diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml new file mode 100644 index 00000000..835aef36 --- /dev/null +++ b/guide/blueprints/workflow/steps/steps.yaml @@ -0,0 +1,271 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +- + section_name: Workflow Control + section_intro: | + The first group of built-in step types are those which control the flow of execution and local state within the workflow. + + steps: + - name: let + summary: An alias for `set-workflow-variable`. + shorthand: '`let [ "trimmed" ] [ TYPE ] VARIABLE_NAME = VALUE`' + + - name: set-workflow-variable + summary: Sets the value of a workflow internal variable. The step `let` is an alias for this. + shorthand: '`set-workflow-variable ["trimmed"] [TYPE] VARIABLE_NAME = VALUE`' + input: | + * `variable`: a string being the workflow variable name or a map containing the `name` and optionally the `type` + to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`) + * `value`: the value to set, with some limited evaluation as described [here](../variables.md) + * `trim`: whether the value, if a string, should be trimmed after evaluation and prior to setting, as described [here](../variables.md); + this can be set from shorthand if the first word after the step type is `trimmed` + output: the output from the previous step, or null if this is the first step + + - name: clear-workflow-variable + summary: Clears the value of a workflow internal variable. + shorthand: '`clear-workflow-variable [TYPE] VARIABLE_NAME`' + input: | + * `variable`: a string being the workflow variable name or a map containing the `name` + of the workflow variable which should be cleared + output: the output from the previous step, or null if this is the first step + + - name: return + summary: | + Returns an indicated value and specifies that the workflow should end, + essentially equivalent to `{ type: no-op, output: VALUE, next: end }`. + shorthand: '`return VALUE`' + input: | + * `value`: the value to return + output: the value indicated + + - name: wait + summary: | + Waits for a value which might not yet be resolved, or a task which might not have finished, + optionally setting the value or the task's result to a workflow variable. + shorthand: '`wait [ [TYPE] VARIABLE_NAME = ] [MODE] VALUE`' + input: | + * `variable`: a string being the workflow variable name or a map containing the `name` and optionally the `type` + to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`) + * `mode`: either `expression` (the default) or `task` to treat value as a task or task ID + * `value`: the expression to wait on and optionally set + output: | + 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: workflow + summary: | + Runs nested workflow, optionally over an indicated target. + This step type is described in more detail [here](../nested-workflow.md). + input: | + * `steps`: a list of steps to run, run in a separate context + * `target`: an optional target specifier (see below) + output: the output from the last step in the nested workflow + +- + section_name: External Actions + section_intro: | + The next group of step types are those which typically do the "real work" by interacting with + external resources in the real world. + + steps: + - name: container + summary: | + Runs a container with optional command and environment variables. + shorthand: '`container IMAGE [ COMMAND ]`' + input: | + * `image`: the image to run + * Optionally a command to pass to the image, at most one of: + * `command`: a command or script as a string, to pass to bash to be run + * `commands`: a list of commands to pass to bash to be run + * `raw-command`: a list containing the base executable in the first entry and any arguments as additional entries + * `env`: a map of string keys with values whose JSON is taken and passed to the command be executed + * `exit-code`: the word `any`, a number, or a predicate DSL expression (e.g. `less-than: 32`) + to require of the exit status code from the command, defaulting to `0` + * `pull-policy`: one of `IfNotPresent`, `Always`, or `Never`, whether to pull the image before running; + defaults to `IfNotPresent` + output: | + * `stdout` + * `stderr` + * `exit_code` + + + - name: http + summary: Sends an HTTPS (or HTTP) request and returns the response content and code. + shorthand: '`http ENDPOINT`' + input: | + * `endpoint`: the URL to connect to, optionally omitting the protocol and slash prefix if `https://` is intended + (e.g. just the host and any path); per URL standard any unusual characters such as query parameters should be URL-encoded, + so if e.g. passing parameters containing spaces, `params` should be used instead of `host/path?param=${value}` + * `query`: a map of query parameters to URL encode and add to the URL + * `body`: an object to be serialized and sent as the body (or just set as body if it is an array of bytes) + * `charset`: the character set to use to convert between byte arrays and strings for the request body and response content; + not applied if `body` is already a byte array, and not applied to the `content_bytes` output; + defaults to the system default + * `status-code`: the word `any`, a number, or a predicate DSL expression to require of the response status code, + defaulting to `{ less-than: 400, greater-than-or-equal-to: 200 }` + * `headers`: a map of header key-values to set on the request + * `method`: the HTTP method for the request, defaulting to `get` + * `username` and `password`: credentials to set on the request, e.g. for Basic auth + (other auth schemes can be implemented using `headers`) + * `config`: allows configuration of HTTPS, specifically a map of booleans `laxRedirect`, `trustAll`, and `trustSelfSigned`; + defaults to entity config or `brooklyn.properties` values of the same keys prefixed with + `brooklyn.https.config.`, and otherwise defaulting to `false` for each for security; + this allows e.g. configuration to work with self-signed hosts where the network is trusted + output: | + * `status_code`: integer status code, e.g. 200 + * `headers`: a map of header keys to a _list_ of values for that header on the response (as multiple values are permitted) + * `content`: the content, converted to a string using `charset` + * `content_bytes`: the content, as a raw byte array + * `duration`: how long the request took + + - name: ssh + summary: Runs a command over ssh. + shorthand: '`ssh COMMAND`' + input: | + * `command`: the command to run + * `env`: a map of string keys with values whose JSON is taken and passed to the command be executed + * `exit-code`: the word `any`, a number, or a predicate DSL expression (e.g. `less-than: 32`) + + # [//]: # (* `endpoint`: an alternative endpoint (format TODO); typically this is omitted and the SSH machine location of the entity is the target) + # [//]: # (* `key`: a private key to use for the connection to the endpoint (TODO, again typically embedded in the SSH machine location of the entity)) + output: | + * `stdout` + * `stderr` + * `exit_code` + + - name: winrm + summary: Runs a command over winrm. + shorthand: '`winrm COMMAND`' + input: | + * `command`: the command to run + * `env`: a map of string keys with values whose JSON is taken and passed to the command be executed + * `exit-code`: the word `any`, a number, or a predicate DSL expression (e.g. `less-than: 32`) + to require of the exit status code from the command, defaulting to `0` + + # [//]: # (* `endpoint`: an alternative endpoint (format TODO); typically this is omitted and the SSH machine location of the entity is the target) + # [//]: # (* `key`: a private key to use for the connection to the endpoint (TODO, again typically embedded in the SSH machine location of the entity)) + + output: | + * `stdout` + * `stderr` + * `exit_code` + + + - name: ansible-ssh + summary: | + Runs a playbook via Ansible by SSHing to the VM under management. + These playbooks will often target `localhost` but may target other servers. + shorthand: '`ansible-ssh PLAYBOOK_NAME [ "from" PLAYBOOK_URL ]`' + input: | + * `playbook_name`: name of the playbook to run; required + * `playbook_url`: URL for downloading the playbook; exactly one of this or `playbook_yaml` is required + * `playbook_yaml`: YAML for the playbook, embedded in the step + * `vars`: optional variables to pass to Ansible + * `run_dir`: the directory on the target system where playbooks should be installed and run; + defaults to an entity-specific folder + * `install`: whether to install Ansible if necessary, defaults to `true` + * `install_dir`: the directory on the target system from which Ansible should be downloaded and installed, + if `install` is not false, defaults to an entity-specific folder + output: | + * `stdout` + * `stderr` + * `exit_code` + +- + section_name: Application Models + section_intro: | + The next group of step types manipulate the application models in Brooklyn. + + steps: + - name: invoke-effector + summary: Invokes an effector. + shorthand: '`invoke-effector EFFECTOR`' + input: | + * `effector`: the name of the effector to invoke + * `entity`: optional entity or entity ID where the effector should be invoked + * `args`: map of argument names to values to pass to the effector + output: the returned object from the invoked effector + + - name: set-config + summary: Sets the value of a config key on an entity. + shorthand: '`set-config [TYPE] CONFIG_KEY_NAME = VALUE`' + input: | + * `config`: a string being the config key name or a map containing the `name` and + optionally the `type` (defaulting to the declared type of the config key, if present, or to `Object`) + and/or the `entity` where the config should be set (defaulting to the entity where the workflow is running) + * `value`: the value to set + output: the output from the previous step, or null if this is the first step + + - name: set-sensor + summary: Sets the value of a sensor on an entity. + shorthand: '`set-sensor [TYPE] SENSOR_NAME = VALUE`' + input: | + * `sensor`: 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) + * `value`: the value to set + output: the output from the previous step, or null if this is the first step + + - name: clear-config + summary: Clears the value of a config key on an entity. + shorthand: '`clear-config [TYPE] CONFIG_KEY_NAME`' + input: | + * `config`: a string being the config key name or a map containing the `name` and + optionally the `entity` where the config should be set (defaulting to the entity where the workflow is running) + output: | + the output from the previous step, or null if this is the first step + + - name: clear-sensor + summary: Clears the value of a sensor on an entity. + 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) + output: the output from the previous step, or null if this is the first step + + +- + section_name: General Purpose + section_intro: | + A few other miscellaneous step types don't fit into the other categories. + steps: + + - name: log + summary: Logs a message. + shorthand: '`log MESSAGE`' + input: | + * `message`: the message to be logged + output: the output from the previous step, or null if this is the first step + + - name: no-op + summary: | + Does nothing. It is mainly useful when setting a `next` point to jump to, + optionally with a `condition`. + shorthand: '`no-op`' + input: _none_ + output: the output from the previous step, or null if this is the first step + + - name: sleep + summary: Causes execution to pause for a specified duration. + shorthand: '`sleep DURATION`' + input: | + * `duration`: how long to sleep for, e.g. `5s` for 5 seconds + output: the output from the previous step, or null if this is the first step + + + diff --git a/style/css/_util.scss b/style/css/_util.scss index b6d4b448..d9163c42 100644 --- a/style/css/_util.scss +++ b/style/css/_util.scss @@ -25,3 +25,9 @@ .flip { @include flip; } + +div.no-space-in-list { + p { + margin: 0; + } +} \ No newline at end of file
