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. 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 a service for network booting and provisioning bare-metal nodes into CoreOS Container Linux clusters.
matchbox should be installed on a provisioner node to serve configs during boot.
The commands to set up
matchbox should be performed on the provisioner node.
Download the latest Tectonic release to the provisioner node and extract it.
wget https://releases.tectonic.com/releases/tectonic_1.5.5-tectonic.2.tar.gz tar xzvf tectonic-1.5.5-tectonic.2.tar.gz cd tectonic/matchbox
matchbox on the provisioner node. You need only choose one of the following options.
On a CoreOS Container Linux provisioner, run
matchbox with the provided systemd unit.
$ sudo cp contrib/systemd/matchbox-for-tectonic.service /etc/systemd/system/matchbox.service
Pre-built binaries are available for generic Linux distributions. Copy the
matchbox static binary to an appropriate location on the provisioner node.
$ cd tectonic/matchbox $ sudo cp matchbox /usr/local/bin $ sudo chmod +x /usr/local/bin/matchbox
matchbox service should be run by a non-root user with access to the
matchbox data directory (
/var/lib/matchbox). Create a
matchbox user and group.
$ sudo useradd -U matchbox $ sudo mkdir -p /var/lib/matchbox/assets $ sudo chown -R matchbox:matchbox /var/lib/matchbox
Copy the provided
matchbox systemd unit file.
$ sudo cp contrib/systemd/matchbox-local.service /etc/systemd/system/matchbox.service
On an RPM-based provisioner, install the
matchbox RPM from the Copr repository using
dnf copr enable @CoreOS/matchbox dnf install matchbox
matchbox by editing the systemd unit or adding a systemd dropin. Find the complete set of
matchbox flags and environment variables at config.
sudo systemctl edit matchbox
By default, the read-only HTTP machine endpoint will be exposed on port 8080. Enable the gRPC API to allow clients with a TLS client certificate to change machine configs. The Tectonic Installer uses this API.
# /etc/systemd/system/matchbox.service.d/override.conf [Service] Environment="MATCHBOX_ADDRESS=0.0.0.0:8080" Environment="MATCHBOX_RPC_ADDRESS=0.0.0.0:8081" Environment="MATCHBOX_LOG_LEVEL=debug"
matchbox to suit your preferences.
Allow your port choices on the provisioner's firewall so the clients can access the service. Here are the commands for those using
$ sudo firewall-cmd --zone=MYZONE --add-port=8080/tcp --permanent $ sudo firewall-cmd --zone=MYZONE --add-port=8081/tcp --permanent
matchbox API allows client apps such as the Tectonic Installer to manage how machines are provisioned. TLS credentials are needed for client authentication and to establish a secure communication channel.
If your organization manages public key infrastructure and a certificate authority, create a server certificate and key for the
matchbox service and a client certificate and key.
Otherwise, generate a self-signed
ca.crt, a server certificate (
server.key), and client credentials (
client.key) with the
scripts/tls/cert-gen script. Export the DNS name or IP (discouraged) of the provisioner node.
$ cd scripts/tls # DNS or IP Subject Alt Names where matchbox can be reached $ export SAN=DNS.1:matchbox.example.com,IP.1:192.168.1.42 $ ./cert-gen
Place the TLS credentials in the default location:
$ sudo mkdir -p /etc/matchbox $ sudo cp ca.crt server.crt server.key /etc/matchbox/
ca.crt generated here will be used later to authenticate Tectonic Installer with Matchbox. Tectonic installer will go on to create a second set of certificates for use in the cluster. These two distinct sets of certificates have different purposes.
matchbox service and enable it if you'd like it to start on every boot.
$ sudo systemctl daemon-reload $ sudo systemctl start matchbox $ sudo systemctl enable matchbox
Verify the matchbox service is running and can be reached by nodes (those being provisioned). It is recommended that you define a DNS name for this purpose (see Networking).
$ systemctl status matchbox $ dig matchbox.example.com
Verify you receive a response from the HTTP and API endpoints.
$ curl http://matchbox.example.com:8080 matchbox $ cd tectonic/matchbox $ openssl s_client -connect matchbox.example.com:8081 -CAfile /etc/matchbox/ca.crt -cert scripts/tls/client.crt -key scripts/tls/client.key CONNECTED(00000003) depth=1 CN = fake-ca verify return:1 depth=0 CN = fake-server verify return:1 --- Certificate chain 0 s:/CN=fake-server i:/CN=fake-ca --- ....
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 will use this feature.
Download a recent CoreOS Container Linux stable release with signatures.
$ ./scripts/get-coreos stable 1298.5.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 │ └── 1235.6.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.
Set up DHCP, TFTP, and DNS services with your network administrator. Review network setup to find the right approach for your PXE environment. At a high level, your goals are to:
matchboxiPXE HTTP endpoint (e.g.
CoreOS provides a dnsmasq container, if you wish to use rkt or Docker.
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.
The Tectonic Installer is a graphical application run on your laptop to create Tectonic clusters. It authenticates to
matchbox via its API.
Your laptop running the Tectonic installer app must be able to access your
matchbox instance. You will need the
client.key credentials created when setting up
matchbox to complete the flow, as well as the
The commands to run the Tectonic Installer should be performed on your laptop.
Download the latest Tectonic release to your laptop and and extract it.
wget https://releases.tectonic.com/releases/tectonic_1.5.5-tectonic.2.tar.gz tar xzvf tectonic-1.5.5-tectonic.2.tar.gz cd tectonic
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.
Run the Tectonic Installer that matches your platform (
A tab should open in your browser. Follow the instructions to enter information needed for provisioning. You will need to enter machine MAC addresses, domain names, and your SSH public key.
Then, you'll be prompted to power on your machines via IPMI or by pressing the power button and guided through the rest of the bring-up. If needed, you can use the generated assets bundle kubeconfig to troubleshoot.
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!