We’re integrating Tectonic with Red Hat OpenShift

We are bringing the best of Tectonic to Red Hat OpenShift to build the most secure, hybrid Kubernetes application platform.

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.

$ openssl genrsa -out ca-key.pem 2048
$ openssl req -x509 -new -nodes -key ca-key.pem -days 10000 -out ca.pem -subj "/CN=tectonic-ca"

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.

openssl.cnf
[req]
req_extensions = v3_req
distinguished_name = req_distinguished_name
[req_distinguished_name]
[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = identity
DNS.2 = identity.default
IP.1 = ${K8S_SERVICE_IP}
IP.2 = ${MASTER_HOST}

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.

Three files result: identity-key.pem, identity.csr, and identity.pem.

$ openssl genrsa -out identity-key.pem 2048
$ openssl req -new -key identity-key.pem -out identity.csr -subj "/CN=tectonic-identity" -config openssl.cnf
$ openssl x509 -req -in identity.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out identity.pem -days 365 -extensions v3_req -extfile openssl.cnf

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.

openssl.cnf
[req]
req_extensions = v3_req
distinguished_name = req_distinguished_name
[req_distinguished_name]
[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = console
DNS.2 = console.default
IP.1 = ${K8S_SERVICE_IP}
IP.2 = ${MASTER_HOST}

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.

Three files result: console-key.pem, console.csr, and console.pem.

$ openssl genrsa -out console-key.pem 2048
$ openssl req -new -key console-key.pem -out console.csr -subj "/CN=tectonic-console" -config openssl.cnf
$ openssl x509 -req -in console.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out console.pem -days 365 -extensions v3_req -extfile openssl.cnf

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:

$ ./generate-secrets-from-file.sh tectonic-ca-cert tectonic-ca-cert.yml cert,ca.pem

After conversion, load it into the cluster:

$ kubectl create -f tectonic-ca-cert.yml
secrets/tectonic-ca-cert

Step 2: Convert Identity Certificate

Given TLS certificate/key pairs for the Identity service in files identity.pem and identity-key.pem, we can produce a secret-format YAML file by invoking:

$ ./generate-secrets-from-file.sh tectonic-identity-cert tectonic-identity-cert.yml cert,identity.pem key,identity-key.pem

Then, load it into the cluster:

$ kubectl create -f tectonic-identity-cert.yml
secrets/tectonic-identity-cert

Step 3: Convert Console Certificate

$ ./generate-secrets-from-file.sh tectonic-console-cert tectonic-console-cert.yml cert,console.pem key,console-key.pem

Afterwards, load it into the cluster:

$ kubectl create -f tectonic-console-cert.yml
secrets/tectonic-console-cert

The Identity and Console services are now equipped with TLS certificates authenticating and encrypting connections between them and their cluster.