Skip to content

IONOS Cloud

This tutorial describes how to set up ExternalDNS for use within a Kubernetes cluster using IONOS Cloud DNS.
For more details, visit the IONOS external-dns webhook repository.
You can also find the external-dns-ionos-webhook container image required for this setup.

Creating a DNS Zone with IONOS Cloud DNS

If you are new to IONOS Cloud DNS, we recommend you first read the following instructions for creating a DNS zone:

Steps to Create a DNS Zone

  1. Log in to the IONOS Cloud Data Center Designer.
  2. Navigate to the Network Services section and select Cloud DNS.
  3. Click on Create Zone and provide the following details:
    - Zone Name: Enter the domain name (e.g., example.com).
    - Description: It is optional to provide a description of your zone.
  4. Save the zone configuration.

For more advanced configurations, such as adding records or managing subdomains, refer to the IONOS Cloud DNS Documentation.

Creating an IONOS API Token

To use ExternalDNS with IONOS Cloud DNS, you need an API token with sufficient privileges to manage DNS zones and records. Follow these steps to create an API token:

  1. Log in to the IONOS Cloud Data Center Designer.
  2. Navigate to the Management section in the top right corner and select Token Manager.
  3. Select the Time To Live(TTL) of the token and click on Create Token.
  4. Copy the generated token and store it securely. You will use this token to authenticate ExternalDNS.

Deploy ExternalDNS

Step 1: Create a Kubernetes Secret for the IONOS API Token

Store your IONOS API token securely in a Kubernetes secret:

kubectl create secret generic ionos-credentials --from-literal=api-key='<IONOS_API_TOKEN>'

Replace <IONOS_API_TOKEN> with your actual IONOS API token.

Step 2: Configure ExternalDNS

Create a Helm values file for the ExternalDNS Helm chart that includes the webhook configuration. In this example, the values file is called external-dns-ionos-values.yaml .

logLevel: debug # ExternalDNS Log level, reduce in production

namespaced: false # if true, ExternalDNS will run in a namespaced scope (Role and Rolebinding will be namespaced too).
triggerLoopOnEvent: true # if true, ExternalDNS will trigger a loop on every event (create/update/delete) on the resources it watches.

logLevel: debug
sources:
  - ingress
  - service
provider:
  name: webhook
  webhook:
    image:
      repository: ghcr.io/ionos-cloud/external-dns-ionos-webhook
      tag: latest
      pullPolicy: IfNotPresent
    env:
      - name: IONOS_API_KEY
        valueFrom:
          secretKeyRef:
            name: ionos-credentials
            key: api-key
      - name: SERVER_PORT
        value: "8888"
      - name: METRICS_PORT
        value: "8080"
      - name: DRY_RUN
        value: "false"

Step 3: Install ExternalDNS Using Helm

Install ExternalDNS with the IONOS webhook provider:

helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
helm upgrade --install external-dns external-dns/external-dns -f external-dns-ionos-values.yaml

Deploying an Example Application

Step 1: Create a Deployment

In this step we will create echoserver application manifest with the following content:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: echoserver
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echoserver
  template:
    metadata:
      labels:
        app: echoserver
    spec:
      containers:
      - name: echoserver
        image: ealen/echo-server:latest
        ports:
        - containerPort: 80

Deployment manifest can be saved in echoserver-deployment.yaml file.

Next, we will apply the deployment:

kubectl apply -f echoserver-deployment.yaml

Step 2: Create a Service

In this step, we will create a Service manifest to expose the echoserver application within the cluster. The service will also include an annotation for ExternalDNS to create a DNS record for the specified hostname.

Save the following content in a file named echoserver-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: echoserver
  annotations:
    external-dns.alpha.kubernetes.io/hostname: app.example.com
spec:
  ports:
    - port: 80
      targetPort: 80
  selector:
    app: echoserver

Note: Replace app.example.com with a subdomain of your DNS zone configured in IONOS Cloud DNS. For example, if your DNS zone is example.com, you can use a subdomain like app.example.com.

Next, apply the service:

kubectl apply -f echoserver-service.yaml

This service will expose the echoserver application on port 80 and instruct ExternalDNS to create a DNS record for app.example.com.

Step 3: Create an Ingress

In this step, we will create an Ingress resource to expose the echoserver application externally. The ingress will route HTTP traffic to the echoserver service and include a hostname that ExternalDNS will use to create the corresponding DNS record.

Save the following content in a file named echoserver-ingress.yaml :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echoserver
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: echoserver
            port:
              number: 80

Note: Replace app.example.com with a subdomain of your DNS zone configured in IONOS Cloud DNS. For example, if your DNS zone is example.com, you can use a subdomain like app.example.com.

Next, apply the ingress manifest:

kubectl apply -f echoserver-ingress.yaml

This ingress will expose the echoserver application at http://app.example.com and instruct ExternalDNS to create a DNS record for the specified hostname.

Accessing the Application

Once the Ingress resource has been applied and the DNS records have been created, you can access the application using the hostname specified in the ingress (app.example.com).

Verify Application Access

Use the following curl command to verify that the application is accessible:

curl -I http://app.example.com

Replace app.example.com with the subdomain you configured in your DNS zone.

Note: Ensure that your DNS changes have propagated and that the hostname resolves to the correct IP address before running the command.

Expected result

You should see an HTTP response header indicating that the application is running, such as:

HTTP/1.1 200 OK

Troubleshooting:

If you encounter any issues, verify the following:

  • The DNS record for app.example.com (replace with your own subdomain configured in IONOS Cloud DNS) has been created in IONOS Cloud DNS.
  • The ingress controller is running and properly configured in your Kubernetes cluster.
  • The echoserver application is running and accessible within the cluster.

Verifying IONOS Cloud DNS Records

Use the IONOS Cloud Console or API to verify that the A and TXT records for your domain have been created. For example, you can use the following API call:

curl --location --request GET 'https://dns.de-fra.ionos.com/records?filter.name=app' \
--header 'Authorization: Bearer <IONOS_API_TOKEN>'

Replace <IONOS_API_TOKEN> with your actual API token.

The API response should include the A and TXT records for the subdomain you configured.

Note: DNS changes may take a few minutes to propagate. If the records are not visible immediately, wait and try again.

Cleanup

Optional: Perform the cleanup step only if you no longer need the deployed resources.

Once you have verified the setup, you can clean up the resources created during this tutorial:

kubectl delete -f echoserver-deployment.yaml
kubectl delete -f echoserver-service.yaml
kubectl delete -f echoserver-ingress.yaml

Summary

In this tutorial, you successfully deployed ExternalDNS webhook with IONOS Cloud DNS as the provider.
You created a Kubernetes deployment, service, and ingress, and verified that DNS records were created and the application was accessible.
You also learned how to clean up the resources when they are no longer needed.