For a more complete list of hardware and networking requirements, please see the bare metal requirements document.

1. Node and networking requirements

Node types

A minimum of 3 machines are required to run Tectonic.

Provisioner node runs the matchbox network boot and provisioning service, along with PXE services (if not running elsewhere). You may use Container Linux or any Linux distribution for this node. It provisions nodes, but does not join Tectonic clusters.

Controller nodes run etcd and the control plane of the Tectonic cluster.

Worker nodes run your applications in Tectonic clusters. New worker nodes join the cluster by talking to controller nodes for admission.

For more information, see [Bare metal installation requirements][requirements.md].

2. Provision Infrastructure

Download and configure matchbox

Matchbox is an open source service for on-premise environments that matches bare metal machines to profiles in order to PXE boot Container Linux clusters and automate cluster provisioning. Matchbox provides an authenticated API for clients like Tectonic Installer and Terraform. Profiles will define the kernel, initrd, iPXE config, and Container Linux config each node should use.

Be sure to enable the gRPC API and use the TLS generation script to create server and client certificates. This can be done following the "Customization" and "Generate TLS" sections. Save the ca.crt, client.crt, and client.key on your local machine (e.g. ~/.matchbox).

Download CoreOS Container Linux

Matchbox can serve CoreOS Container Linux images to reduce bandwidth usage and increase the speed of CoreOS Container Linux PXE boots and installs to disk. Tectonic Installer detects the highest version number available in the Matchbox cache.

3. Configure Networking

A bare metal Tectonic cluster requires PXE infrastructure.

PXE-enabled network

Tectonic works with many on-premise network setups. Matchbox does not seek to be the DHCP server, TFTP server, or DNS server for the network. Instead, it serves iPXE scripts as the entrypoint for provisioning network booted machines. At a high level, the goals are to:

DNS

Tectonic Installer will prompt for Controller and Tectonic DNS names.

Controller DNS

For the controller DNS name, add a record which resolves to the node you plan to use as a controller.

Tectonic DNS

By default, Tectonic Ingress runs as a Kubernetes Daemon Set across all worker nodes. For the Tectonic DNS name, add a record resolving to any nodes you plan to use as workers. Tectonic Console will be accessible at this DNS name. Choosing a Tectonic DNS type depends on the available infrastructure. Provide either a single DNS entry, round-robin DNS records, or the name of a load balancer fronting the workers on ports 80 and 443.

Machine MAC addresses: The MAC address for the machines on which the cluster will be built. The MAC address plus the DNS tell Matchbox (the provisioner node) what image to serve the machines (worker and master nodes).

SSH public key: The public key for the machine on which Tectonic Installer is running.

Selecting a platform in Tectonic Installer

Click Submit to launch Terraform apply, then power on your machines via IPMI or by pressing the power button. Matchbox will configure your machine, load Container Linux, and allow cluster creation to begin.

5. Tectonic Console

After the installer is complete, you'll have a Tectonic cluster and be able to access Tectonic Console. You are ready to deploy your first application on to the cluster!