Tink Server

Deep Dive into Tink Server

Tink Server is the core component of the Tinkerbell stack that orchestrates the interaction between all other Tinkerbell services. It is responsible for managing the lifecycle of hardware, workflows, and templates by exposing a set of RESTful APIs that other components (such as Tink CLI, Rufio, Boots, Hegel, and OSIE) use to carry out their tasks. Essentially, the Tink Server acts as the central brain for bare-metal provisioning operations.

Tink Server Architecture Overview

Tink Server manages the backend logic and the coordination of workflows, templates, and hardware in the Tinkerbell stack. It works in conjunction with other components to handle the full lifecycle of a bare-metal machine, from initial provisioning to deployment, monitoring, and reconfiguration.

Key concepts around Tink Server:

  1. API Management: Tink Server provides a RESTful API that other components use to interact with Tinkerbell. This API allows for operations like hardware registration, workflow creation, and template management.
  2. State Management: Tink Server tracks the state of workflows, hardware, and templates. It records the status of each workflow, ensuring tasks are executed in the correct sequence and reporting any errors.
  3. Orchestration: Tink Server coordinates with services like Boots, OSIE, and Rufio to ensure that the provisioning process is executed seamlessly. It handles the logic for orchestrating hardware provisioning and coordinating interactions between the different components.

Core Components of Tink Server

  • API Server: The central RESTful API that handles requests from clients like Tink CLI and external systems. This is the primary interface through which users and other services interact with Tinkerbell.
  • Workflow Engine: This component manages the execution of workflows, ensuring that tasks are performed in the correct order and on the appropriate hardware.
  • Template Manager: The template manager stores and retrieves reusable provisioning templates that define the tasks to be executed in a workflow.
  • Hardware Manager: This component handles hardware registration, updates, and queries. It tracks the current state of all hardware under Tinkerbell’s control.

Tink Server Provisioning Flow

Here’s how Tink Server fits into the Tinkerbell provisioning process:

  1. Hardware Registration:
  • Bare-metal machines are registered with the Tink Server via Tink CLI or API. The hardware manager stores metadata about the machines, including MAC addresses, IPMI details, and network configuration.
  1. Template Creation:
  • Users create templates that define the provisioning steps for a machine. These templates include tasks like wiping disks, installing operating systems, and configuring networking. The template manager stores and manages these reusable templates.
  1. Workflow Execution:
  • Once hardware is registered and templates are created, users define workflows that link templates to specific hardware. The workflow engine takes over and coordinates the provisioning process by invoking tasks in the defined sequence.
  1. Task Orchestration:
  • Tink Server orchestrates tasks by interacting with other Tinkerbell services, such as Boots (for PXE booting), OSIE (for operating system installation), and Rufio (for BMC management). Tink Server ensures that each task in the workflow is executed and monitors the status of the machine as it progresses through the provisioning process.
  1. Status Monitoring:
  • Tink Server keeps track of the workflow’s state. It logs events, provides status updates, and reports any failures. The state of each machine and task is tracked, and Tink Server ensures that workflows are retried if they fail.

Working Examples with Tink Server

Let’s go through some practical examples of how Tink Server can be used to manage workflows, templates, and hardware resources.

1. Setting Up Tink Server

Tink Server is typically deployed within a Kubernetes environment. Here’s an example Kubernetes manifest to deploy Tink Server:

Tink Server Deployment Manifest
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tink-server
  namespace: tink-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tink-server
  template:
    metadata:
      labels:
        app: tink-server
    spec:
      containers:
      - name: tink-server
        image: quay.io/tinkerbell/tink:latest
        ports:
        - containerPort: 42113
          name: api

This manifest deploys Tink Server in the tink-system namespace and exposes it on port 42113.

Service Definition

To expose the Tink Server within the Kubernetes cluster:

apiVersion: v1
kind: Service
metadata:
  name: tink-server
  namespace: tink-system
spec:
  selector:
    app: tink-server
  ports:
  - protocol: TCP
    port: 42113
    targetPort: 42113

This service makes the Tink Server API available to other components and clients like Tink CLI.

2. Managing Hardware Resources with Tink Server

Tink Server manages the hardware inventory for Tinkerbell. Here’s how you can interact with hardware resources using the Tink CLI, which communicates with Tink Server’s API.

Registering Hardware

