Nodes and Executors

Overview¶

Flowctl allows you to execute workflows both locally and on remote nodes.

Executors¶

Executors define how your actions run. Flowctl provides three built-in executors:

Docker Executor¶

The Docker executor runs your scripts inside Docker containers.

Configuration:

- id: build_app
  name: Build Application
  executor: docker
  variables:
    - version: "{{ inputs.version }}"
  with:
    image: docker.io/node:18
    script: |
      npm install
      npm run build
      echo "BUILD_ID=$(date +%s)" >> $FC_OUTPUT

Config:

• image: Docker image
• script: Bash script to execute inside the container

Script Executor¶

The Script executor runs shell scripts directly on the host system (local or remote).

Configuration:

- id: deploy
  name: Deploy Application
  executor: script
  variables:
    - app_name: "{{ inputs.app_name }}"
  with:
    script: |
      cd /opt/$app_name
      git pull origin main
      systemctl restart $app_name
      echo "DEPLOYED_AT=$(date -Iseconds)" >> $FC_OUTPUT
    interpreter: /bin/bash # Optional, defaults to /bin/bash

Key Features:

• script: Script to execute. Could be anything the interpreter can execute.
• interpreter: Path to interpreter

Flow Executor¶

The Flow executor triggers another flow as a child execution. Use it to compose workflows.

Configuration:

- id: run_tests
  name: Run Test Suite
  executor: flow
  with:
    flow_id: my-test-flow
    params: '{"env": "staging"}'
    wait: true

Config:

• flow_id (required): ID of the flow to trigger
• params: JSON string of parameters to pass to the child flow
• wait: If true, blocks until the child flow completes. Defaults to false

Outputs:

• exec_id: Execution ID of the triggered flow
• status: Final status of the child flow (only when wait: true). One of completed, errored, or cancelled

Remote Nodes¶

A remote node is any server or machine that flowctl can connect to via a remote client (SSH).

Setting Up Remote Nodes¶

Step 1: Create a Credential¶

Before adding a node, create SSH credentials:

1. Navigate to Credentials
2. Click Add Credential
3. Provide:
4. Name: Descriptive name (e.g., "Production Server SSH Key")
5. Type: private_key or password
6. Key Data: SSH private key or password

Step 2: Add a Node¶

1. Navigate to Nodes
2. Click Add Node
3. Configure the node:

Fields:

• Name: Unique identifier used in flow definitions
• Hostname: IP address or domain name
• Port: SSH port (default: 22)
• Username: SSH username
• Connection Type: ssh or qssh (QUIC-based SSH)
• Credential: SSH authentication credential
• Tags: Optional labels for organization

Using Remote Nodes in Flows¶

Execute actions on remote nodes using the on field. You can specify node names directly or use tags to target multiple nodes.

By Node Name¶

actions:
  - id: remote_deploy
    name: Deploy to Production
    executor: script
    on:
      - WebServer1
      - WebServer2

By Tag¶

Use the tag: prefix to run on all nodes with a specific tag:

actions:
  - id: deploy_to_dev
    name: Deploy to Dev Servers
    executor: script
    on:
      - tag:dev

You can mix node names and tags:

on:
  - WebServer1
  - tag:backend

In the UI, type tag: followed by the tag name to search by tag. You can either select the tag itself (targets all nodes with that tag) or pick individual nodes from the results.

Key Points:

• Actions run on all specified nodes in parallel
• Each node receives the same inputs and variables
• Outputs are collected from all nodes
• If any node action fails, the entire flow will fail
• When using tags, nodes are resolved at execution time. Add/remove nodes from a tag without updating flows

Next Steps¶

• Learn about Flow Secrets for secure credential management
• Review Access Control for multi-user environments