# Matchbox for PXE provisioning Fedora CoreOS and Flatcar clusters

> Matchbox is a Go service that selects bare-metal boot profiles by hardware labels and serves iPXE and Ignition data for Fedora CoreOS or Flatcar Linux. It fits controlled bare-metal cluster provisioning, but PXE network setup and production-ready profile configuration remain operator responsibilities.

**poseidon/matchbox** — Network boot and provision Fedora CoreOS and Flatcar Linux clusters

- Repository: https://github.com/poseidon/matchbox
- Website: https://matchbox.psdn.io/
- Stars: 1,428 · Forks: 291
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/poseidon-matchbox

## Why Matchbox targets bare-metal identity

Matchbox addresses a specific part of cluster provisioning: deciding what a physical machine should boot and how that boot should lead to an installed or live operating system. It is intended for infrastructure engineers who repeatedly provision Fedora CoreOS or Flatcar Linux machines and already understand the surrounding network-boot environment. The project does not attempt to be a general-purpose disk imaging service.

The distinguishing mechanism is hardware matching during PXE. A machine presents labels such as a MAC address or UUID, and Matchbox uses those labels to select a profile. That profile supplies the kernel and initrd, an iPXE configuration, and an Ignition configuration. The result is a provisioning path tied to the identity of each machine rather than a single boot image sent indiscriminately across a cluster.

This design is useful when different machines need different kernels, Ignition files, or iPXE behavior. It also creates an important operational boundary. Matchbox cannot provision a machine unless PXE boot reaches it and the network infrastructure correctly supplies DHCP, TFTP, and DNS services. The README identifies a separate PXE-enabled network setup as part of installation rather than presenting the service as a turnkey network-boot appliance.

## How label matching drives the Matchbox boot path

The documented data flow begins when a PXE-capable client contacts the provisioning infrastructure. Matchbox chainloads through iPXE, evaluates labels associated with the hardware, and returns the profile selected for that machine. The profile then describes the boot and initialization inputs needed by the target operating system.

Ignition supplies the provisioning stage for Fedora CoreOS and Flatcar Linux. Matchbox therefore sits between the network boot mechanism and the operating system's declarative configuration. It does not derive configuration from an inventory database exposed by Matchbox itself. Instead, operators define profiles and organize related assets outside the request handler, with the repository providing an `examples/profiles/` directory and separate examples for Ignition, groups, Terraform, and local QEMU/KVM workflows.

Automation is also part of the architecture. Matchbox exposes an authenticated gRPC API for clients such as Terraform, while its documentation also lists an HTTP API. Authentication is therefore relevant when infrastructure automation will manage or consume Matchbox resources. The README does not describe the authentication configuration, token format, authorization policy, or TLS termination procedure, so those details must be checked in `docs/api-grpc.md`, `docs/api-http.md`, and `docs/config.md` before an exposed deployment is accepted.

## Building Matchbox from the Go module

The README lists binary, container, and Kubernetes deployment routes, but the listed excerpt does not provide their full commands. For a source build, the repository's `Makefile` defines an exact development workflow. It expects the toolchain declared in `go.mod`, disables CGO, writes the binary to `bin/matchbox`, and records a version derived from Git tags.

The following builds the Matchbox command from the repository root:

```bash
make build
```

The Makefile maps that target to a Go build of `github.com/poseidon/matchbox/cmd/matchbox`, with its output written to `bin/matchbox`. The declared module uses `go 1.26.0` and `toolchain go1.27.2`. Those declarations are unusually important for adoption because an older compatible toolchain cannot simply be assumed to build the current `main` branch.

After building, the repository also defines the full local check target:

```bash
make all
```

That target invokes build, test, vet, and formatting checks. These commands establish only that the source builds and its repository checks complete. They do not verify PXE delivery, machine matching, Ignition behavior, operating-system installation, or production networking. Those are separate acceptance conditions.

## Starting the first Fedora CoreOS or Flatcar provisioning run

The first real use is an infrastructure exercise rather than merely launching the binary. The repository directs new users to separate tutorials for PXE installation of Fedora CoreOS and Flatcar Linux, as well as local QEMU/KVM workflows for live PXE or installation to disk. It also provides `docs/network-setup.md`, `examples/`, and a Terraform usage tutorial.

A sensible sequence follows the repository structure. First, create the PXE-enabled network described in `docs/network-setup.md`. Next, prepare a profile in the format documented by the project and place its kernel, initrd, iPXE configuration, and Ignition configuration where Matchbox can serve or reference them. Finally, select a target machine by MAC address or UUID and use one of the documented tutorials to perform either a live boot or a disk installation. Matchbox does not accept an arbitrary unidentified client into a default provisioning path merely because it can reach the service; profile matching is central to the documented model.

