cert-manager-webhook-ionos-cloud

module

v1.0.5 Latest Latest Go to latest Published: Oct 7, 2026 License: Apache-2.0

README ¶

Alt text

IONOS Cloud DNS Webhook for cert-manager

This webhook allows you to utilize IONOS Cloud as a DNS provider for performing DNS-01 challenges when using cert-manager.

Overview

Cert-manager is a powerful Kubernetes add-on that automates the management and issuance of TLS certificates from various issuing sources. The IONOS Cloud Webhook extends cert-manager's capabilities to manage DNS challenges using IONOS Cloud's DNS services.

Features

Simplified integration with IONOS Cloud for DNS-01 challenges
Secure, automated DNS record management for certificate validation
Seamless issuance and renewal of TLS certificates

Prerequisites

Before proceeding, ensure you have the following:

A Kubernetes cluster with cert-manager installed
An IONOS Cloud account with Cloud DNS API access
kubectl configured to access your Kubernetes cluster

Usage

Install the webhook server

helm repo add cert-manager-webhook-ionos-cloud https://ionos-cloud.github.io/cert-manager-webhook-ionos-cloud
helm upgrade cert-manager-webhook-ionos-cloud \
--namespace cert-manager \
--install cert-manager-webhook-ionos-cloud/cert-manager-webhook-ionos-cloud

[!IMPORTANT] Before engaging into DNS-01, cert-manager does a DNS pre-check (SOA and NS records). Depending on your environment, you may see a failure in the cert-manager logs with the following message: error When querying the SOA record for the domain.... To fix the issue, you need to add the following arguments to the cert-manager: --dns01-recursive-nameservers-only, --dns01-recursive-nameservers=8.8.8.8:53,1.1.1.1:53. For more details, check out the official documentation: https://cert-manager.io/docs/configuration/acme/dns01/#setting-nameservers-for-dns01-self-check

Using a custom cert-manager namespace (optional):

By convention, cert-manager is deployed in a namespace named cert-manager. The chart assumes this default and uses this value to add privileges to the cert-manager service account to enable the creation of resources of type "ionos-cloud". If you are deploying the cert-manager chart in a different namespace, you need to use the certManager.namespace chart value to set the name of the namespace where cert-manager is deployed (e.g., using --set certManager.namespace=custom_namespace)

Authentication Methods

Both username/password and token authentication are supported. The username/password method has the advantage of not requiring the user to intervene periodically. If a token is used, it falls under the responsibility of the user to renew the token periodically (IONOS tokens can have a maximum ttl of 365 days). Regardless of the method used, it is highly recommended to scope the privileges to the DNS management only. This can be done by creating a new IAM user under your main contract, and scoping the privileges to "Access and manage DNS". More details on how to create a bot user can be found here

[!IMPORTANT] It is not recommended to use the credentials of the root/admin account.

Secret Creation:

For token authentication:

