Action Runner

Deep Dive into Tinkerbell’s Action Runner

The Action Runner in Tinkerbell is a critical component responsible for executing individual actions defined within a provisioning workflow. These actions can include tasks such as partitioning disks, installing an operating system, configuring the network, or running custom scripts. The Action Runner interacts with the Tink server to execute these tasks sequentially, reporting the status of each action back to the Tink server.

Core Responsibilities of the Action Runner

  1. Executing Workflow Actions:
    • The Action Runner is responsible for executing each task or action defined in a workflow. Workflows are composed of multiple actions, each representing a specific step in the provisioning process, such as setting up the OS, configuring networking, or installing software.
    • Actions are typically containerized, meaning they run within a container environment to ensure consistency and isolation. This containerization allows for using different environments or tools needed for each action.
  2. Status Reporting:
    • After executing an action, the Action Runner reports the outcome (success or failure) back to the Tink server. This reporting allows the Tink server to monitor the progress of the workflow and determine if subsequent actions can be executed or if an error has occurred that needs addressing.
    • Status reporting includes logging details about the execution, such as exit codes, standard output, and error messages, which are useful for debugging and monitoring.
  3. Handling Dependencies and Sequencing:
    • The Action Runner ensures that actions within a workflow are executed in the correct order. Some actions may depend on the successful completion of previous actions, and the Action Runner manages this sequencing to ensure workflows progress smoothly.
    • It handles retries for actions that fail due to transient issues, attempting to recover from failures before halting the workflow.
  4. Containerized Execution:
    • Actions are defined as Docker containers, which the Action Runner pulls and executes. This approach allows for flexibility, as different actions can use different container images suited to their specific tasks (e.g., a container for disk partitioning, another for OS installation).
    • The use of containers ensures that actions are executed in a controlled and consistent environment, minimizing the risk of dependency conflicts or environmental issues.

Working Example: Using the Action Runner in Tinkerbell

Let’s walk through a practical example where the Action Runner is used to provision a bare-metal server by executing a series of actions defined in a workflow. The example will involve partitioning a disk, installing an operating system, and configuring the network.

1. Define the Workflow

First, we need to define a Tinkerbell workflow that includes several actions. Here’s an example workflow definition in YAML:

version: "0.1"
name: "Ubuntu 20.04 Provisioning"
global_timeout: 6000
tasks:
  - name: "disk-partitioning"
    worker: "{{.device_1}}"
    volumes:
      - /dev:/dev
    actions:
      - name: "parted"
        image: "quay.io/tinkerbell-actions/parted:latest"
        timeout: 60
        environment:
          DEVICE: /dev/sda
          PARTITION_LAYOUT: |
            mklabel gpt
            mkpart ESP fat32 1MiB 513MiB
            set 1 boot on
            mkpart primary ext4 513MiB 100%

  - name: "install-os"
    worker: "{{.device_1}}"
    volumes:
      - /mnt/root:/mnt/root
    actions:
      - name: "os-install"
        image: "quay.io/tinkerbell-actions/osie-ubuntu:latest"
        timeout: 1200
        environment:
          ROOT_DISK: /dev/sda
          OS_IMAGE_URL: "http://example.com/images/ubuntu-20.04.img"

  - name: "network-config"
    worker: "{{.device_1}}"
    actions:
      - name: "network-configure"
        image: "quay.io/tinkerbell-actions/network-helper:latest"
        timeout: 300
        environment:
          INTERFACE: eth0
          IP_ADDRESS: 192.168.1.10
          NETMASK: 255.255.255.0
          GATEWAY: 192.168.1.1
  • Tasks: The workflow is divided into tasks, each responsible for a specific part of the provisioning process.
  • Actions: Each task contains one or more actions, which are executed in sequence. These actions are containerized commands that perform specific tasks.
  • Environment Variables: Actions often use environment variables to customize their behavior (e.g., specifying the disk to partition, the OS image to install, network settings).

2. Submit the Workflow to the Tink Server

Once the workflow is defined, it must be submitted to the Tink server so that it can be executed on the designated hardware.

tink workflow create -t ubuntu-20-04-provisioning.yml

This command registers the workflow with the Tink server and associates it with the target hardware.

3. Workflow Execution by the Action Runner

  • Disk Partitioning:
  • The first task involves partitioning the disk using the parted action. The Action Runner pulls the parted container image and executes it on the target machine.
  • The partitioning layout is provided via environment variables, instructing parted to create a GPT partition table and define the partitions.
  • Operating System Installation:
  • The second task installs the Ubuntu OS using the osie-ubuntu action. The Action Runner downloads the OS image from the specified URL and writes it to the disk.
  • This task includes mounting the disk and extracting the OS image to the correct location, ensuring the machine is bootable.
  • Network Configuration:
  • The final task configures the network using the network-helper action. The Action Runner sets up the network interface with the provided IP address, netmask, and gateway.
  • This configuration ensures the machine can communicate with the network and other components once it reboots.

4. Monitor Action Runner Execution

The status of each action executed by the Action Runner can be monitored via the Tink CLI:

tink workflow state <workflow-id>

This command shows the current state of the workflow, including whether each action has been executed successfully, is in progress, or has failed.

  • Success: If an action completes successfully, the Action Runner proceeds to the next action in the workflow.
  • Failure: If an action fails, the workflow may halt or retry the action, depending on the configuration. Logs and error messages from the Action Runner provide insights into the failure.

5. Review Logs and Debugging

For debugging or detailed monitoring, you can retrieve logs from the Action Runner:

tink workflow logs <workflow-id>

This command provides access to the logs generated by the Action Runner for each action, including output from the containerized tasks. Reviewing these logs helps identify issues during provisioning, such as misconfigurations or network problems.

Conclusion

The Action Runner in Tinkerbell is a powerful component that drives the execution of workflows on bare-metal servers. By managing containerized actions, it ensures that complex provisioning tasks are executed reliably and in the correct sequence. The use of containerization allows for flexible, consistent, and isolated task execution, making it easier to manage diverse hardware environments. The Action Runner’s ability to report status and handle dependencies makes it an essential part of the Tinkerbell provisioning system, enabling seamless and automated management of physical server infrastructure.