Requesting and installing Let’s Encrypt Certificates for OpenShift 4

Overview

Red Hat OpenShift uses certificates to encrypt the communication with the Web Console as well as applications exposed as Routes. Without any further customization the install process will create self-signed certificates. While these work they usually trigger severe security warnings about unknown certificates in Web Browsers when accessing either the Web Console or any other application that is exposed via HTTPS.

Therefore for any Red Hat OpenShift cluster, it is suggested to use proper certificates to secure the routes and API endpoints. For many years, this required paying for the generation of those certificates and managing them across an organization. Today, thanks to Let’s Encrypt, this process can be automated and performed for free.

In OpenShift 3, certificates are usually added during the installation process by modifying the /etc/ansible/hosts file. In OpenShift 4 however there is no mechanism to provide certificates during the installation process. Adding certificates is considered a post-installation task.

Luckily in OpenShift 4, it is reasonably straighforward to apply certificates after the installation has completed.

This blog walks through using Let’s Encrypt to provision certificates for your cluster in AWS. You will need to know the API endpoint URL and the Wildcard Domain for your router(s).

Installing acme.sh

If you already have certificates for your domains, you may skip this step and go straight to Installing Certificates for the Router.

In order to request Let’s Encrypt certificates we will use the acme.sh client. This client makes it very easy to request and update certificates.

  1. Clone the acme.sh GitHub repository.
cd $HOME
git clone https://github.com/neilpang/acme.sh
cd acme.sh
  1. Update the file $HOME/acme.sh/dnsapi/dns_aws.sh with your AWS access credentials. This is necessary because you are requesting a certificate for wildcard domain and Let’s Encrypt needs a way to validate that you are the owner of the wildcard domain.
  2. Open the file in your favorite text editor and then add your AWS credentials. You will also need to remove the comment (#) before these two lines. The top of the file should look like this:
#!/usr/bin/env sh
#
AWS_ACCESS_KEY_ID="YOUR ACCESS KEY"
#
AWS_SECRET_ACCESS_KEY="YOUR SECRET ACCESS KEY"
#This is the Amazon Route53 api wrapper for acme.sh
[...]

Requesting Certificates

  1. Make sure that you are connected to your Red Hat OpenShift Cluster. You can either do these steps from a bastion host that you installed Red Hat OpenShift from or you can log into the cluster as a user that has cluster administrator permissions. Right after the installation this includes the system:admin and kubeadmin users.
  2. To make things a bit easier, set two environment variables. The first variable should point to your API Endpoint. Use the oc CLI to find the API Endpoint URL.
oc whoami --show-server
Sample Output
https://cluster-e954-api.e954.ocp4.opentlc.com:6443
  1. Now set the variable LE_API to the fully qualified domain name:
export LE_API=$(oc whoami --show-server | cut -f 2 -d ':' | cut -f 3 -d '/' | sed 's/-api././')
  1. Set the second variable LE_WILDCARD to your Wildcard Domain for example:
export LE_WILDCARD=$(oc get ingresscontroller default -n openshift-ingress-operator -o jsonpath='{.status.domain}')
  1. Run the acme.sh script
${HOME}/acme.sh/acme.sh --issue -d ${LE_API} -d *.${LE_WILDCARD} --dns dns_aws
  1. It is usually a good idea to move the certificates from the acme.sh default path to a well known directory. So use the –install-cert option of the acme.sh script to copy the certificates to $HOME/certificates.
export CERTDIR=$HOME/certificates
mkdir -p ${CERTDIR}
${HOME}/acme.sh/acme.sh --install-cert -d ${LE_API} -d *.${LE_WILDCARD} --cert-file ${CERTDIR}/cert.pem --key-file ${CERTDIR}/key.pem --fullchain-file ${CERTDIR}/fullchain.pem --ca-file ${CERTDIR}/ca.cer

Installing Certificates for the Router

The following instructions work for OpenShift 4.0.0.8 (Installer 0.15) and higher.

The Router expects the certificates in a Secret. This secret needs to be created in the project openshift-ingress.

  1. Use the following command to create the secret – and if you have existing certificates, make sure to provide the path to your certificates instead.
oc create secret tls router-certs --cert=${CERTDIR}/fullchain.pem --key=${CERTDIR}/key.pem -n openshift-ingress
  1. Now update the Custom Resource for your router. The default custom resource is of type IngressController, is named default and is located in the openshift-ingress-operator project. Note that this project is different from where you created the secret earlier.
oc patch ingresscontroller default -n openshift-ingress-operator --type=merge --patch='{"spec": { "defaultCertificate": { "name": "router-certs" }}}'
  1. This is all you need to do. After you update the IngressController object the OpenShift ingress operator notices that the custom resource has changed and therefore re-deploys the router.

You now have proper certificates on the router – and this includes custom applications, the Web Console for your OpenShift Cluster and the API Endpoint.

Categories
Containers, Security
Tags
, , ,