Tink CLI

Deep Dive into Tink CLI

Tink CLI is the command-line interface used to interact with the Tinkerbell stack. It provides a user-friendly way to manage various components of Tinkerbell, such as workflows, templates, and hardware resources. Through Tink CLI, users can define workflows, monitor the status of tasks, and manage the lifecycle of bare-metal machines during provisioning.

Tink CLI Architecture Overview

Tink CLI interacts directly with the Tink server, sending commands and receiving responses via the Tink API. It is a powerful tool that allows users to perform complex operations in a simplified manner, leveraging the full capabilities of the Tinkerbell stack.

Key concepts around Tink CLI:

  1. Workflow Management: Tink CLI is used to create, manage, and monitor workflows that define the provisioning process of bare-metal machines.
  2. Template Management: Users can define reusable templates that specify the tasks within workflows, and manage these templates through Tink CLI.
  3. Hardware Management: Tink CLI allows for the registration, modification, and deletion of hardware resources within Tinkerbell.

Core Commands of Tink CLI

Tink CLI offers a wide range of commands, each with specific functions to manage different aspects of Tinkerbell. Here are the core commands:

  • tink hardware: Manage hardware resources.
  • tink template: Create, list, and manage templates.
  • tink workflow: Create, manage, and monitor workflows.
  • tink version: Check the current version of Tink CLI and server.
  • tink events: Monitor events related to workflows.

Tink CLI Usage Flow

Here’s a detailed look at how Tink CLI is used in a typical workflow within the Tinkerbell ecosystem:

  1. Template Creation:
  • Before provisioning a machine, users define a template using Tink CLI. This template specifies the tasks to be performed during the provisioning process.
  1. Hardware Registration:
  • Users register bare-metal machines with Tinkerbell, providing details like MAC addresses, BMC information, and network configuration.
  1. Workflow Creation:
  • With the hardware registered and templates defined, users create workflows that associate a template with specific hardware. This workflow dictates the provisioning process for that machine.
  1. Workflow Execution and Monitoring:
  • Once the workflow is created, it is automatically executed by Tink. Users can monitor the progress of the workflow, check logs, and handle any errors that occur.

Working Examples with Tink CLI

Let’s go through some practical examples of how Tink CLI can be used to manage various aspects of the Tinkerbell stack.

1. Managing Hardware Resources

Registering Hardware

To register a new piece of hardware, you use the tink hardware push command with a YAML configuration file that describes the hardware:

# hardware.yaml
id: "f92d5c9e-71d1-11ec-90d6-0242ac130003"
metadata:
  facility: "on-prem"
  instance:
    device_1: "00:25:90:fd:e1:af"
    manufacturer: "Dell"
    plan: "c3.large.x86"
    state: "provisioning"
network:
  interfaces:
    - dhcp:
        arch: "x86_64"
        mac: "00:25:90:fd:e1:af"
  netboot:
    allow_pxe: true
    osie: {
      commit: "",
      os: "ubuntu"
    }

To push this configuration to the Tink server:

tink hardware push --file hardware.yaml

This command registers the hardware with the specified details in the Tinkerbell system.

Listing Hardware

To list all registered hardware:

tink hardware list

This command outputs a list of all hardware resources registered in the system, along with their IDs, MAC addresses, and other metadata.

Retrieving Hardware Details

To get detailed information about a specific piece of hardware:

tink hardware get f92d5c9e-71d1-11ec-90d6-0242ac130003

This command returns detailed information about the hardware with the given ID.

2. Managing Templates

Templates are reusable definitions of workflows. Here’s how you can manage them with Tink CLI.

Creating a Template

To create a new template, define the template in a YAML file:

# ubuntu-provision.yaml
version: "0.1"
name: "ubuntu-provision"
global_timeout: 1800
tasks:
  - name: "disk-wipe"
    worker: "{{.device_1}}"
    volumes:
      - /dev:/dev
    actions:
      - name: "wipe-disk"
        image: disk-wipe:latest
        timeout: 300
        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: 1200

Push the template to the Tink server:

tink template create --file ubuntu-provision.yaml

This command registers the template so that it can be used in workflows.

Listing Templates

To list all available templates:

tink template list

This command outputs a list of templates, including their IDs and names.

Retrieving Template Details

To view the details of a specific template:

tink template get <template-id>

Replace <template-id> with the actual template ID to see the full details of the template.

3. Managing Workflows

Workflows are where the action happens—they tie together hardware and templates to perform the actual provisioning.

Creating a Workflow

To create a workflow, you’ll need to associate a template with specific hardware:

tink workflow create --template <template-id> --hardware f92d5c9e-71d1-11ec-90d6-0242ac130003

This command creates a workflow based on the specified template and hardware ID.

Listing Workflows

To list all workflows:

tink workflow list

This command shows all workflows currently registered in the system, including their statuses (e.g., running, completed, failed).

Monitoring Workflow Progress

To monitor the progress of a specific workflow:

tink workflow events <workflow-id>

Replace <workflow-id> with the ID of the workflow you want to monitor. This command shows the events and logs associated with the workflow’s execution.

Rerunning a Workflow

If a workflow fails or needs to be rerun, you can use:

tink workflow retry <workflow-id>

This command retries the workflow from the beginning or from the failed step, depending on the configuration.

Advanced Usage of Tink CLI

  1. Scripting and Automation: Tink CLI commands can be scripted to automate complex provisioning tasks. For example, you can write a script that registers hardware, creates templates, and launches workflows in a single automated process.
  2. Integration with CI/CD Pipelines: Tink CLI can be integrated into CI/CD pipelines to automatically provision hardware as part of a build or deployment process. This is particularly useful in environments where physical servers need to be dynamically provisioned and configured for testing or production workloads.
  3. Error Handling and Debugging: Tink CLI provides detailed logs and event tracking for workflows, which can be crucial for debugging and troubleshooting. By using the CLI to monitor and analyze workflow events, you can quickly identify and resolve issues in the provisioning process.
  4. Custom Actions and Extensions: You can extend Tink CLI by integrating custom actions into your workflows. These actions can perform specialized tasks, such as installing specific software packages, configuring network settings, or integrating with external systems.

Conclusion

Tink CLI is a powerful and essential tool for managing the Tinkerbell stack. It provides a user-friendly interface for interacting with Tinkerbell’s core components, enabling you to manage hardware resources, define and deploy templates, and monitor workflows with ease. Whether you’re automating bare-metal provisioning, integrating with CI/CD pipelines, or managing complex infrastructure, Tink CLI offers the flexibility and control needed to efficiently manage your bare-metal environment.