This repo allows cert-manager to use ExternalDNS to handle ACME challenges.
The default configuration of ExternalDNS needs altering for this integration to function:
- TXT records are not managed by ExternalDNS by default, it requires an extra flag
- The DNSEndpoint CRD is not enabled by default
If you are deploying with the official Helm chart you can accomplish this by including this in your values file:
managedRecordTypes:
- A # ┐
- AAAA # ├ Default values
- CNAME # ┘
- TXT # ─ New value
sources:
- service # ┬ Default values
- ingress # ┘
- crd # ─ New valueAny supported version of cert-manager supports DNS webhooks, for documentation on installing cert-manager see the official documentation
The webhook can be installed using Helm:
# Add the repository
helm repo add cert-manager-webhook-external-dns oci://ghcr.io/lion7/cert-manager-webhook-external-dns
# Install the webhook
helm install external-dns-webhook \
cert-manager-webhook-external-dns/external-dns-webhook \
--namespace cert-managerYou can also install directly from the OCI registry:
helm install external-dns-webhook \
oci://ghcr.io/lion7/cert-manager-webhook-external-dns/external-dns-webhook \
--namespace cert-managerThe default values should work for most installations. You can customize the installation by creating a values file:
# values.yaml
image:
repository: ghcr.io/lion7/cert-manager-webhook-external-dns
tag: latest
pullPolicy: IfNotPresent
replicaCount: 1
resources:
limits:
cpu: 100m
memory: 128Mi
requests:
cpu: 100m
memory: 128Mi
# Webhook configuration
webhook:
port: 8443
# cert-manager configuration
certManager:
namespace: cert-manager
serviceAccountName: cert-managerThen install with:
helm install external-dns-webhook \
oci://ghcr.io/lion7/cert-manager-webhook-external-dns/external-dns-webhook \
--namespace cert-manager \
-f values.yamlTo configure an issuer to use ExternalDNS you just specify the group and solver name within the Issuer or ClusterIssuer config:
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: example-issuer
spec:
acme:
...
solvers:
- dns01:
webhook:
groupName: cert-manager-webhook.lion7.dev
solverName: external-dnsThe solver takes an optional config:
webhook:
groupName: cert-manager-webhook.lion7.dev
solverName: external-dns
config:
ttl: 60 # TTL of the challenge record in seconds, 60 when not set
providerSpecific: [] # copied to the endpoint's providerSpecificThe webhook creates one DNSEndpoint object per challenge record, named after the domain and a
hash of the record name, in the namespace of the Issuer (or the cluster resource namespace for a
ClusterIssuer). A domain and its wildcard are validated on the same _acme-challenge record, so
their keys become two targets of the same TXT endpoint. Cleaning up a challenge removes its key,
and the object once no key is left.
The endpoint has no set identifier. Most DNS providers cannot store one, and ExternalDNS then never matches the endpoint with the record it created for it: it creates the same record on every sync.
Run ExternalDNS with --policy=sync to have the challenge record removed after validation. With
--policy=upsert-only the last challenge value of every record stays behind.
All DNS providers must run the DNS01 provider conformance testing suite, else they will have undetermined behaviour when used with cert-manager.
It is essential that you configure and run the test suite when creating a DNS01 webhook.
A test file has been provided in main_test.go.
You can run the test suite with:
go test ./...See TESTING.md for the test binaries it needs.
The test suite includes a mock DNS server with external-dns controller simulation to provide comprehensive testing without requiring external DNS provider credentials.
