commandCall

Note

Since Platform version 31.1 new short syntax for commandCall is available, allowing to use command pin names as action names.

Thereby, it is strongly recommended to use short syntax in most cases. The only exception is when you don’t know pin name or parameter names at the time of writing manifest and want to pass them from dynamic links.

Calls a command on a peer or peers connected to an interface. Supersedes serviceCall step used in 1.x manifests.

Parameters

Name Type Constraints Default Definition
service string required   Alias name for service interface.
command string required   Command to call.
arguments map   {} Command arguments (see docs on particular service).
timeout int or string   30 Timeout to finish with optional time unit suffix. Supported time units are hour, minute, and second (both singular and plural forms). If no time unit specified, seconds will be used.
aggregation map   {} A map from a result key to an aggregation strategy for intermediate command responses. Supported values are default, last, and concatenate. Default is last.
multi boolean   false If true, a request will be send to all connected peers, and a map from peer id to command result will be returned. If false, a request will be send to a single peer, and fail if there are no or several peers connected (unless peerId is defined). See “Calling multiple peers” section for details.
peerId string     Defines a peer the request will be sent to, when multi is false and there are several peers connected.
batchSize int optional   Defines how many values will be processed simultaneously. See throttling for details.
batchBy list   [ “peerId” ] Defines a set of arguments that participate in batching.

Return Values

Name Type Definition
result map Result of command call.

If ignoreFail is set to false, the failure key of result map will contain an explanation (returned by a service).

Calling multiple peers

Using parameter multi set to true will invoke command on all peers on specified interface, known by workflow to be in Active state. This set of peers is remembered during workflow start, and is updated only during waitPeers calls. Between these updates, the same set of peers will be used, regardless of their state at the time of calling.

Throttling

It is possible to limit the level of parallelism of the commandCall step. You might need this when there is a limited external resource (CPU, memory, HTTP API with a limited request rate) or when you need to do something in a rolling manner, for example when you are upgrading a cluster. By default the number of peers processing requests is limited, but you can split other list-typed arguments into batches as well by passing a batchBy parameter. You can set batchBy to a list of command arguments, and there is also one special value peerId (or commandCallPeerId if you use a short syntax), that refers to a list of component peers. Command arguments referenced in the batchBy parameter must be of type list.

For command arguments that are present in the batchBy list we will limit a number of values sent in one request. There is no guaranteed specific processing order, but the product of lengths of all list arguments referenced in batchBy in one batch won’t exceed batchSize. Also, all possible combinations of argument values will be processed exactly once.

For example, if you have the following step executed on a single peer:

execute:
    action: commandCall
    parameters:
        service: pinger
        command: ping
        batchBy: [ hosts, ports ]
        batchSize: 2
        arguments:
          hosts: [ "127.0.0.1", "127.0.0.2" ]
          ports: [ 8080, 8081, 8082 ]

then the request will be split into three batches:

Batch 1: hosts = [ "127.0.0.1" ],              ports = [ 8081, 8082 ]
Batch 2: hosts = [ "127.0.0.2" ],              ports = [ 8081, 8082 ]
Batch 3: hosts = [ "127.0.0.1", "127.0.0.2" ], ports = [ 8083 ]

An example of batching in a multi-peer scenario is:

execute:
    action: commandCall
    parameters:
        service: cluster
        command: install
        multi: true
        batchBy: [ peerId, package ]
        batchSize: 7
        arguments:
          package: [ "a.rpm", "b.rpm" ]

If there are three peers (peer1, peer2, and peer3) in the cluster, the following batches will be formed:

Batch 1: peerId = [ "peer1", "peer2" ], package = [ "a.rpm", "b.rpm" ]
Batch 2: peerId = [ "peer3" ],          package = [ "a.rpm", "b.rpm" ]

Example Usage

workflow:
  type: workflow.Instance
  interfaces:
    compute:
      exec: send-command(string command, int timeout => string stdOut, string stdErr => string stdOut, string stdErr, int exitCode)
  configuration:
    configuration.workflows:
      launch:
        steps:
         execute:
           action: commandCall
           parameters:
             service: compute
             command: exec
             timeout: 600
             arguments:
               command: "{$.command}"
               timeout: 600000
             aggregation:
               stdOut: concatenate
               stdErr: concatenate
           output:
             result: result