Bare Metal: Installation

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

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

Networking requirements

This guide requires familiarity with PXE booting, the ability to configure network services, and to add DNS names. Networking requirements include:

• matchbox installation with gRPC API enabled and TLS client credentials.
• CoreOS Container Linux images installed and available in the Matchbox cache.
• PXE enabled network boot environment with DHCP, TFTP, and DNS services.

Installation and setup of these three items is detailed below.

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.

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 Container Linux
• 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.8.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.8.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/1353.8.0/
<pre>...

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:

• 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. They may choose to:

• Keep using existing DHCP, TFTP, and DNS services
• Configure subnets, architectures, or specific machines to delegate to matchbox
• 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

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.

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 Tectonic Installer.

wget https://releases.tectonic.com/releases/tectonic_1.6.10-tectonic.1.tar.gz
tar xzvf tectonic_1.6.10-tectonic.1.tar.gz
cd tectonic/tectonic-installer

Run the Tectonic Installer for your platform:

For macOS users:

$ ./tectonic-installer/darwin/installer

For Linux users:

$ ./tectonic-installer/linux/installer

For Windows users, see this guide.

A browser window will open to begin the GUI installation process, which will require the following information:

• DNS: Domain names assigned for the master and worker nodes, which must exist before launching Tectonic Installer.
• CoreOS License and Pull Secret: Available from account.coreos.com when logged in to the CoreOS account associated with this installation.
• Matchbox endpoints: The HTTPS and API addresses for your matchbox endpoints.
• Matchbox credentials: The client.crt, client.key, and ca.crt generated when installing Matchbox.
• 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!

Viewing pods in Tectonic Console