Tinkerbell: Bare-Metal Provisioning

By Kokil Thapa | Last reviewed: September 2026

Tinkerbell: bare-metal provisioning solves a problem every growing team hits eventually. You outgrow VPS instances, but you still need repeatable OS installs on physical machines. Cloud APIs do not exist on a rack in Kathmandu or a colo in Singapore. You need DHCP, network boot, disk imaging, and post-install configuration without clicking through a remote KVM for each server. Linux system administration at scale starts here. Tinkerbell gives you a workflow engine for that entire chain.

What Is Tinkerbell Bare-Metal Provisioning and How Does It Work?

Tinkerbell is an open-source bare-metal provisioning stack maintained under the CNCF. Equinix Metal created it to provision thousands of physical servers daily. The project treats each machine as a workflow target, not a snowflake you configure by hand.

The modern Tinkerbell Stack (v2.x) runs on Kubernetes. Four core services handle the boot chain and execution logic. You define what happens to each server in YAML templates. Tink schedules tasks. HookOS runs them on the bare metal itself.

Core Components Explained

• Smee — Listens for DHCP requests and serves iPXE scripts. It tells each machine where to fetch HookOS and which workflow to run.
• Tink — Stores hardware records, workflow templates, and task definitions. It is the control plane for provisioning logic.
• Hegel — Exposes instance metadata over HTTP, similar to a cloud metadata service. HookOS and install scripts read config from here.
• HookOS — A minimal Linux environment that boots over the network. It runs workflow actions like disk partitioning, image writes, and reboot commands.

In my experience maintaining production Linux servers, the shift from manual installs to workflow-driven provisioning cuts deployment errors sharply. A missed partition scheme or wrong SSH key no longer depends on who sat at the KVM console that day.

How Do You Install the Tinkerbell Stack on Kubernetes?

Tinkerbell Stack v2 expects a running Kubernetes cluster. That cluster can live on three small VMs while you bootstrap your first bare-metal nodes. Many teams deploy Tinkerbell onto an existing management cluster rather than bare metal itself.

The official Helm chart is the fastest path for a lab setup. You need Helm 3.x, kubectl access, and a namespace ready.

1. Add the Tinkerbell Helm repository and update your local chart index.
2. Create a dedicated namespace, for example tinkerbell.
3. Configure Smee with your provisioning network CIDR and relay settings if DHCP crosses subnets.
4. Install the stack chart and verify all pods reach Running state.
5. Register your first hardware record in Tink before powering on the target server.

helm repo add tinkerbell https://tinkerbell.org/charts
helm repo update

kubectl create namespace tinkerbell

helm install tinkerbell tinkerbell/stack \
  --namespace tinkerbell \
  --set smee.hostIP=<PROVISIONING_IP> \
  --set smee.publicIP=<PROVISIONING_IP>

kubectl get pods -n tinkerbell

Smee typically needs host networking or a macvlan/CNI setup so it can answer DHCP on the same L2 segment as your bare-metal machines. This is the most common misconfiguration I see on real deployments. The pod runs fine, but no server ever PXE boots because DHCP packets never reach it.

For deeper Kubernetes networking on physical hosts, see our guide on Kubernetes on bare metal with MetalLB. Storage for workflow artifacts may also need a StorageClass with dynamic provisioning.

How Do You Define Tinkerbell Workflows for OS Installation?

Workflows are the heart of Tinkerbell bare-metal provisioning. A workflow binds a template to a specific hardware ID. The template lists actions executed in order inside HookOS.

You define three Kubernetes custom resources: a Template, a Workflow, and a Hardware record. The hardware record maps MAC addresses to machine identity and metadata.

Example Hardware and Workflow YAML

apiVersion: tinkbell.org/v1alpha1
kind: Hardware
metadata:
  name: worker-01
  namespace: tinkerbell
