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.

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).


You may set certain optional variables to override defaults.

# install_disk = "/dev/sda"
# container_linux_oem = ""


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.


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.