See [IONOS Cloud Token management](https://docs.ionos.com/cloud/set-up-ionos-cloud/management/identity-access-management/token-manager) for how to get a token.

```bash
kubectl create secret generic cert-manager-webhook-ionos-cloud \
  --namespace=cert-manager \
  --from-literal=auth-token=<IONOS CLOUD AUTH TOKEN>
```

For username/password authentication:

```bash
kubectl create secret generic cert-manager-webhook-ionos-cloud \
  --namespace=cert-manager \
  --from-literal=username=<IONOS CLOUD USERNAME> \
  --from-literal=password=<IONOS CLOUD PASSWORD>
```

Configuration of the ClusterIssuer/Issuer:

The first step of using cert-manager is creating an Issuer or ClusterIssuer.


apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: example@example.com # Replace this with your email address
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - dns01:
        webhook:
          solverName: ionos-cloud
          groupName: acme.ionos.com
          config:
            #optional, defaults to cert-manager-webhook-ionos-cloud
            secretRef: cert-manager-webhook-ionos-cloud
            #optional, defaults to auth-token
            authTokenSecretKey: auth-token
            #optional, defaults to username
            usernameSecretKey: username
            #optional, defaults to password
            passwordSecretKey: password

The following webhook config options are available:

Name	Description	Required	Default
secretRef	the secret name that contains the IONOS token, it should be in the same namespace as the webhook deployment	no	cert-manager-webhook-ionos-cloud
authTokenSecretKey	the secret key name that contains the token (under `.data`)	no	auth-token
usernameSecretKey	the secret key name that contains the username (under `.data`)	no	username
passwordSecretKey	the secret key name that contains the password (under `.data`)	no	password

Check with a demonstration of Ingress Integration with Wildcard SSL/TLS Certificate Generation Given the preceding configuration, it is possible to exploit the capabilities of the Issuer or ClusterIssuer to dynamically produce wildcard SSL/TLS certificates in the following manner:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-example
  namespace: default
spec:
  secretName: wildcard-example-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  commonName: '*.example.runs.ionos.cloud' # project must be the owner of this zone
  duration: 8760h0m0s
  dnsNames:
    - example.runs.ionos.cloud
    - '*.example.runs.ionos.cloud'
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  namespace: default
  annotations:
    ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: "nginx"
  rules:
    - host: "app.example.runs.ionos.cloud"
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: webapp
                port:
                  number: 80
  tls:
    - hosts:
        - "app.example.runs.ionos.cloud"
      secretName: wildcard-example-tls

Contribute

Verify the image resource integrity

Release images published from tag v* builds are signed keylessly with Cosign using GitHub Actions OIDC identity, and the signature is recorded in the Rekor transparency log. There is no signing key to distribute or trust.

export RELEASE_VERSION=latest
cosign verify \
  --certificate-identity-regexp="^https://github.com/ionos-cloud/cert-manager-webhook-ionos-cloud/" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  ghcr.io/ionos-cloud/cert-manager-webhook-ionos-cloud:$RELEASE_VERSION

Development Workflow

Check out the make targets for the development cycle:

make help

Conformance tests

DNS providers must run the DNS01 provider conformance testing suite, else they will have undetermined behavior when used with cert-manager.

The conformance tests are provided by the cert-manager test package: https://github.com/cert-manager/cert-manager/blob/master/test/acme/suite.go

To run the conformance tests: TEST_ZONE_NAME=test-zone.com IONOS_TOKEN=api-token make conformance-test

the following environment variables must be set:

TEST_ZONE_NAME: the zone for which DNS-01 will be performed

depending on the authentication method, either:

IONOS_TOKEN: the token for accessing IONOS DNS API or :
IONOS_USERNAME: the username of the bot account
IONOS_PASSWORD: the password of the bot account

e2e tests:

The e2e tests run the whole stack on a Kubernetes cluster. Prequisites:

a Kind cluster
Kubectl pointing to the cluster
Helm
Docker (the script builds a docker container based on the current code)

The e2e tests can be run using the run-e2e-tests.sh:

export IONOS_TOKEN=THE_TOKEN
export TEST_ZONE_NAME=THE_ZONE_NAME

./run-e2e-tests.sh --cert-manager-version $version --authentication-method token

or

export IONOS_USERNAME=THE_USERNAME
export IONOS_PASSWORD=THE_PASSWORD
export TEST_ZONE_NAME=THE_ZONE_NAME

./run-e2e-tests.sh --cert-manager-version $version --authentication-method username-password

Based on the operating system and the current user permissions, sudo may be needed to run the script.

Compatibility:

The Helm chart keeps image.tag empty by default and resolves the image tag from the chart appVersion during release packaging (helm package --app-version ...).

If you install directly from source/unpackaged chart, set an explicit image tag:

helm upgrade --install cert-manager-webhook-ionos-cloud \
  cert-manager-webhook-ionos-cloud/cert-manager-webhook-ionos-cloud \
  --namespace cert-manager \
  --set image.tag=<VERSION> \
  --set image.override=true

cert-manager-webhook-ionos-cloud	cert-manager
v1.0.3,v1.0.4,v1.0.5	v1.21.2
v1.0.1,v1.0.2	v1.21.1
v0.6.0,v1.0.0	v1.21.0
v0.5.0	v1.20.1
v0.4.0	v1.19.4
v0.3.3	v1.19.3
v0.3.0	v1.19.1
v0.2.2,v0.2.1	v1.18.1
v0.1.0,v0.1.1	v1.17.1

Directories ¶

Path	Synopsis
cmd
webhook command
internal
clouddns
mocks
resolver

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL