From f62edc6bfe999261e1136c0010d7a3c01974df62 Mon Sep 17 00:00:00 2001 From: Marc Singer Date: Sat, 21 Feb 2026 08:27:36 +0100 Subject: [PATCH] docs: add the main README --- Dockerfile | 2 +- README.md | 155 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 4092c24..892c939 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM golang:1.26.0 AS build +FROM golang:1.26.0-alpine AS build WORKDIR /workspace diff --git a/README.md b/README.md index 09c4d27..665933a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,157 @@ # Cert Manager DeSEC Webhook +

+ cert-manager project logo +

+ +# Independently maintained ACME webhook for desec.io DNS API + +This solver can be used with [desec.io](https://desec.io) DNS API. The documentation of the API can be found [here](https://desec.readthedocs.io/en/latest/) + +## Requirements +- [go](https://golang.org) => 1.26.0 +- [helm](https://helm.sh/) >= v3.0.0 +- [kuberentes](https://kubernetes.io/) => 1.25.0 +- [cert-manager](https://cert-manager.io/) => 1.19.0 + +## Installation + +### Using helm from local checkout +```bash +helm install \ + -n cert-manager \ + desec-webhook \ + charts/cert-manager-desec-webhook +``` + +### Using public helm chart +```bash +helm install \ + -n cert-manager \ + --version \ + desec-webhook \ + oci://ghcr.io/pr0ton11/charts/cert-manager-desec-webhook +``` + +## Uninstallation + +## Creating an issuer + +Create a secret containing the credentials +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: desec-io-token + namespace: cert-manager +type: Opaque +data: + token: your-key-base64-encoded +``` + +We can also then provide a standardised 'testing framework', or set of +conformance tests, which allow us to validate that a DNS provider works as +expected. +Create a 'ClusterIssuer' or 'Issuer' resource as the following: + +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: letsencrypt-staging +spec: + acme: + server: https://acme-staging-v02.api.letsencrypt.org/directory + email: mail@example.com + + privateKeySecretRef: + name: letsencrypt-staging + + solvers: + - dns01: + webhook: + config: + apiKeySecretRef: + key: token + name: desec-io-token + groupName: acme.pr0ton11.github.com + solverName: desec +``` + +## Create a manual certificate + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: example-cert + namespace: cert-manager +spec: + commonName: example.com + dnsNames: + - example.com + issuerRef: + name: letsencrypt-staging + kind: ClusterIssuer + secretName: example-cert +``` + +## Using cert-manager with traefik ingress +```yaml + +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: bitwarden + namespace: utils + labels: + app: bitwarden + annotations: + cert-manager.io/cluster-issuer: letsencrypt-staging + kubernetes.io/ingress.class: traefik + traefik.ingress.kubernetes.io/rewrite-target: /$1 + traefik.ingress.kubernetes.io/router.entrypoints: websecure + traefik.ingress.kubernetes.io/router.tls: 'true' +spec: + tls: + - hosts: + - bitwarden.acme.example.com + secretName: bitwarden-crt + rules: + - host: bitwarden.acme.example.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: bitwarden + port: + number: 80 + +``` + +### Creating your own repository + +### Running the test suite + +All DNS providers **must** run the DNS01 provider conformance testing suite, +else they will have undetermined behaviour when used with cert-manager. + +Provide a secret.yaml in testdata/desec + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: desec-token +data: + token: your-key-base64-encoded +type: Opaque +``` + +Define a **TEST_ZONE_NAME** matching to your authenticaton creditials. + +```bash +$ TEST_ZONE_NAME=example.com. make test +```