spec:
  metadata:
    instance:
      hostname: worker-01
      allow_pxe: "true"
  interfaces:
    - dhcp:
        mac: "b4:2e:99:3a:11:01"
        ip:
          address: 10.10.0.21
          netmask: 255.255.255.0
          gateway: 10.10.0.1
---
apiVersion: tinkbell.org/v1alpha1
kind: Template
metadata:
  name: ubuntu-2404-install
  namespace: tinkerbell
spec:
  data: |
    version: "5.4"
    name: ubuntu-2404
    global_timeout: 1800
    tasks:
      - name: os-install
        worker: "{{ .device_1 }}"
        volumes:
          - /dev:/dev
          - /dev/console:/dev/console
          - /lib/firmware:/lib/firmware:ro
        actions:
          - name: disk-wipe
            image: quay.io/tinkerbell-actions/disk-wipe:v1.0.0
          - name: image2disk
            image: quay.io/tinkerbell-actions/image2disk:v1.0.0
            timeout: 900
            environment:
              DEST_DISK: /dev/sda
              COMPRESSED: "true"
              IMG_URL: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img.tar.gz
          - name: reboot
            image: quay.io/tinkerbell-actions/reboot:v1.0.0

After applying the hardware and template, create a Workflow resource that links them. Power-cycle the machine with PXE enabled in BIOS. Smee answers DHCP. The machine chainloads iPXE, pulls HookOS, and Tink dispatches each action container.

Custom actions are plain OCI images. If you already containerize tooling, you can wrap disk layout scripts, RAID setup, or firmware updates as Tinkerbell actions. Validate JSON workflow payloads with a JSON formatter before applying them to the cluster.

How Does Tinkerbell Compare to MAAS, cloud-init, and Terraform?

Teams evaluating bare-metal automation often compare three tools. Each solves a different slice of the problem. Tinkerbell focuses on the install moment. Other tools handle inventory, config, or VM creation.

Tinkerbell and MAAS overlap most directly. MAAS bundles DHCP, DNS, IPAM, and Ubuntu image streaming into one product. Tinkerbell stays composable. You bring your own Kubernetes, storage, and observability stack.

cloud-init does not replace Tinkerbell. HookOS can write a cloud-init datasource to disk during workflow execution. The install workflow and the first-boot config layer work together cleanly.

For config after the OS exists, Ansible or cloud-init still apply. Read our comparison of Ansible vs Terraform for provisioning vs configuration and the follow-up on where each tool stops.

What Production Patterns Work for Tinkerbell Bare-Metal Provisioning?

Lab success with Tinkerbell differs from production reliability. These patterns come from common bare-metal operations practice and align with how I deploy Linux infrastructure for client workloads.

Separate Provisioning and Production Networks

Keep PXE traffic on a dedicated VLAN. Only BMC ports and NICs used for provisioning need access. Production traffic stays isolated. This limits blast radius if a malformed workflow wipes the wrong disk.

GitOps Workflow Templates

Store Template and Hardware YAML in Git. Use Argo CD or Flux to sync them to the management cluster. Pull requests become your change audit trail. Pair this with CI validation so broken templates never reach Smee.

Post-Install Configuration With Ansible

Tinkerbell installs the base OS. Ansible playbooks then harden SSH, install PHP-FPM 8.3 or 8.4, configure MySQL 9.7, and deploy your Laravel 13 application. See Ansible playbooks for PHP server provisioning for a concrete pattern on Ubuntu 24.04 hosts.

Observability From Day One

Export Tink workflow status to Prometheus. Alert when workflows stall in disk-write steps. Disk failures and bad image URLs show up as long-running workflows, not clean error messages. Add Alertmanager rules early. Our Prometheus Alertmanager guide covers routing those alerts.

For Laravel or Symfony workloads on owned hardware, this stack removes manual OS installs before Deployer 7 or GitLab CI can even run. Several sister sites I maintain on shared EC2 today could move to bare-metal workers with the same CI pipeline once Tinkerbell delivers identical Ubuntu images every time.

