GETTING STARTED

This getting started guide was developed under the same lofty goal of EVERY Kubernetes getting started guide: The Goal: To be EASY. And we lived up to that goal if you don’t include the tricky parts that we sprinkled in just for meanness. So tread without fear, but keep your wits about you…

before you start your quest you will need:

kubectl, helm and curl command line tools

access to a Kubernetes cluster (preferably non-production)

access to a domain or subdomain (you must be able to configure the DNS entries)

And don’t forget to keep your wits.

INSTALL THE OPERATOR

To install the operator open a terminal and run this:

curl http://uberscott.com/recert5/files/recert5-operator.yaml | kubectl apply -f -

this will configure Kubernetes to recognize Recert5’s CRDs and install a recert5 deployment that will be the heart of the operator.

check to make sure everything is up and running before you move on

kubectl get pods -n recert5-system                                                                            195ms  Sun Jul 25 20:19:51 2021
NAME                                          READY   STATUS    RESTARTS   AGE
recert5-controller-manager-795b888849-lp9ht   2/2     Running   0          29s

Notice that the controller manager is in the Running STATUS.

DOWNLOAD THE HELM CHARTS

curl http://uberscott.com/recert5/files/helm-charts.zip --output helm-charts.zip

UNZIP THE HELM CHARTS

unzip helm-charts.zip

BUG ALERT

RECERT 5.0.0 will only work if you run the rest of the commands in this tutorial within the ‘recert5-system’ namespace. You can set the namespace like this:

kubectl config set-context --current --namespace=recert5-system

Our team of millions of developers are working to fix this issue and get a 5.0.1 patch out so certs can be installed cluster-wide.

INSTALL A MOCK NGINX WEBSITE

This will serve as our mock website.

In the newly unzipped helm directory:

helm install example nginx

INSTALL RECERT SSL REVERSE PROXY

helm install ssl-reverse-proxy ssl-reverse-proxy

Here is the YAML file to install: BUT READ THE NOTES BEFORE INSTALLING!

apiVersion: recert5.uberscott.com/v1
kind: RecertSSLReverseProxy
metadata:
  name: example
spec:
  pass: "http://example-nginx:80"
  replicas: 1
  storage-class: standard

IMPORTANT NOTES: And Here’s the snag we hit every time we think we are just about to start having fun installing an operator: “Need the storage-class for your cluster.” WHY it needs a storageclass is something that we say we explain later somewhere on the website, but then don’t really explain it. Anyway, the reason is really boring… like Certbot needs a PVC to store some data… suffice it to say that ALL of Recert5 will NOT work without a correctly working storage-class… so don’t get any bright ideas about skipping this part…

If you are running kubernetes on GCP like the lazy author of this getting started guide then choose ‘standard’ for storage class as shown in the example since GKE automatically has standard installed. For any other platform you will have to discover what your favorite devops administrator named it when he set up the cluster. You can list the available storage classes using kubectl like so:

kubectl get sc

You want to use the cheapest and least reliable option available since this storage space is only used very infrequently…. if “just-tell-kubernetes-i-wrote-it-down-on-a-piece-of-paper-somewhere…” is available - use that.

MORE NOTES ABOUT THE YAML: You can also see the ‘pass’ directive which tells recert5’s nginx reverse proxy where to pass it’s traffic.

And finally you can see the replicicas directive in case your website is more popular than Recert5 and you may need kubernetes to spread the load. After you are done testing the nginx example it is by changing ‘pass’ and ‘replicas’ that you can exert all kinds of self expression and make recert5 your own!

FIND THE REVERSE PROXY EXTERNAL IP ADDRESS

Now let’s get our external IP address:

kubectl get service example-nginx-ssl-reverse-proxy

The output should look something like this:

NAME                              TYPE           CLUSTER-IP   EXTERNAL-IP     PORT(S)                      AGE
example-nginx-ssl-reverse-proxy   LoadBalancer   10.0.7.13    34.134.55.212   80:30783/TCP,443:30321/TCP   80s

NOTE: The EXTERNAL-IP may be in a pending state for several minutes as a static IP is provisioned. Don’t Hit the Kubernetes cluster to make it go faster, its workind hard and doing the best job it can!

Keep a copy the EXTERNAL-IP address for the next step.

SET DNS RECORDS FOR YOUR TEST DOMAIN

Now you will need to modify your DNS records for the test domain you are using. In our example we are using example.uberscott.com

In this example we would make a new A record for example.uberscott.com and point it to the external IP address that the service assigned: ‘34.134.55.212’… of course use the IP address YOU see not the one I just wrote for you, right?

CHECK DNS RESOLUTION

DNS propogation can take days, however, if you selected a subdomain that wasn’t in use before like “recert5-test.my-domain.com” in my experience it can resolve immediately since there should be no caching conflicts.

curl http://example.uberscott.com/

Notice we are just testing HTTP traffic at this point, which should resolve to the Nginx example webpage we setup earlier.

you shoul see an output of the default nginx page:

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
    body {
        width: 35em;
        margin: 0 auto;
        font-family: Tahoma, Verdana, Arial, sans-serif;
    }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

CREATE A RECERT CR

Lastly we create the Recert CR which will bind the domain to the ReverseSSLProxy.

to run this helm chart you must pass YOUR domain and YOUR email as a parameterized value.

helm install recert recert --set Domain=example.uberscott.com --set Email=your@email.com

Let’s Encrypt does require an email for payment of services rendered. I think, the email address is used for some marketing stuff and also will tell you when if there are any problems with your cert. Uhm, we at Recert5 also use your email address so we can say ‘hello’ to people using our product once in a while since we don’t have a lot of friends. Dont' worry we’ll be very nice to your email address while its in our care!

So Again, let’s look under the hood at the yaml file we just generated via our helm chart:

apiVersion: recert5.uberscott.com/v1
kind: Recert
metadata:
  name: example
spec:
  domain: {{ .Values.Domain }}
  email: {{ .Values.Email }}
  sslReverseProxy: example

As you can see it takes the Domain and Email as a templated value, but also we are pointing this Recert to the sslReverseProxy named ‘example’ which we created earlier.

The certification process can take several minutes to complete. In the meantime you can periodically check the status of the recertification process like this:

kubectl get recert.recert5.uberscott.com -o=jsonpath="{.items[0].status.state}"

which will return a status of Pending, Creating, Failed or Updated.

When the status is Updated, that means the certification process succeeded.

It may then take a few more seconds for the SSLReverseProxies to restart with the new certificates.

You can now run the same curl test you ran before on the HTTP using HTTPS:

curl https://example.uberscott.com/

And you should get an identical result as HTTP:

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
    body {
        width: 35em;
        margin: 0 auto;
        font-family: Tahoma, Verdana, Arial, sans-serif;
    }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

CONGRATULATIONS!

You have just setup your first Recert5 instance hopefully without injuring yourself or others!

Copyright 2021 Uberscott.