cert-manager-webhook-ionos-cloud

module

v1.0.2 Latest Latest Go to latest Published: Sep 4, 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

All official webhooks provided by IONOS are signed using Cosign. The Cosign public key can be found in the cosign.pub file.

Note: Due to the early development stage of the webhook, the image is not yet signed by sigstores transparency log.

export RELEASE_VERSION=latest
cosign verify --insecure-ignore-tlog --key cosign.pub 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.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