Skip to content

poseidon/terraform-provider-matchbox

Folders and files

NameName
Last commit message
Last commit date
Feb 15, 2025
Mar 25, 2024
May 7, 2019
May 15, 2024
Aug 2, 2017
Mar 25, 2024
May 27, 2019
Apr 4, 2017
Apr 4, 2017
Jun 22, 2024
Mar 25, 2024
Apr 21, 2025
Apr 21, 2025
Dec 7, 2020

Repository files navigation

terraform-provider-matchbox

GoDoc Workflow Downloads Sponsors Mastodon

terraform-provider-matchbox allows defining Matchbox Profiles and Groups in Terraform. Matchbox matches machines, by label (e.g. MAC address), to Profiles with iPXE configs, Ignition configs, or generic free-form configs to provision clusters. Resources are created via the client certificate authenticated Matchbox API.

Usage

Setup a PXE network boot environment and deploy a Matchbox instance. Be sure to enable the gRPC API and follow the instructions to generate TLS credentials.

Configure the Matchbox provider with the Matchbox API endpoint and client certificate (e.g. providers.tf).

provider "matchbox" {
  endpoint    = "matchbox.example.com:8081"
  client_cert = "${file("~/.matchbox/client.crt")}"
  client_key  = "${file("~/.matchbox/client.key")}"
  ca          = "${file("~/.matchbox/ca.crt")}"
}

terraform {
  required_providers {
    matchbox = {
      source = "poseidon/matchbox"
      version = "0.5.4"
    }
  }
}

Define a Matchbox Profile or Group resource in Terraform.

// Fedora CoreOS profile
resource "matchbox_profile" "fedora-coreos-install" {
  name  = "worker"
  kernel = "https://builds.coreos.fedoraproject.org/prod/streams/${var.os_stream}/builds/${var.os_version}/x86_64/fedora-coreos-${var.os_version}-live-kernel-x86_64"

  initrd = [
    "--name main https://builds.coreos.fedoraproject.org/prod/streams/${var.os_stream}/builds/${var.os_version}/x86_64/fedora-coreos-${var.os_version}-live-initramfs.x86_64.img"
  ]

  args = [
    "initrd=main",
    "coreos.live.rootfs_url=https://builds.coreos.fedoraproject.org/prod/streams/${var.os_stream}/builds/${var.os_version}/x86_64/fedora-coreos-${var.os_version}-live-rootfs.x86_64.img",
    "coreos.inst.install_dev=/dev/sda",
    "coreos.inst.ignition_url=${var.matchbox_http_endpoint}/ignition?uuid=$${uuid}&mac=$${mac:hexhyp}"
  ]

  raw_ignition = data.ct_config.worker.rendered
}

data "ct_config" "worker" {
  content = templatefile("fcc/fedora-coreos.yaml", {
    ssh_authorized_key = var.ssh_authorized_key
  })
  strict = true
}

// Default matcher group for machines
resource "matchbox_group" "default" {
  name    = "default"
  profile = matchbox_profile.fedora-coreos-install.name
  selector = {}
  metadata = {}
}

Run terraform init to ensure plugin version requirements are met.

$ terraform init

See examples for Terraform configs which PXE boot, install CoreOS, and provision entire clusters.

Requirements

  • Terraform v0.13+ installed
  • Matchbox v0.8+ installed
  • Matchbox credentials client.crt, client.key, ca.crt

Development

Binary

To develop the provider plugin locally, build an executable with Go 1.18+.

make