DNS Providers

Introduction

Gardener can manage DNS records on your behalf, so that you can request them via different resource types (see here) within the shoot cluster. The domains for which you are permitted to request records, are however restricted and depend on the DNS provider configuration.

Shoot provider

By default, every shoot cluster is equipped with a default provider. It is the very same provider that manages the shoot cluster's kube-apiserver public DNS record (DNS address in your Kubeconfig).

kind: Shoot
...
dns:
  domain: shoot.project.default-domain.gardener.cloud

You are permitted to request any sub-domain of .dns.domain that is not already taken (e.g. api.shoot.project.default-domain.gardener.cloud, *.ingress.shoot.project.default-domain.gardener.cloud) with this provider.

Additional providers

If you need to request DNS records for domains not managed by the default provider, additional providers can be configured in the shoot specification. Alternatively, if it is enabled, it can be added as DNSProvider resources to the shoot cluster.

Additional providers in the shoot specification (preferred)

To add a provider in the shoot spec for the shoot-dns-service, you first need to take a look into the shoot manifest to check if it already has been migrated to the new separate configuration. If the flag .spec.extensions[@.type="shoot-dns-service"].providerConfig.syncProvidersFromShootSpecDNS is set to false, you need to set the providers in the providerConfig section of the extension. Additionally, the secret must be referenced in the spec.resources section. The referenced secret needs to exist in the project namespace.

For example:

kind: Shoot
...
spec:
  dns:
    domain: shoot.project.default-domain.gardener.cloud
    providers:
    # define primary provider here if needed (used for the shoot's kube-apiserver record)
  extensions:
    - type: shoot-dns-service
      providerConfig:
        apiVersion: service.dns.extensions.gardener.cloud/v1alpha1
        kind: DNSConfig
        providers:
          - secretName: my-aws-account
            type: aws-route53
          - secretName: my-gcp-account
            type: google-clouddns
        syncProvidersFromShootSpecDNS: false
  resources:
    - name: my-aws-account
      resourceRef:
        kind: Secret
        name: my-aws-credentials # secret with this name must exist in the project namespace
        apiVersion: v1
    - name: my-gcp-account
      resourceRef:
        kind: Secret
        name: my-gcp-credentials # secret with this name must exist in the project namespace
        apiVersion: v1

If syncProvidersFromShootSpecDNS is set to true, you need to set the providers in the spec.dns.providers section (see below)

Additional providers in the shoot specification (deprecated)

WARNING

This approach is deprecated. Please prefer keeping syncProvidersFromShootSpecDNS set to false Instead, configure additional DNS providers as part of the shoot-dns-service provider config as described above or configure them as resources in the shoot cluster as described below.

To add a provider in the shoot spec, you need set them in the spec.dns.providers list.

For example:

kind: Shoot
...
spec:
  dns:
    domain: shoot.project.default-domain.gardener.cloud
    providers:
    - secretName: my-aws-account
      type: aws-route53
    - secretName: my-gcp-account
      type: google-clouddns
  extensions:
    - type: shoot-dns-service
      providerConfig: # this section is synced from spec.dns.providers if syncProvidersFromShootSpecDNS is true
        apiVersion: service.dns.extensions.gardener.cloud/v1alpha1
        kind: DNSConfig
        providers:
        - secretName: my-aws-account
          type: aws-route53
        - secretName: my-gcp-account
          type: google-clouddns
        syncProvidersFromShootSpecDNS: true # if this flag is set to true, the providerConfig is automatically synced from spec.dns.providers

Please consult the API-Reference to get a complete list of supported fields and configuration options.

Referenced secrets should exist in the project namespace in the Garden cluster and must comply with the provider specific credentials format. The External-DNS-Management project provides corresponding examples (20-secret-<provider-name>-credentials.yaml) for known providers.

Additional providers as resources in the shoot cluster

If it is not enabled globally, you have to enable the feature in the shoot manifest:

Kind: Shoot
...
spec:
  extensions:
    - type: shoot-dns-service
      providerConfig:
        apiVersion: service.dns.extensions.gardener.cloud/v1alpha1
        kind: DNSConfig
        dnsProviderReplication:
          enabled: true
...

To add a provider directly in the shoot cluster, provide a DNSProvider in any namespace together with Secret containing the credentials.

For example if the domain is hosted with AWS Route 53 (provider type aws-route53):

apiVersion: dns.gardener.cloud/v1alpha1
kind: DNSProvider
metadata:
  annotations:
    dns.gardener.cloud/class: garden
  name: my-own-domain
  namespace: my-namespace
spec:
  type: aws-route53
  secretRef:
    name: my-own-domain-credentials
  domains:
    include:
    - my.own.domain.com
---
apiVersion: v1
kind: Secret
metadata:
  name: my-own-domain-credentials
  namespace: my-namespace
type: Opaque
data:
  # replace '...' with values encoded as base64
  AWS_ACCESS_KEY_ID: ...
  AWS_SECRET_ACCESS_KEY: ...

The External-DNS-Management project provides examples with more details for DNSProviders (30-provider-<provider-name>.yaml) and credential Secrets (20-secret-<provider-name>.yaml) at https://github.com/gardener/external-dns-management//examples for all supported provider types.