Skip to content

Network: ExternalDNS

What is ExternalDNS?

With kubara you can deploy ExternalDNS into your Kubernetes cluster (see https://kubernetes-sigs.github.io/external-dns/latest/).
ExternalDNS ensures that DNS records are automatically created and updated as soon as you define Ingress, Service, or supported Traefik resources with hostnames.

Info

ExternalDNS will be rolled out as a Helm Chart when you enable the service in your config.yaml.

Workflow

  1. Prepare DNS zone
  2. kubara generates the necessary Terraform definitions (modules and variables) for DNS setup.
  3. You then run Terraform yourself to actually create the zone.
  4. If you use your own domain, you must delegate the nameservers of this zone at your registrar.

  5. Provider-specific behavior depends on your DNS platform.

  6. Enable ExternalDNS

  7. In config.yaml you enable the service external-dns.
  8. Then you must rerun kubara (kubara generate) so that Terraform files and Helm values are re-rendered with the new settings.
  9. Configure provider-specific values in platform-configs/<cluster-name>/helm/external-dns/values-*.yaml, for example values-provider.yaml.
  10. Next steps:
    • run terraform apply to provision DNS resources,
    • git commit & push the Helm chart changes so that Argo CD/Flux deploys them to the cluster.

  11. At this point the ExternalDNS Helm Chart will be deployed from Argo CD in the cluster.

  12. Automatic records

  13. When you deploy an application with Ingress or Service including a hostname (e.g. app.example.com), ExternalDNS automatically creates the corresponding DNS record in your configured zone.
  14. Changes or deletions are also reflected automatically.

Provider configuration

kubara includes ExternalDNS webhook configuration for terraform.provider: stackit and terraform.provider: t-cloud-public. It generates the webhook image and required authentication configuration for those providers.

For another DNS provider, add platform-configs/<cluster-name>/helm/external-dns/values-provider.yaml. If ExternalDNS supports the provider directly, configure its native provider:

external-dns:
  provider:
    name: <provider-name>

Otherwise, use a compatible provider webhook implementation:

external-dns:
  provider:
    name: webhook
    webhook:
      image:
        repository: <provider-webhook-image>
        tag: <compatible-version>

Webhook implementations are provider-specific. The regular registry.k8s.io/external-dns/external-dns image is the ExternalDNS controller, not a generic provider webhook. Your overlay may also need credentials, environment variables, Secret references, or volume mounts. See the ExternalDNS provider documentation for native providers and community webhook implementations.

Do not edit values.generated.yaml; it is regenerated by kubara generate.

Warning

kubara does not yet validate incomplete ExternalDNS provider settings during generation. For a provider that kubara does not configure, add the overlay before enabling ExternalDNS, or set services.external-dns.status to disabled if you do not need automatic DNS management yet. Then run kubara generate again.

Configuration in config.yaml

Example

clusters:
  - name: my-cluster
    stage: prod

    # Base domain / zone
    dnsName: example.com

    terraform:
      provider: stackit # currently supported: stackit
      dns:
        name: "example-zone"
        email: "hostmaster@example.com"

    services:
      external-dns:
        status: enabled        # <--- enable here

Explanation

  • dnsName → base domain for the cluster
  • terraform.dns → defines the zone for which kubara generates Terraform code (name and contact email).
  • services.external-dns.status → when set to enabled, ExternalDNS is templated into the Helm charts for deployment via Argo CD.
  • provider-specific settings → configure them in a values-*.yaml chart overlay.

DNS Credentials

  • DNS credentials are provider-specific and should be stored in your selected secret backend.
  • The External Secrets Operator can sync those credentials into the cluster.
  • The ExternalDNS Helm Chart consumes the synced secret for provider authentication.

Depending on your provider setup, credentials may be managed by Terraform, by your secret backend workflow, or manually.