To register hardware, you need to create a YAML file that describes the bare-metal machine. Once the file is ready, you push it to the Tink Server:

tink hardware push --file hardware.yaml

This command sends the hardware configuration to the Tink Server, which stores it and makes it available for workflows.

Listing Hardware

To list all hardware resources registered with Tink Server:

tink hardware list

This command retrieves the list of hardware currently stored in Tink Server’s database.

3. Managing Templates with Tink Server

Templates define the tasks that will be executed in a workflow. These templates are stored and managed by Tink Server.

Creating a Template

Here’s how you would define a template in a YAML file:

# template.yaml
version: "0.1"
name: "basic-provision"
global_timeout: 3600
tasks:
  - name: "disk-wipe"
    worker: "{{.device_1}}"
    volumes:
      - /dev:/dev
    actions:
      - name: "wipe-disk"
        image: disk-wipe:latest
        timeout: 600
        environment:
          BLOCK_DEVICE: "/dev/sda"
  - name: "os-install"
    worker: "{{.device_1}}"
    actions:
      - name: "install-os"
        image: osie-installer:latest
        timeout: 2400

You can push this template to Tink Server using the following command:

tink template create --file template.yaml

Tink Server stores this template and makes it available for use in workflows.

Listing Templates

To list all templates stored in Tink Server:

tink template list

This command retrieves the list of available templates.

4. Managing Workflows with Tink Server

Workflows are created by associating a template with specific hardware. Tink Server executes workflows and coordinates the tasks across the relevant hardware.

Creating a Workflow

To create a workflow that provisions hardware using a template:

tink workflow create --template <template-id> --hardware <hardware-id>

This command registers the workflow with Tink Server, which will manage the workflow’s execution.

Monitoring Workflow Progress

To monitor the status of a workflow as it executes:

tink workflow events <workflow-id>

This command shows the events associated with the workflow, providing real-time status updates.

Retrying a Failed Workflow

If a workflow fails, you can retry it using the following command:

tink workflow retry <workflow-id>

Tink Server will re-execute the workflow, either from the failed step or from the beginning, depending on the configuration.

5. Integrating with Other Tinkerbell Services

Tink Server acts as the central point of orchestration in Tinkerbell, working in conjunction with other services like Boots, OSIE, Hegel, and Rufio. Here’s an example of how Tink Server interacts with these components during a typical provisioning process:

  1. Boots: Tink Server coordinates with Boots to initiate PXE booting for bare-metal machines. Boots listens for DHCP requests and provides the necessary boot instructions to the machine.
  2. OSIE: Once the machine is booted, Tink Server instructs OSIE to install the operating system on the machine according to the tasks defined in the workflow.
  3. Hegel: Tink Server ensures that Hegel provides the necessary metadata to the machine during the provisioning process. This metadata includes information like the machine’s network configuration, role, and user-defined data.
  4. Rufio: Tink Server can issue BMC management commands through Rufio, such as powering on the machine, resetting it, or configuring its boot order.

Advanced Usage of Tink Server

  1. API Integration: Tink Server’s RESTful API can be integrated into custom automation scripts, allowing for programmatic management of hardware, workflows, and templates. This can be useful in environments where Tinkerbell is part of a larger infrastructure-as-code or DevOps pipeline.
  2. Custom Workflows: Tink Server allows for highly customizable workflows. You can define templates that include complex sequences of tasks, such as installing multiple operating systems, configuring RAID arrays, or installing specific software packages.
  3. Scaling Tink Server: In large environments, Tink Server can be scaled to handle a high volume of provisioning requests. This involves deploying multiple instances of Tink Server behind a load balancer and ensuring that the backend database can handle concurrent workflow executions.
  4. Monitoring and Logging: Tink Server provides detailed logs and status updates for all workflows. These logs can be integrated with monitoring systems like Prometheus or ELK stacks to provide real-time visibility into the provisioning process and help with troubleshooting.

Conclusion

Tink Server is the heart of the Tinkerbell stack, orchestrating the entire lifecycle of bare-metal provisioning. By managing hardware, templates, and workflows through a powerful RESTful API, Tink Server ensures that all components of Tinkerbell work together seamlessly. Whether you’re registering new hardware, creating reusable templates, or executing complex workflows, Tink Server provides the centralized control needed to manage bare-metal infrastructure efficiently and effectively.