├── Lets_Encrypt_Certificates_for_OCP4.adoc ├── Project_Request_Template.adoc └── README.md /Lets_Encrypt_Certificates_for_OCP4.adoc: -------------------------------------------------------------------------------- 1 | = Requesting and installing Let's Encrypt Certificates for OpenShift 4 2 | 3 | == Overview 4 | 5 | For any OpenShift cluster it is suggested to use proper certificates to secure the routes and API endpoints. 6 | 7 | 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. 8 | 9 | Luckily in OpenShift 4 it is very easy to apply certificates after the installation has completed. 10 | 11 | This document walks through using *Let's Encrypt* to provision certificates for your cluster. You will need to know the API endpoint URL and the Wildcard Domain for your router(s). 12 | 13 | == Installing acme.sh 14 | 15 | If you already have certificates for your domains you may skip this step and go straight to <>. 16 | 17 | 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. 18 | 19 | . Clone the `acme.sh` GitHub repository. 20 | + 21 | [source,sh] 22 | ---- 23 | cd $HOME 24 | git clone https://github.com/neilpang/acme.sh 25 | cd acme.sh 26 | ---- 27 | 28 | . 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. 29 | + 30 | 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: 31 | + 32 | [source,sh] 33 | ---- 34 | #!/usr/bin/env sh 35 | 36 | # 37 | AWS_ACCESS_KEY_ID="YOUR ACCESS KEY" 38 | # 39 | AWS_SECRET_ACCESS_KEY="YOUR SECRET ACCESS KEY" 40 | 41 | #This is the Amazon Route53 api wrapper for acme.sh 42 | 43 | [...] 44 | ---- 45 | 46 | == Requesting Certificates 47 | 48 | . To make things a bit easier set two environment variables. The first variable should point to your API Endpoint. Make sure you are logged into OpenShift as `system:admin` and use the `oc` CLI to find the API Endpoint URL. 49 | + 50 | [source,sh] 51 | ---- 52 | oc whoami --show-server 53 | ---- 54 | + 55 | .Sample Output 56 | [source,texinfo] 57 | ---- 58 | https://cluster-e954-api.e954.ocp4.opentlc.com:6443 59 | ---- 60 | 61 | . Now set the variable LE_API to the fully qualified domain name: 62 | + 63 | [source,sh] 64 | ---- 65 | export LE_API=$(oc whoami --show-server | cut -f 2 -d ':' | cut -f 3 -d '/' | sed 's/-api././') 66 | ---- 67 | 68 | . Set the second variable LE_WILDCARD to your Wildcard Domain for example: 69 | + 70 | [source,sh] 71 | ---- 72 | export LE_WILDCARD=$(oc get ingresscontroller default -n openshift-ingress-operator -o jsonpath='{.status.domain}') 73 | ---- 74 | 75 | . Run the acme.sh script 76 | + 77 | [source,sh] 78 | ---- 79 | ${HOME}/acme.sh/acme.sh --issue -d ${LE_API} -d *.${LE_WILDCARD} --dns dns_aws 80 | ---- 81 | 82 | . 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`. 83 | 84 | + 85 | [source,sh] 86 | ---- 87 | export CERTDIR=$HOME/certificates 88 | mkdir -p ${CERTDIR} 89 | ${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 90 | ---- 91 | 92 | [[installing]] 93 | == Installing Certificates for the Router 94 | 95 | The following instructions work for OpenShift 4.0.0.8 (Installer 0.15) and higher. 96 | 97 | The Router expects the certificates in a `Secret`. This secret needs to be created in the project `openshift-ingress`. 98 | 99 | . Use the following command to create the secret - and if you have existing certificates make sure to provide the path to your certificates instead. 100 | + 101 | [source,sh] 102 | ---- 103 | oc create secret tls router-certs --cert=${CERTDIR}/fullchain.pem --key=${CERTDIR}/key.pem -n openshift-ingress 104 | ---- 105 | 106 | . 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. 107 | + 108 | [source,sh] 109 | ---- 110 | oc patch ingresscontroller default -n openshift-ingress-operator --type=merge --patch='{"spec": { "defaultCertificate": { "name": "router-certs" }}}' 111 | ---- 112 | 113 | . 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. 114 | 115 | . You now have proper certificates on the router - and this includes custom applications, the Web Console for your OpenShift Cluster and the API Endpoint. 116 | -------------------------------------------------------------------------------- /Project_Request_Template.adoc: -------------------------------------------------------------------------------- 1 | = Setting a Project Request Template on OCP4 2 | 3 | . Get the current project request template: 4 | + 5 | [source,sh] 6 | ---- 7 | oc adm create-bootstrap-project-template -o yaml > $HOME/project_request_template.yaml 8 | ---- 9 | 10 | . Edit the template (add LimitRanges, NetworkPolicies, ...) in `$HOME/project_request_template.yaml`. Note the template name: `project-request`. Do not change this template name. 11 | . Create the Project Request template in the `openshift-config` project 12 | + 13 | [source,sh] 14 | ---- 15 | oc create -f $HOME/project_request_template.yaml -n openshift-config 16 | ---- 17 | 18 | . Tell OpenShift to use this template by creating a Custom Resource of type `Project.config.openshift.io/v1` named `cluster` and importing the CustomResource into the `openshift-config` project 19 | 20 | + 21 | [source,sh] 22 | ---- 23 | echo ' 24 | apiVersion: "config.openshift.io/v1" 25 | kind: "Project" 26 | metadata: 27 | name: "cluster" 28 | spec: 29 | projectRequestMessage: "You requested a new project" 30 | projectRequestTemplate: 31 | name: "project-request"' | oc create -n openshift-config -f - 32 | ---- 33 | 34 | . Create a new project and validate that your changes have been applied. 35 | + 36 | [source,sh] 37 | ---- 38 | oc new-project test-project-request 39 | ---- 40 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # openshift-4-alpha-enablement --------------------------------------------------------------------------------