Tink

Deep Dive into Tink

Tink is the core orchestrator of the Tinkerbell stack. It manages the provisioning workflows for bare-metal servers, which include tasks like bootstrapping, operating system installation, and post-installation configuration. Let’s explore Tink in more detail, along with some working examples to illustrate its functionality.

Tink Architecture Overview

Tink is built around a few key concepts:

  1. Workflows: These are the heart of Tink. A workflow defines a sequence of actions (tasks) that should be executed on a specific piece of hardware.
  2. Templates: Templates define reusable sets of actions that can be applied to multiple workflows. They are written in YAML or JSON and specify what tasks need to be performed.
  3. Actions: Actions are the individual tasks that make up a workflow. Each action is a step, such as executing a shell command, installing a package, or rebooting the machine.
  4. Hardware: Tink manages hardware resources, associating workflows with specific machines based on their hardware ID.

Tink Components

  • Tink Server: The central API server that manages workflows, templates, and hardware resources. It exposes a REST API and is responsible for the orchestration logic.
  • Tink CLI: A command-line tool used to interact with the Tink server. It allows users to create, list, and manage workflows, templates, and hardware.

Basic Workflow with Tink

Let’s walk through a basic example of how Tink is used to provision a bare-metal machine.

1. Setup and Initialization

Before creating workflows, we need to ensure that Tink is set up correctly. Typically, Tink is deployed in a Kubernetes environment, and you interact with it using the Tink CLI.

Install Tink CLI

Assuming that you have Tink installed in your environment, you can install the Tink CLI using the following commands:

# Download the Tink CLI binary
curl -LO https://github.com/tinkerbell/tink/releases/download/<version>/tink_<version>_linux_amd64.tar.gz

# Extract the binary
tar -xvf tink_<version>_linux_amd64.tar.gz

# Move it to a directory in your PATH
sudo mv tink /usr/local/bin/tink

2. Define and Create a Template

A template is a reusable set of actions that can be applied to one or more workflows. Below is an example template that provisions a bare-metal server by installing Ubuntu and performing some basic configurations.

version: "0.1"
name: "ubuntu-provision"
global_timeout: 6000
tasks:
  - name: "disk-wipe"
    worker: "{{.device_1}}"
    volumes:
      - /dev:/dev
    actions:
      - name: "disk-wipe"
        image: disk-wipe:latest
        timeout: 3600
        environment:
          BLOCK_DEVICE: "/dev/sda"

  - name: "install-ubuntu"
    worker: "{{.device_1}}"
    actions:
      - name: "ubuntu-install"
        image: osie-ubuntu-installer:latest
        environment:
          UBUNTU_VERSION: "20.04"
          DEVICE: "/dev/sda"
        timeout: 6000

In this template:

  • disk-wipe: Wipes the disk on the machine to prepare it for a fresh OS installation.
  • install-ubuntu: Installs Ubuntu 20.04 on the machine.
Create the Template

Once the template is defined, you can create it in Tink using the CLI:

tink template create --file ubuntu-provision.yaml

This command uploads the template to the Tink server, making it available for workflows.

3. Register the Hardware

Next, you need to register the hardware (bare-metal machine) that will be provisioned. Hardware is identified by its MAC address and other details.

id: "d5eb5a20-16a7-11ec-82a8-0242ac130003"
metadata:
  facility: "on-prem"
  instance:
    device_1: "00:1e:67:1c:3e:84"
    manufacturer: "Dell"
    plan: "c3.small.x86"
    state: "provisioning"
network:
  interfaces:
    - dhcp:
        arch: "x86_64"
        mac: "00:1e:67:1c:3e:84"
  netboot:
    allow_pxe: true
    osie: {
      commit: "",
      os: "ubuntu",
    }
Create the Hardware Resource

You create the hardware resource with:

tink hardware push --file hardware.yaml

This registers the hardware with Tink, associating it with the workflow to be run.

4. Create and Execute a Workflow

Now, create a workflow that uses the previously defined template and targets the registered hardware.

template: "ubuntu-provision"
hardware:
  - "d5eb5a20-16a7-11ec-82a8-0242ac130003"
Create the Workflow

Use the following command to create the workflow:

tink workflow create --template ubuntu-provision --hardware "d5eb5a20-16a7-11ec-82a8-0242ac130003"
Start and Monitor the Workflow

To start the workflow, it is automatically triggered when the bare-metal machine boots. You can monitor the progress using:

tink workflow list

Or, to see the detailed status:

tink workflow events <workflow-id>

This will show you the sequence of actions being executed, including any errors or logs from the tasks.

5. Post-Provisioning Actions

After the workflow is complete, the machine will be fully provisioned with Ubuntu and any specified configurations. You can then proceed to add it to a Kubernetes cluster or use it for other purposes.

Advanced Usage

Multiple Machines and Parallel Workflows

Tink allows for provisioning multiple machines in parallel by creating multiple workflows. You can define different templates for different roles (e.g., control plane nodes, worker nodes) and apply them to different hardware resources.

Error Handling and Re-Execution

If a workflow fails at any step, Tink provides mechanisms for error handling. You can define retry policies in the template or manually re-execute failed tasks.

For example, to retry a specific action:

tink workflow action retry <workflow-id> <action-id>

Custom Actions

In addition to the pre-built actions, you can create custom actions by writing your own Docker containers that perform specific tasks. These containers are then referenced in the template like any other action.

Conclusion

Tink, as the orchestrator in the Tinkerbell stack, provides powerful and flexible tools for provisioning bare-metal servers. By defining templates, registering hardware, and creating workflows, you can automate complex provisioning processes, ensuring consistency and reducing manual intervention. The Tink CLI and API make it easy to integrate Tink into larger automation frameworks, allowing for scalable and repeatable infrastructure management.