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

Create systemd Service

RPM-based Distribution

On an RPM-based provisioner, install the matchbox RPM from the Copr repository using dnf.

dnf copr enable @CoreOS/matchbox
dnf install matchbox

Customization

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

Generate TLS Credentials

The 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.crt, server.key), and client credentials (client.crt, client.key) with the scripts/tls/cert-gen script. Export the DNS name or IP (discouraged) of the provisioner node.

The client.crt, client.key, and 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.

Start matchbox

Start the matchbox service and enable it if you'd like it to start on every boot.

CoreOS provides a dnsmasq container, if you wish to use rkt or Docker.

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.

4. Tectonic Installer

The Tectonic Installer is a graphical application run on your laptop to create Tectonic clusters. It authenticates to matchbox via its API.

Requirements

Your laptop running the Tectonic installer app must be able to access your matchbox instance. You will need the client.crt and client.key credentials created when setting up matchbox to complete the flow, as well as the ca.crt.

The commands to run the Tectonic Installer should be performed on your laptop.

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.

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!