For teams already using infrastructure as code, the README points to `terraform-provider-matchbox` as the client plugin and labels Terraform usage as a supported tutorial path. The examples also contain a `terraform/` directory. However, the README does not include an exact profile schema, sample request, service startup command, or first Terraform configuration. Copying an invented block would risk introducing unsupported keys, so the appropriate first configuration source is `examples/profiles/` together with the linked documentation.

## Container and Kubernetes deployment boundaries

Matchbox also has a container deployment route. Its Dockerfile builds the application in `docker.io/golang:1.26.5`, copies the compiled binary into `docker.io/alpine:3.24.2`, exposes port `8080`, and sets `/matchbox` as the entrypoint. The Makefile provides multi-platform image targets for `linux/amd64` and `linux/arm64/v8`, followed by manifest operations for the Quay image repository.

The image is only the Matchbox service. It does not replace the DHCP, TFTP, and DNS responsibilities described by the network setup documentation. The repository includes `contrib/dnsmasq/` for running those services in a container, but that is a separate network component rather than proof that the Matchbox image performs PXE delivery by itself. Operators must also decide how the service reaches profiles, boot assets, credentials, and any external provisioning resources.

Kubernetes deployment is documented by the README, but its manifests, storage requirements, service exposure, and network policy are not included in the listed files. A Kubernetes installation may simplify process management, yet it can add a harder network path between PXE clients and Matchbox. That path is the first architectural question to validate: machines must reach the correct boot infrastructure and selected profile assets, not merely reach a healthy service inside the cluster.

## Operational limits, maintenance, and licensing

Matchbox is a poor fit for environments without PXE-capable machines, for operating systems outside Fedora CoreOS and Flatcar Linux, or for teams seeking unattended installation with no network-boot setup. It also does not replace the Terraform provider, DNS and DHCP software, Ignition configuration, or the operator's decisions about machine inventory.

The repository is not archived, and its last push was on 2026-10-15. The most recent listed release is v0.11.0 from 2024-03-24, after v0.10.0 from 2023-04-02 and v0.9.1 from 2022-08-01. This supports continued repository activity but does not establish how frequently a new release will be published. Production operators should distinguish current `main` from the latest tagged release before estimating upgrade work.

The upgrade surface includes a Go module with current pinned dependencies, Ignition v2 packages, gRPC, Cobra, and generated protobuf-related components. The presence of `CHANGES.md` gives maintainers a release-history file, but the repository excerpt does not document upgrade procedures or compatibility guarantees. Matchbox uses the Apache-2.0 license. That identifies the licensed basis of the project, while organizations still need to review license notices and their own distribution obligations separately from Matchbox's technical behavior.

## Conclusion

Adopt Matchbox when an infrastructure team already operates a PXE-capable network and needs repeatable Fedora CoreOS or Flatcar provisioning based on machine identity. Do not choose it for generic disk cloning, hosts without PXE access, or teams unwilling to own DHCP, TFTP, DNS, profile files, and operating-system boot assets. Verify first that a target machine can reach the required network boot services and that its MAC address or UUID will match the profile selectors used by your organization.

## FAQ

### What operating systems can Matchbox provision?

Matchbox provisions Fedora CoreOS and Flatcar Linux through PXE and Ignition. Its documented profiles supply a kernel, initrd, iPXE configuration, and Ignition configuration.

### How does Matchbox select a provisioning profile?

It matches a bare-metal machine to a profile using hardware labels such as MAC address or UUID during PXE. The selected profile determines the boot and Ignition inputs.

### Does Matchbox include the network services required for PXE?

The installation documentation separates Matchbox from setup of a PXE-enabled network. Matchbox also supports a dnsmasq container for DHCP, TFTP, and DNS, but network provisioning still requires deployment and configuration.

### Can Matchbox be managed through Terraform?

The README lists an authenticated gRPC API for clients such as Terraform and points to `terraform-provider-matchbox`. It also provides a Terraform usage tutorial and examples.

## Sources

- [License: Apache-2.0](https://github.com/poseidon/matchbox/blob/main/LICENSE)
- [poseidon/matchbox on GitHub](https://github.com/poseidon/matchbox)
- [Project website](https://matchbox.psdn.io/)
- [README](https://github.com/poseidon/matchbox/blob/main/README.md)
- [Releases](https://github.com/poseidon/matchbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/poseidon-matchbox