Installation

AWS

Bare Metal

Azure

OpenStack

VMware

Advanced Install

Cluster Administration

Upgrade/Software Updates

User Management

Troubleshooting

User Guides

Deploying Secure Authentication and TLS encryption

This document explains the process of deploying the Tectonic Identity and Console services protected by TLS. After completing the steps below, you will be able to continue with the secure deployment of the Tectonic services.

Prerequisites

A PostgreSQL database must be available for metadata storage. We currently recommend running this database server outside of the cluster to simplify persisting the data stored there. A dedicated database server or virtual machine not joined to the Tectonic cluster can best serve this purpose.

TLS Certificates

You will need two TLS certificate/key pairs, one pair each for Identity and Console. The first part of this document will describe the process of generating those certificates, and the private Certificate Authority (CA) used to sign them. If you are deploying certificates signed by a public CA, skip the CA creation steps and proceed from your CA-issued certificates.

Examples in this guide will use the openssl tool to generate and sign the necessary certificates. If you prefer a different CA tool, this document assumes your ability to adapt the examples to work with it. Alternative CA tools are mentioned briefly at the end of this document.

The second part of this guide will encode the certificates for each service into the format expected by the Kubernetes API so that they can be used in the cluster.

Create CA

First, create a new Certificate Authority to sign the certificates for each service. The following example writes the CA's private key to a file named ca-key.pem, then signs the CA master certificate with that key. The result is two files: ca-key.pem and ca.pem.

The Common Name (CN) set for this CA is determined by the deployer or corporate PKI policy. The value given will work for test environments or smaller scale deployments without existing PKI policy.

Store the CA certificate and key in a secure location for use later in this guide and in the rest of the Tectonic deployment process.

Create the Identity Certificate

OpenSSL Config File for Identity Cert

An openssl config file is convenient since a number of extended certificate options are required. In this configuration, we refer to to placeholder variables: ${K8S_SERVICE_IP} and ${MASTER_HOST}. For common configurations with a single Kubernetes controller, K8S_SERVICE_IP is the first VirtualIP from the Kubernetes SERVICE_IP_RANGE. For the default SERVICE_IP_RANGE of 10.3.0.0/24, this address is 10.3.0.1.

The MASTER_HOST variable is either this same IP address, or a DNS name resolving there. Replace these placeholders with the values appropriate for your environment, and write the configuration to a file named openssl.cnf.

The DNS.* subjectAltNames must be matched to the environment by the deployer, who must ensure DNS resolution for any name configured in these certificates.

Create the Identity Key and Certificate based on the Config File

The following set of shell commands invoke the openssl utility to create a key for the Identity service, generate a request for an Authority to sign a new certificate, and finally generate a certificate for the Identity service, signed by the CA created earlier. Make sure the CA certificate file ca.pem and the openssl.cnf config file are both available.

Save the key and certificate .pem files for conversion to Kubernetes secret format later in this guide.

Create Console Certificate

OpenSSL Config File for Console Cert

An openssl config file is convenient since a number of extended certificate options are required. In this configuration, we refer to to placeholder variables: ${K8S_SERVICE_IP} and ${MASTER_HOST}. For common configurations with a single Kubernetes controller, K8S_SERVICE_IP is the first VirtualIP from the Kubernetes SERVICE_IP_RANGE. For the default SERVICE_IP_RANGE of 10.3.0.0/24, this address is 10.3.0.1.

The MASTER_HOST variable is either this same IP address, or a DNS name resolving there. Replace these placeholders with the values appropriate for your environment, and write the configuration to a file named openssl.cnf.

Create the Console Key and Certificate based on the Config File

The following set of shell commands invoke the openssl utility to create a key for the Console service, generate a request for an Authority to sign a new certificate, and finally generate a certificate for the Console service, signed by the CA created earlier. Make sure the CA certificate file ca.pem and the openssl.cnf config file are both available.

Save the key and certificate .pem files for conversion to Kubernetes secret format later in this guide.

Create Kubernetes Secrets from TLS Certificates

Kubernetes Secret objects are used to configure Tectonic services with the necessary TLS components. The next steps convert the PEM-formatted TLS certificate/key pairs to be used by the Identity and Console services into the format expected by the Kubernetes API. The generate-secrets-from-file.sh script encodes data from the given source file with base64 and wraps the result in the necessary YAML boilerplate to feed to kubectl.

Kubernetes secrets have a name for the secret itself inside Kubernetes, like "tectonic-ca-cert". Each secret in turn contains at least one key with at least one value. For example, a TLS certificate for the CA we created above might be stored inside the tectonic-ca-cert secret, in a key named cert. The base64 encoded certificate is stored as the value of cert.

The generate-secrets-from-file script takes the following arguments:

generate-secrets-from-file.sh <secret> <out.yml> <key,in>

These arguments are:

secret is the name of the Kubernetes secret. Tectonic requires certain secrets before continuing installation.

out is the YAML file to be written containing the secret, and

key,in represents a pair of key, the key name within the secret, and in, the input file containing the value for the key. In this document, in will be one or another path to the certificate and key files generated above.

Step 1: Convert CA Certificate

Convert and load a secret for your CA certificate/key pair (and any intermediaries) so that your cluster can trust the certificate chain to the Identity and Console services: