This guide walks through a bare-metal installation of Tectonic utilizing PXE-based tools. This document will cover:
|1. Overview||Review types of machines in the cluster
Review networking requirements
|2. Provisioning Infrastructure||Download and install matchbox
Generate TLS assets
|3. Configure Networking||Set up DHCP, TFTP, and DNS services
Configure DNS for the cluster
|4. Tectonic Installer||Install Kubernetes and Tectonic|
|5. Tectonic Console||You're done! Your cluster is ready!|
A minimum of 3 machines are required to run Tectonic.
A provisioner node runs the matchbox network boot and provisioning service, along with PXE services if you don't already run them elsewhere. These are long running infrastructure services. You may use Container Linux or any Linux distribution for this node. It provisions nodes, but does not join Tectonic clusters.
A Tectonic cluster consists of two types of nodes:
Controller nodes run
etcd and the control plane of the cluster.
Worker nodes run your applications. New worker nodes will join the cluster by talking to controller nodes for admission.
This guide requires familiarity with PXE booting, the ability to configure network services, and to add DNS names. These are discussed in detail below.
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.
Download a Matchbox v0.6+ release.
$ wget https://github.com/coreos/matchbox/releases/download/v0.6.0/matchbox-v0.6.0-linux-amd64.tar.gz $ wget https://github.com/coreos/matchbox/releases/download/v0.6.0/matchbox-v0.6.0-linux-amd64.tar.gz.asc
Untar the release.
$ tar xzvf matchbox-v0.6.0-linux-amd64.tar.gz $ cd matchbox-v0.6.0-linux-amd64
Install Matchbox on a server or Kubernetes cluster that your bare-metal machines can reach using the guides:
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
client.key on your local machine (e.g.
Verify the Matchbox service is running.
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.
Download a recent CoreOS Container Linux stable release with signatures.
$ ./scripts/get-coreos stable 1353.7.0 . # note the "." 3rd argument
Move the images to
$ sudo cp -r coreos /var/lib/matchbox/assets
$ tree /var/lib/matchbox/assets /var/lib/matchbox/assets/ ├── coreos │ └── 1353.7.0 │ ├── CoreOS_Image_Signing_Key.asc │ ├── coreos_production_image.bin.bz2 │ ├── coreos_production_image.bin.bz2.sig │ ├── coreos_production_pxe_image.cpio.gz │ ├── coreos_production_pxe_image.cpio.gz.sig │ ├── coreos_production_pxe.vmlinuz │ └── coreos_production_pxe.vmlinuz.sig
and verify the images are accessible.
$ curl http://matchbox.example.com:8080/assets/coreos/SOME-VERSION/ <pre>...
A bare-metal Tectonic cluster requires PXE infrastructure, which we'll setup next.
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:
In the simplest case, an iPXE-enabled network can chain to Matchbox,
# /var/www/html/ipxe/default.ipxe chain http://matchbox.foo:8080/boot.ipxe
Read network-setup for the complete range of options. Network admins have a great amount of flexibility:
The Tectonic Installer will prompt for Controller and Tectonic DNS names.
For the controller DNS name, add a record which resolves to the node you plan to use as a controller.
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 is 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.
matchbox.example.comresolves to your
controllers.example.comresolves to any controller node
tectonic.example.comresolves to any worker nodes
Providing a single entry for Tectonic DNS implies the console will be inaccessible if that node fails. For higher availability, use a load balancer over several worker nodes. Changes to the Tectonic and Controller DNS configuration are not supported after installation.
Make sure a current version of either the Google Chrome or Mozilla Firefox web browser is set as the default browser on the workstation where Installer will run.
Download the Tectonic Installer.
wget https://releases.tectonic.com/releases/tectonic_1.6.2-tectonic.1.tar.gz tar xzvf tectonic-1.6.2-tectonic.1.tar.gz cd tectonic/tectonic-installer
Run the Tectonic Installer that matches your platform (
A browser window should open to begin the GUI installation process. When prompted for Matchbox credentials, insert the
ca.crt created previously. You will need to enter machine MAC addresses, domain names, and your SSH public key as well.
Once Terraform apply starts, power on your machines via IPMI or by pressing the power button.
After the installer is complete, you'll have a Tectonic cluster and be able to access the Tectonic console. You are ready to deploy your first application on to the cluster!