Bare Metal: Installation

This guide walks through a bare-metal installation of Tectonic utilizing PXE-based tools. This document will cover:

1. Overview

Node types

A minimum of 3 machines are required to run Tectonic.

Provisioner node

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

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

Worker nodes

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

Networking requirements

This guide requires familiarity with PXE booting, the ability to configure network services, and to add DNS names. These are discussed in detail below.

2. Provisioning Infrastructure

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.

Download a Matchbox v0.6+ release.

$ wget https://github.com/coreos/matchbox/releases/download/v0.6.1/matchbox-v0.6.1-linux-amd64.tar.gz
$ wget https://github.com/coreos/matchbox/releases/download/v0.6.1/matchbox-v0.6.1-linux-amd64.tar.gz.asc

Untar the release.

$ tar xzvf matchbox-v0.6.1-linux-amd64.tar.gz
$ cd matchbox-v0.6.1-linux-amd64

Install Matchbox on a server or Kubernetes cluster that your bare-metal machines can reach using the guides:

• Installing on CoreOS
• Installing on RPM-based distros
• Installing on generic Linux
• Installing on Kubernetes
• Running with rkt or docker

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

Verify the Matchbox service is running.

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.

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 /var/lib/matchbox/assets,

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

3. Networking

A bare-metal Tectonic cluster requires PXE infrastructure, which we'll setup next.

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:

• Chainload PXE firmwares to iPXE
• Point iPXE client machines to the Matchbox iPXE endpoint (e.g. http://matchbox.example.com:8080/boot.ipxe)

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:

• May keep using existing DHCP, TFTP, and DNS services
• May configure subnets, architectures, or specific machines to delegate to matchbox
• May place matchbox behind a menu entry (timeout and default to matchbox)

If you've never set up a PXE-enabled network before, check out the quay.io/coreos/dnsmasq container image copy-paste examples and see the section about proxy-DHCP.

DNS

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

For example,

• matchbox.example.com resolves to your matchbox deployment
• controllers.example.com resolves to any controller node
• tectonic.example.com resolves 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.

4. Tectonic Installer

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.4-tectonic.1.tar.gz
tar xzvf tectonic-1.6.4-tectonic.1.tar.gz
cd tectonic/tectonic-installer

Run the Tectonic Installer that matches your platform (linux or darwin):

./$PLATFORM/installer

A browser window will open to begin the GUI installation process. When prompted for Matchbox credentials, insert the client.crt, client.key, and ca.crt created previously. You will need to enter machine MAC addresses, domain names, and your SSH public key as well.

Selecting a platform in Tectonic Installer

Once Terraform apply starts, power on your machines via IPMI or by pressing the power button.

5. Tectonic Console

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!

Viewing pods in the Tectonic Console