How to use the STACKIT DNS extension with your cluster

This tutorial guides you through the necessary steps to enable the STACKIT DNS extension on your STACKIT Kubernetes Engine (SKE) cluster. Activating this extension allows for the automatic synchronization of your Kubernetes Services and Ingresses with your managed DNS zones in STACKIT DNS, eliminating manual record keeping.

What is the STACKIT DNS extension?

STACKIT DNS is a managed service to host your external DNS zones, allowing you to easily create resource records that are automatically globally distributed leveraging Anycast DNS. See more on how to get started with STACKIT DNS in the documentation.

The STACKIT DNS extension bridges the gap between SKE and STACKIT DNS. When exposing your Services and Ingresses you likely want to make them discoverable via DNS. It can be tedious to keep your exposed IPs and DNS records in sync. This is where STACKIT DNS extension comes into play. By deploying a fully managed ExternalDNS deployment in your cluster’s control plane all required DNS records are created, updated and cleaned up for you to make your deployments available via DNS.

Learn more on how ExternalDNS works or get started with the STACKIT DNS extension in the section below.

How to use the STACKIT DNS extension

To benefit from automation provided by the STACKIT DNS extension follow these steps:

• Create a primary STACKIT DNS zone.
• Activate the STACKIT DNS extension on your SKE cluster.
• Expose an application via Service or ingress.

Create a primary STACKIT DNS zone

You need a primary STACKIT DNS zone for the extension to work, which can easily be done via the portal. Read more on how to achieve this in the STACKIT DNS documentation.

Activate the STACKIT DNS extension on your SKE cluster

You can activate the STACKIT DNS extension using the SKE API. You can find out how to connect to the SKE API here.

Once ready to use the SKE API use the following endpoint to activate the extension:

PUT v1/projects/{projectId}/clusters/{clusterName}

In the request body configure the following section:

...
"extensions":
{
    ...
    "dns":
    {

    "enabled": true,
    "zones":
    [
    "<your-dns-zone>"
    ]
  }
  ...
},

The field zones acts as a filter and is optional. When not defining a zone for which the STACKIT DNS extension is activated, the extension will try to sync DNS records for all exposed addresses. You can use wildcards when defining a zone, for example *.example.runs.on.stackit.cloud. Please note that due to technical reasons wildcards are replaced with x-stackit-dns-wildcard for the created A- and TXT-Records inside your STACKIT DNS zone. Keep this in mind when handling long domain names.

Expose an application via service or ingress

ExternalDNS will pick up any Service with type=LoadBalancer, type=ExternalName or type=NodePort and all hostnames defined in Ingresses.

For Services ExternalDNS will look for the external-dns.alpha.kubernetes.io/hostname annotation. For Ingresses all hosts defined in the rules are used. For more details please refer to the ExternalDNS documentation.

Example

As a simple showcase take the example Wordpress deployment on SKE.

• Create a primary DNS zone. You can use a free <your-domain>.runs.on.stackit.cloud.
• Activate the extension via ske-api, defining

...
"extensions":
{
  ...
  "dns":
  {

   "enabled": true,
   "zones":
   [
    "<your-domain>.runs.onstackit.cloud"
    ]
 }
  ...
},

Make the following change to the Wordpress deployment (notice lines 9-10) and apply it:

...
---
apiVersion: v1
kind: Service
metadata:
  name: wordpress
  labels:
    app: wordpress
  annotations:
    external-dns.alpha.kubernetes.io/hostname: wp.<your-domain>.runs.onstackit.cloud
spec:
  type: LoadBalancer
  ports:
    - name: wordpress
      port: 80
  selector:
    app: wordpress
---
...

After a short time your site can be reached via wp.<your-domain>.runs.on.stackit.cloud.