171 lines
4.8 KiB
Markdown
171 lines
4.8 KiB
Markdown
# cert-manager Webhook for sthome private DNS
|
|
cert-manager Webhook for sthome private DNS is a ACME [webhook](https://cert-manager.io/docs/configuration/acme/dns01/webhook/) for [cert-manager](https://cert-manager.io/) allowing sthome users to use local DNS for DNS01 challenge.
|
|
|
|
## Getting started
|
|
|
|
### Prerequisites
|
|
|
|
- A Kubernetes cluster (v1.19+ recommended)
|
|
- [Helm 3](https://helm.sh/) [installed](https://helm.sh/docs/intro/install/) on your computer
|
|
- cert-manager [deployed](https://cert-manager.io/docs/installation/) on the cluster
|
|
|
|
### Installing
|
|
|
|
- Clone this repository:
|
|
```bash
|
|
git clone https://github.com/stuurmcp/cert-manager-webhook-sthome.git
|
|
```
|
|
|
|
- Run:
|
|
```bash
|
|
helm install sthome-webhook deploy/sthome-webhook
|
|
```
|
|
|
|
### How to use it
|
|
|
|
**Note**: It uses the [cert-manager webhook system](https://cert-manager.io/docs/configuration/acme/dns01/webhook/). Everything after the issuer is configured is just cert-manager. You can find out more from [their documentation](https://cert-manager.io/docs/usage/).
|
|
|
|
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:
|
|
```bash
|
|
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:
|
|
```yaml
|
|
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: acme.sthome.net
|
|
solverName: sthome
|
|
```
|
|
|
|
Run:
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
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: acme.sthome.net
|
|
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 configuration/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:
|
|
```yaml
|
|
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:
|
|
```bash
|
|
kubectl create -f certificate.yaml
|
|
```
|
|
|
|
The certificate should ready after a few seconds:
|
|
```bash
|
|
$ 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:
|
|
```bash
|
|
TEST_ZONE_NAME=radarr.sthome.net make test
|
|
```
|