External DNS Controller

The External DNS Controller is a Kubernetes add-on that automatically manages DNS records for services in a Kubernetes cluster. It ensures that services are discoverable via DNS, making it easier to access applications running within the cluster from outside.

The External DNS Controller simplifies the process of exposing applications running in Kubernetes to the outside world by managing DNS records automatically. It automatically creates DNS records for Kubernetes services and ingresses and keeps them up-to-date as services and ingresses are created, updated, or deleted. This enables users to easily manage and keep track of DNS records without worrying about manually updating them.

OBLV Deploy

The External DNS Controller is a prerequisite to use OBLV Deploy. For additional information, refer to the Prerequisites page.

Configuration

To configure the External DNS Controller, you need to grant the necessary permissions to enable it to manage DNS records in AWS Route 53. The process involves creating an IAM Policy file and an IAM Service Account. Follow the detailed instructions below for creating the IAM Policy file, IAM Policy, and Service Account:

IAM Policy File Creation

Unlike other controllers, the IAM Policy file for the External DNS Controller cannot be downloaded and must be created manually. Create a file named external_dns_iam_policy.json with the following content. Replace ${HOSTED_ZONE_ID} with your actual Route 53 hosted zone ID:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "route53:ChangeResourceRecordSets",
        "route53:ListResourceRecordSets",
        "route53:ListTagsForResources"
      ],
      "Resource": [
        "arn:aws:route53:::hostedzone/${HOSTED_ZONE_ID}"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "route53:ListHostedZones"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}

This policy grants the External DNS Controller the following permissions:

Modify DNS Records in Specific Hosted Zone: The policy allows the controller to change resource record sets, list existing records, and retrieve tag information for resources within a specific hosted zone (identified by ${HOSTED_ZONE_ID}) in AWS Route 53. This is crucial for dynamically updating DNS records as services and ingresses are created, updated, or deleted within the Kubernetes cluster.
List All Hosted Zones: The policy allows the controller to list all hosted zones in the AWS account. This is necessary for the controller to discover existing hosted zones and determine where to manage DNS records.

IAM Policy Creation

Create an IAM policy in AWS using the policy document you created in the previous step. This policy grants the External DNS Controller the necessary permissions to manage Route 53 DNS records on your behalf.

aws iam create-policy \
  --policy-name "ExternalDNSUpdatesPolicy" \
  --policy-document file://external_dns_iam_policy.json

The command parameters are described in the table below:

Parameter	Description
`aws iam create-policy`	The AWS CLI command to create a new IAM policy. IAM (Identity and Access Management) is a service that helps you securely control access to AWS resources.
`--policy-name ExternalDNSUpdatesPolicy`	The name of the IAM policy. Choose a descriptive name that clearly indicates the purpose—in this case, granting permissions for the External DNS Controller.
`--policy-document file://external_dns_iam_policy.json`	Points to the policy document file. The `file://` prefix indicates a local filesystem path. This references the `external_dns_iam_policy.json` file you created in the previous step.

Service Account Creation

Create an IAM service account for the External DNS Controller with the necessary permissions using the eksctl command-line tool. This service account will be associated with the IAM policy created in the previous step.

eksctl create iamserviceaccount \
  --name external-dns \
  --namespace kube-system \
  --cluster ${CLUSTER_NAME} \
  --attach-policy-arn=arn:aws:iam::${AWS_CURRENT_ACCOUNT}:policy/ExternalDNSUpdatesPolicy \
  --approve \
  --override-existing-serviceaccounts \
  --region ${CLUSTER_REGION}

The command parameters are described in the table below:

Parameter	Description
`--cluster=${CLUSTER_NAME}`	Specifies the name of the EKS cluster where the service account will be created. Replace `${CLUSTER_NAME}` with your actual cluster name.
`--namespace=kube-system`	Specifies the Kubernetes namespace for the service account. The `kube-system` namespace is typically used for cluster-level system components.
`--name=external-dns`	The name of the service account used to identify it within the Kubernetes cluster.
`--attach-policy-arn`	Attaches the specified IAM policy ARN to the service account role. Replace `${AWS_CURRENT_ACCOUNT}` with your AWS account ID.
`--approve`	Automatically approves the creation of the service account and associated IAM role without manual confirmation.
`--override-existing-serviceaccounts`	Updates existing service accounts with the same name instead of creating a new one. This option applies new IAM role and policy attachments to the existing service account.
`--region ${CLUSTER_REGION}`	Specifies the AWS region where the EKS cluster is located. Replace `${CLUSTER_REGION}` with your cluster's region. This ensures resources are created in the correct region.

Important Considerations:

Security: Ensure the ExternalDNSUpdatesPolicy IAM policy exists and grants only the necessary permissions for the External DNS Controller to manage Route 53 resources.
Namespace: The service account is created in the kube-system namespace, which is standard for cluster-level controllers. You may choose a different namespace based on your organization's policies.
Region: Always verify that the specified region matches your EKS cluster's region. Mismatched regions can cause errors or create resources in unintended locations.

What's Next?

For additional information about how OBLV Deploy uses the External DNS Controller, refer to the Prerequisites page.

Getting Started