Porkbun Webhook for cert-manager

An implementation of the cert-manager webhook.Solver interface for Porkbun. This is based on cert-manager/webhook-example, with inspiration from baarde/cert-manager-webhook-ovh

Subdomain Support

This webhook properly supports issuing certificates for multi-level subdomains (e.g., *.subdomain.example.com, *.subdomain.example.net). The webhook automatically detects the authoritative Porkbun zone by querying the Porkbun API, ensuring that ACME DNS-01 challenges work correctly even when cert-manager passes incorrect zone information for subdomains. This enables environment-specific wildcard certificates for multi-environment Kubernetes deployments without requiring manual DNS delegation or workarounds.

Installation

Install cert-manager

Install cert-manager using its installation documentation.

Install webhook

Add helm repo:

helm repo add cert-manager-webhook-porkbun https://pabloa.github.io/cert-manager-webhook-porkbun

Generate a porkbun API key and create a secret with it:

apiVersion: v1
stringData:
  PORKBUN_API_KEY: pk1_yourapikeyhere
  PORKBUN_SECRET_API_KEY: sk1_yoursecretkeyhere
kind: Secret
metadata:
  name: porkbun-secret
  namespace: cert-manager
type: Opaque

Install helm chart in a namespace of your choice, e. g. cert-manager:

helm install cert-manager-webhook-porkbun cert-manager-webhook-porkbun/cert-manager-webhook-porkbun -n cert-manager

Add an issuer (change the email address; the groupName has to match the groupName value of the helm chart), e. g.:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-issuer
spec:
  acme:
    email: youremailhere@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-porkbun-tls
    solvers:
    - dns01:
        webhook:
          groupName: cert-manager-webhook-porkbun.pabloa.dev
          solverName: porkbun
          config:
            apiKey:
              key: PORKBUN_API_KEY
              name: porkbun-secret
            secretApiKey:
              key: PORKBUN_SECRET_API_KEY
              name: porkbun-secret

Add a certificate, e. g.:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: prod-cert
spec:
  secretName: prod-cert
  issuerRef:
    name: letsencrypt-issuer
    kind: ClusterIssuer
  dnsNames:
  - 'mysub.example.com'

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.

An example Go test file has been provided in main_test.go.

Before running the tests, you need to configure your Porkbun API credentials:

1. Enable API Access for your domain - Go to your domain's settings in Porkbun and enable the "API Access" option. This must be enabled for each domain you want to test with.
2. Get your API credentials from Porkbun API settings
3. Base64 encode your credentials:

   echo -n "pk1_your_api_key" | base64
   echo -n "sk1_your_secret_key" | base64

4. Update testdata/porkbun/porkbun-credentials.yaml with your base64-encoded values
5. Set TEST_ZONE_NAME to a domain you own in Porkbun (must have API Access enabled)

You can run the test suite with:

$ TEST_ZONE_NAME=yourdomain.com. make test

See testdata/porkbun/README.md for detailed instructions.

Note: The tests will create and delete actual TXT records in your DNS zone.