Hardware costs in Nepal vary widely. A used enterprise 1U server might run Rs 80,000–150,000 (~USD 600–1,100). Colo power adds Rs 5,000–15,000 per month (~USD 37–110). Tinkerbell makes that capital expense worthwhile only if reprovisioning stays hands-off. Manual KVM work erodes the cost advantage fast.

Common Gotchas

• UEFI vs BIOS boot mode — iPXE scripts differ. Pick one mode per hardware pool and enforce it in firmware settings.
• Wrong MAC in Hardware CR — Tink ignores unknown machines. The server boots into an old local disk or loops PXE forever.
• Image URL timeouts — Pulling large cloud images over a slow uplink exceeds default action timeouts. Mirror images locally or raise timeouts.
• DHCP conflicts — An existing router handing DHCP prevents Smee from owning the boot chain. Disable rogue DHCP or use DHCP relay.

Official references: the Tinkerbell project documentation, the Tinkerbell GitHub repository, and the CNCF Tinkerbell project page for governance and roadmap status.

If you run mixed infrastructure, pair this with AIOps practices for modern infrastructure so provisioning failures surface before a capacity crunch. For ongoing hardening after install, testing and optimization services and support and maintenance cover the application layer above bare metal.

On a booking platform like Adventure Third Pole Trek, consistent server builds mean staging matches production. That reduces deployment surprises when Laravel 13, Livewire, and queue workers land on freshly provisioned hosts.

Key Takeaways

• Tinkerbell bare-metal provisioning uses Smee, Tink, Hegel, and HookOS to PXE-boot physical servers and run install workflows as OCI actions.
• Deploy the Stack on Kubernetes via Helm, isolate provisioning traffic on a dedicated VLAN, and register every machine by MAC address before boot.
• Define install logic in Template YAML; combine disk-wipe, image2disk, and reboot actions for repeatable Ubuntu or custom OS images.
• Tinkerbell handles the install moment; use cloud-init or Ansible afterward and Terraform only for API-driven cloud resources.
• Store templates in Git with GitOps sync, export workflow metrics to Prometheus, and alert on stuck provisioning runs.
• Validate UEFI/BIOS mode, DHCP ownership, and image mirror location before scaling beyond a lab—those four issues cause most production failures.

People Also Ask

Does Tinkerbell require Kubernetes?

Tinkerbell Stack v2 runs its control plane as services on Kubernetes. You need at least a small management cluster to host Smee, Tink, and Hegel. That cluster can itself run on VMs while you bootstrap your first bare-metal nodes.

Can Tinkerbell install Windows or only Linux?

Workflow actions are OCI containers, so Linux installs are the common path with prebuilt actions like image2disk. Windows is possible with custom actions that apply WIM images, but the ecosystem and examples skew heavily toward Linux cloud images.

How is Tinkerbell different from Cobbler or Foreman?

Cobbler and Foreman are traditional bare-metal tools tied to monolithic installs. Tinkerbell uses cloud-native patterns—Kubernetes CRDs, containerized actions, and GitOps-friendly templates—aimed at teams already running K8s infrastructure.

Is Tinkerbell production-ready in 2026?

Equinix Metal used Tinkerbell at scale for years, and the project lives under CNCF governance. Production readiness depends on your team's Kubernetes skills and network design. Start with a staging rack, harden observability, then expand.

Build Repeatable Bare-Metal Infrastructure

Tinkerbell bare-metal provisioning turns rack servers into workflow targets you can reprovision from zero in minutes. That matters when you run Kubernetes workers, database replicas, or dedicated Laravel hosts on hardware you actually own. Start with one machine, one Template, and a mirrored OS image. Expand only after DHCP, MAC registration, and post-install Ansible runs work without manual intervention every time.

Need help designing provisioning pipelines, Kubernetes on metal, or the application layer above it? Contact us or explore enterprise application development and Linux system administration services. For related reading, browse the blog, learn more about my infrastructure work, or review hosting and domain setup options for Nepal-based deployments.