MachineCFG

MachineCFG is a specialized CLI tool designed to bridge the gap between your Inventory Management System (NetBox) and your provisioning stack (Tinkerbell or Talos Linux).

It automates the generation of configuration files by fetching hardware data and mapping them to Butane/Ignition configurations, Tinkerbell Hardware objects or Talos MachineConfig patches .

---

✨ Key Features

• NetBox Integration: Automatically fetches device details, MAC addresses, and roles via the NetBox API.
• Butane Templating: Converts YAML Butane configurations into JSON Ignition files on the fly.
• Tinkerbell Automation: Generates the necessary Hardware objects to deploy devices using a MaaS
• Talos Linux Automation: Generates the necessary Machine patches to manage networking.
• Infrastructure as Code: Ensures your physical deployment matches your "Source of Truth".

🚀 Getting Started

Prerequisites

• Go (version 1.25.4 or higher)
• A running NetBox instance with an API token.
• Devices properly configured in Netbox in order to be managed.
• A working Kubernetes cluster for some features.

Installation

Using task:

task cli

Using Nix:

nix-build

⚙️ Configuration

MachineCFG requires access to your NetBox instance. Set the following environment variables:

Variable	Description
NETBOX_URL	The base URL of your NetBox instance (e.g., https://netbox.example.com)
NETBOX_TOKEN	Your NetBox API Token

A custom field called Domains can be added to IPAM/Prefix in order to manage systemd-networkd option Domains.

The hostname set in /etc/hostname of generated Ignition files is derived from the DNS name of the device's primary IPv4 address (or primary IP if no IPv4 is set). If no DNS name is configured, the device name is used as a fallback.

Netbox-side, devices' statuses are very important. They allow the tool to know which device to create and delete.

Device status	Tinkerbell action
Offline	The device is not connected. The Hardware should deleted.
Planned	The device is not ready yet but you know where to install it.
Staged	The device is ready for commissioning. The Hardware can be created.
Active	The Workflow succeeded. The status has been updated to "Active".
Decommissioning	The device needs to be decommissioned from a cluster. Some cleanup Workflow can be triggered too.
Failed	The Workflow failed.

Here is a typical workflow.

stateDiagram-v2
  direction LR

  state if_failure_staged <<choice>>
  state if_failure_deco <<choice>>

  [*] --> Offline
  Offline --> Planned
  Planned --> Staged
  Staged --> if_failure_staged
  if_failure_staged --> Active: Success
  if_failure_staged --> Failed: Failure
  Active --> Decommissioning
  Decommissioning --> if_failure_deco
  if_failure_deco --> Offline: Success
  if_failure_deco --> Failed: Failure

Loading

🛠 Usage

The tool operates by mapping NetBox ressources to create configuration objects.

Command	Description
butane / ignition	Manage butane / ignition configurations
talos	Manage Talos Linux
tinkerbell	Manage Tinkerbell objects

Create Tinkerbell Hardware objects

Embed Fedora CoreOS vendor data and add objects directly into Kubernetes.

./machinecfg \
    --netbox-endpoint $NETBOX_ENDPOINT --netbox-token $NETBOX_TOKEN \
    --sites paris-dc1 --roles cattle \
  tinkerbell hardware sync \
    --embed-ignition-as-vendor-data \
    --embedded-ignition-variant=fcos

Enable PXE boot on Hardware objects

Enable PXE boot (AllowPXE=true) on all Hardware objects in a namespace:

./machinecfg tinkerbell hardware pxe-allow \
    --namespace tinkerbell-system

Or target a single machine by hostname:

./machinecfg tinkerbell hardware pxe-allow \
    --namespace tinkerbell-system \
    --hostname my-server

The aliases allow-pxe and deny-pxe are also available for pxe-allow and pxe-deny respectively.

Show Hardware objects

Display all Hardware objects in a namespace with their PXE and Workflow boot settings:

./machinecfg tinkerbell hardware show \
    --namespace tinkerbell-system

Example output:

HOSTNAME           STATUS    ALLOW-PXE   WORKFLOW
server-paris-01    staged    true        true
server-paris-02    active    false       false
server-paris-03    offline   false       false

Or inspect a single machine:

./machinecfg tinkerbell hardware show \
    --namespace tinkerbell-system \
    --hostname server-paris-02

Create Ignition files

Write an .ign file per device into /tmp, using Flatcar variant.

./machinecfg \
    --netbox-endpoint $NETBOX_ENDPOINT --netbox-token $NETBOX_TOKEN \
    --sites maison --roles cattle \
  ignition flatcar \
    --output-directory /tmp

Create Talos Linux patches

./machinecfg \
    --netbox-endpoint $NETBOX_ENDPOINT --netbox-token $NETBOX_TOKEN \
    --sites paris-dc1 --roles cattle \
  talos machineconfig \
    --output-directory /tmp