cert-manager - ExternalDNS webhook

This repo allows cert-manager to use ExternalDNS to handle ACME challenges.

Requirements

ExternalDNS

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 value

cert-manager

Any supported version of cert-manager supports DNS webhooks, for documentation on installing cert-manager see the official documentation

Installing

Using Helm

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-manager

Using OCI Registry

You 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-manager

Configuration

The 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-manager

Then install with:

helm install external-dns-webhook \
  oci://ghcr.io/lion7/cert-manager-webhook-external-dns/external-dns-webhook \
  --namespace cert-manager \
  -f values.yaml

Usage

To 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-dns

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.

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:

make test

The test suite includes a mock DNS server with external-dns controller simulation to provide comprehensive testing without requiring external DNS provider credentials.