The etcd3-install example shows how to use matchbox to network boot and provision 3-node etcd3 cluster on bare-metal in an automated way.


Follow the getting started tutorial to learn about matchbox and set up an environment that meets the requirements:

  • Matchbox v0.6+ installation with gRPC API enabled
  • Matchbox provider credentials client.crt, client.key, and ca.crt
  • PXE network boot environment
  • Terraform v0.9+ and terraform-provider-matchbox installed locally on your system
  • 3 machines with known DNS names and MAC addresses

If you prefer to provision QEMU/KVM VMs on your local Linux machine, set up the matchbox development environment.

sudo ./scripts/devnet create


Clone the matchbox project and take a look at the cluster examples.

$ git clone
$ cd matchbox/examples/terraform/etcd3-install

Copy the terraform.tfvars.example file to terraform.tfvars. Ensure references your matchbox credentials.

matchbox_http_endpoint = ""
matchbox_rpc_endpoint = ""
ssh_authorized_key = "ADD ME"

Configs in etcd3-install configure the matchbox provider, define profiles (e.g. cached-container-linux-install, etcd3), and define 3 groups which match machines by MAC address to a profile. These resources declare that the machines should PXE boot, install Container Linux to disk, and provision themselves into peers in a 3-node etcd3 cluster.

Fetch the profiles Terraform module which let's you use common machine profiles maintained in the matchbox repo (like etcd3).

$ terraform get

Plan and apply to create the resoures on Matchbox.

$ terraform plan
Plan: 10 to add, 0 to change, 0 to destroy.
$ terraform apply
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.

Note: The cached-container-linux-install profile will PXE boot and install Container Linux from matchbox assets. If you have not populated the assets cache, use the container-linux-install profile to use public images (slower).


Power on each machine (with PXE boot device on next boot). Machines should network boot, install Container Linux to disk, reboot, and provision themselves as a 3-node etcd3 cluster.

$ ipmitool -H -U USER -P PASS chassis bootdev pxe
$ ipmitool -H -U USER -P PASS power on

For local QEMU/KVM development, create the QEMU/KVM VMs.

$ sudo ./scripts/libvirt create
$ sudo ./scripts/libvirt [start|reboot|shutdown|poweroff|destroy]


Verify each node is running etcd3 (i.e. etcd-member.service).

$ ssh
$ systemctl status etcd-member

Verify that etcd3 peers are healthy and communicating.

$ etcdctl cluster-health
$ etcdctl set /message hello
$ etcdctl get /message

Going Further

Learn more about matchbox or explore the other example clusters.