Alek's Blog - go

cert-manager-webhook-libdns: One Webhook, Many DNS Providers

aleks — Tue, 03 Mar 2026 00:00:00 +0000

cert-manager-webhook-libdns: One Webhook, Many DNS Providers🔗</a></h1>
Managing DNS-01 challenges with cert-manager often means choosing one provider-specific integration and staying tightly coupled to it. cert-manager-webhook-libdns</a> takes a different approach: it uses the libdns</a> ecosystem so one webhook can support many DNS providers through a shared interface.</p>
If you run mixed infrastructure, migrate between DNS vendors, or just want a cleaner operational model, this project is built for that.</p>

Why this project exists 🔗</a></h2>
In many Kubernetes setups, certificate automation becomes harder than it should be because DNS integrations are fragmented:</p>

Every provider has different APIs, credentials, and operational quirks.</li>
Switching providers often means switching tooling.</li>
Testing and maintenance can become provider-specific and brittle.</li> </ul>
cert-manager-webhook-libdns</a> solves this by exposing a single cert-manager webhook that delegates DNS record operations to pluggable libdns providers.</p>
What it does 🔗</a></h2>
At a high level, the webhook:</p>

Receives DNS-01 challenge requests from cert-manager.</li>
Loads provider credentials from Kubernetes Secrets.</li>
Resolves and writes challenge TXT records through the selected libdns provider.</li>
Cleans up records after validation.</li> </ul>
It supports important real-world behaviors, including:</p>

Handling multiple TXT values for wildcard + apex certificate requests.</li>
Safer fallback logic when record listing fails.</li>
Provider-specific TTL handling (for example, deSEC minimum TTL enforcement).</li>
Deterministic provider listing in CLI output.</li> </ul>
Operational improvements in recent iterations 🔗</a></h2>
Several practical improvements were added to make this project easier to run and maintain:</p>

Semantic version output via `--version</code> (currently v0.5.0</code>).</li>`
`No etcd/envtest dependency in the default make test</code> path.</li>`
`Cleaner container workflow with Containerfile</code> support.</li>`
`Release workflow hardening:</li>`
`tests run before image release</li>`
`latest</code> is only published for stable tags</li>`
`release creation happens after successful image push</li>`
`concurrency guard to prevent overlapping tag releases</li> </ul> These are the kinds of changes that reduce surprises in CI/CD and day-to-day operations.</p>`Provider compatibility is now automated🔗</a></h2> A major maintenance challenge with libdns-based projects is knowing which upstream provider modules are actually compatible with your pinned libdns</code> version.</p> This repository now includes an automated compatibility process:</p> Script: scripts/check_libdns_provider_compat.sh</code></li> Workflow: .github/workflows/libdns-provider-compat.yml</code></li> Report snapshot: docs/01_provider-compat-latest.md</code></li> Historical snapshots: docs/YYYY-MM-DD_provider-compat.md</code></li> </ul> The check uses gh api</code> to scan provider repositories, inspect their go.mod</code>, and classify compatibility against the libdns version used in this project.</p> That gives maintainers a repeatable compatibility signal instead of manual guesswork.</p> Quick start🔗</a></h2> 1. Build and publish the image🔗</a></h3> Use your preferred container runtime (Podman is preferred, Docker fallback is supported):</p> make</span> container-build</span></span> make</span> container-push</span> IMAGE_TAG=v0.5.0</span> REGISTRY=ghcr.io/</span><</span>your-or</span>g</span>></span></span></code></pre>2. Deploy the Helm chart🔗</a></h3> helm</span> install</span> libdns-webhook</span> ./deploy/libdns-webhook</span> \</span></span> -</span>-namespace</span> cert-manager</span> \</span></span> -</span>-set</span> image.repository=ghcr.io/</span><</span>your-or</span>g</span>></span>/cert-manager-webhook-libdns</span> \</span></span> -</span>-set</span> image.tag=v0.5.0</span> \</span></span> -</span>-set</span> groupName=acme.yourdomain.com</span></span></code></pre>3. Create provider credentials secret🔗</a></h3> Example for token-based providers:</p> a</span>piVersion</span>:</span> v</span>1</span></span> k</span>ind</span>:</span> S</span>ecret</span></span> m</span>etadata</span>:</span></span> n</span>ame</span>:</span> d</span>ns-provider-credentials</span></span> n</span>amespace</span>:</span> c</span>ert-manager</span></span> t</span>ype</span>:</span> O</span>paque</span></span> s</span>tringData</span>:</span></span> a</span>pi_token</span>:</span> "</span><YOUR_API_TOKEN></span>"</span></span></code></pre>4. Configure ClusterIssuer🔗</a></h3> a</span>piVersion</span>:</span> c</span>ert-manager.io/v1</span></span> k</span>ind</span>:</span> C</span>lusterIssuer</span></span> m</span>etadata</span>:</span></span> n</span>ame</span>:</span> l</span>etsencrypt-prod</span></span> s</span>pec</span>:</span></span> a</span>cme</span>:</span></span> s</span>erver</span>:</span> h</span>ttps://acme-v02.api.letsencrypt.org/directory</span></span> e</span>mail</span>:</span> y</span>our-email@example.com</span></span> p</span>rivateKeySecretRef</span>:</span></span> n</span>ame</span>:</span> l</span>etsencrypt-prod-account</span></span> s</span>olvers</span>:</span></span> -</span> d</span>ns01</span>:</span></span> w</span>ebhook</span>:</span></span> g</span>roupName</span>:</span> a</span>cme.yourdomain.com</span></span> s</span>olverName</span>:</span> l</span>ibdns</span></span> c</span>onfig</span>:</span></span> p</span>rovider</span>:</span> c</span>loudflare</span></span> s</span>ecretRef</span>:</span></span> n</span>ame</span>:</span> d</span>ns-provider-credentials</span></span> n</span>amespace</span>:</span> c</span>ert-manager</span></span></code></pre>Useful CLI checks🔗</a></h2> Before deployment, you can quickly inspect the binary:</p> ./webhook</span> -</span>-version</span></span> ./webhook</span> -</span>-list-providers</span></span></code></pre> This is helpful for validating exactly what was compiled into your image.</p> Who should use this🔗</a></h2> This project is a strong fit if you:</p> Run cert-manager and use DNS-01 challenges.</li> Need flexibility across multiple DNS providers.</li> Want one consistent webhook integration instead of many provider-specific implementations.</li> Care about release discipline and compatibility visibility.</li> </ul> Final thoughts🔗</a></h2> cert-manager-webhook-libdns</a> is not just a DNS integration layer. It is an operational strategy: keep cert-manager integration stable while letting providers vary underneath.</p> If your platform team wants fewer moving parts and more predictable certificate automation, this is a practical approach worth adopting.</p>