== Development in progess ==

cert-manager Webhook for sthome private DNS

cert-manager Webhook for sthome private DNS is a ACME webhook for cert-manager allowing sthome users to use local DNS for DNS01 challenge.

Getting started

Prerequisites

• A Kubernetes cluster (v1.19+ recommended)
• Helm 3 installed on your computer
• cert-manager deployed on the cluster

Installing

• Clone this repository:

git clone https://github.com/stuurmcp/cert-manager-webhook-sthome.git

• Run:

helm install sthome-webhook deploy/sthome-webhook

How to use it

Note: It uses the cert-manager webhook system. Everything after the issuer is configured is just cert-manager. You can find out more from their documentation.

Now that the webhook is installed, here is how to use it.

But first, Issuers and ClusterIssuers are Kubernetes resources that represent certificate authorities (CAs) capable of generating signed certificates. An Issuer is limited to a single namespace while a ClusterIssuer can issue certificates for a whole cluster.

Let's say you need a certificate for radarr.sthome.net (should be registered in sthome DNS).

First, create a base64 CA bundle: Obtain CA bundle in .pem format, then execute the following on shell command line:

cat /path/to/pem/file/ca.pem | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n//g' | base64 -w0

Replace <cabundle> in .yaml examples below with generated base64 line

Create a cert-manager Issuer. Create a sthome-issuer.yaml file with the following content:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: sthome-issuer
spec:
  acme:
    email: my-user@sthome.net
    # acme URL
    server: https://upd.sthome.net/acme-v02.api
    
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: sthome-private-key-secret
    
    # Private ca's cert bundle in base64
    caBundle: <cabundle>
    solvers:
    - dns01:
        webhook:
          groupName: webhook.acme.cert-manager.io
          solverName: sthome

Run:

kubectl create -f sthome-issuer.yaml

Check the status of the Issuer.

kubectl describe issuer sthome-issuer

Should you need to delete the Issuer, run the following command:

kubectl delete issuer sthome-issuer

Alternatively, to create a ClusterIssuer , create a sthome-clusterissuer.yaml file with the following content:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: sthome-clusterissuer
spec:
  acme:
    # Your ACME server URL.
    server: https://upd.sthome.lan/acme-v02.api

    # Replace this email address with your own, however currently not used
    email: my-user@sthome.net

    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: sthome-acme

    # Private ca's cert bundle in base64
    caBundle: <cabundle>

    solvers:
      - dns01:
          webhook:
            groupName: webhook.acme.cert-manager.io
            solverName: sthome
            #config:
            #  usernameSecretKeyRef:
            #    name: sthome-credentials
            #    key: username
            #  passwordSecretKeyRef:
            #    name: sthome-credentials
            #    key: password

To deploy the Cluster Issuer configuration file, run the following command:

kubectl apply -f sthome-clusterissuer.yaml

Check the status of the Cluster Issuer.

kubectl describe clusterissuer sthome-clusterissuer

Should you need to delete the Cluster Issuer, run the following command:

kubectl delete clusterissuer sthome-clusterissuer

Create the Certificate object for radarr.sthome.net. Create a certificate.yaml file with the following content:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: radarr-sthome-net
spec:
  dnsNames:
  - radarr.sthome.net
  issuerRef:
    name: sthome-issuer
  secretName: radarr-sthome-net-tls

Run:

kubectl create -f certificate.yaml

The certificate should ready after a few seconds:

$ kubectl get certificate radarr-sthome-net
NAME          READY   SECRET                  AGE
example-com   True    radarr-sthome-net-tls   2m21s

The certificate is now available in the radarr-sthome-net-tls secret

Integration testing

Before running the test, you need:

• A valid domain on sthome DNS (here radarr.sthome.net)
• The variables STH_ACCESS_KEY and STH_SECRET_KEY valid and in the environment

In order to run the integration tests, run:

TEST_ZONE_NAME=radarr.sthome.net make test