This webhook allows you to utilize IONOS Cloud as a DNS provider for performing DNS-01 challenges when using cert-manager.
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.
- Simplified integration with IONOS Cloud for DNS-01 challenges
- Secure, automated DNS record management for certificate validation
- Seamless issuance and renewal of TLS certificates
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
- 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 and 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) 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: passwordThe 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
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_VERSIONCheck out the make targets for the development cycle:
make helpDNS providers must run the DNS01 provider conformance testing suite, else they will have undetermined behaviour 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 acccount
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.
The helm chart uses the latest release unless the version is explicitly set using --set image.tag=$VERSION.
| cert-manager-webhook-ionos-cloud | cert-manager |
|---|---|
| v0.6.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 |