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 Ingress controllers with your managed DNS zones in STACKIT DNS, removing the need for manual record keeping.

What is the STACKIT DNS extension?

STACKIT DNS is a managed service for hosting external DNS zones. It allows you to create resource records that are globally distributed automatically by leveraging Anycast DNS. To get started with STACKIT DNS, see “Create your first DNS zone and query it”.

The STACKIT DNS extension bridges the gap between SKE and STACKIT DNS. When exposing your Services and Ingress controllers 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, Ingress, or Gateway API.

Create a primary STACKIT DNS zone

You need a primary STACKIT DNS zone for the extension to work, which can be provisioned via the Portal. To learn how to achieve this, refer to the STACKIT DNS documentation.

Activate the STACKIT DNS extension on your SKE cluster

You can activate the STACKIT DNS extension using the SKE API.

Once you are prepared to use the SKE API, use the following endpoint to activate the extension:

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

In the request body configure the following section:

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

The field gatewayApi is optional and set to false by default. When enabled, external-dns watches Gateway API *Route resources. The Gateway API CRDs must be installed in the cluster before enabling this field. After deploying the CRDs and enabling gatewayApi, the cluster will be reconciled automatically — no manual trigger is needed.

You can also configure the DNS extension via Terraform:

extensions = {
  dns = {
    enabled = true
    zones   = ["<your-domain>.runs.onstackit.cloud"]
  }
}

Note: The gatewayApi field is currently not supported in the Terraform provider. Configure it via the SKE API v2 if you need Gateway API support. See the Terraform stackit_ske_cluster documentation for details.

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. 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 dealing with long domain names.

Expose an application via service or ingress or Gateway

ExternalDNS will pick up any Service with type=LoadBalancer, type=ExternalName or type=NodePort, and all hostnames defined in Ingress or Gateway API routing rules. Note that type=NodePort only creates useful public DNS records when nodes have publicly reachable addresses. For publicly reachable workloads, LoadBalancer, Ingress, or Gateway API are recommended.

• Services: ExternalDNS will look for the external-dns.alpha.kubernetes.io/hostname annotation.
• Ingress: All hosts defined in the rules are used.
• Gateway API: Hostnames from spec.hostnames on HTTPRoute, TLSRoute, GRPCRoute, TCPRoute, or UDPRoute resources are used. If no hostname is specified on the route, listener hostnames from the parent Gateway may be used as a fallback. See the ExternalDNS Gateway source documentation for details.

For more details refer to the ExternalDNS documentation.

Example

Take the following example as a showcase.

• Create a primary DNS zone. You can use a free <your-domain>.runs.onstackit.cloud.
• Activate the extension via the SKE API, defining:

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

Make the following change to your deployment 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.onstackit.cloud.