External DNS 활용 예제

VPC 환경에서 이용 가능합니다.

Ncloud Kubernetes Service(NKS)에서 ExternalDNS를 사용하여 Kubernetes 리소스와 Global DNS 서비스의 레코드를 동기화할 수 있습니다.

사용 전 확인

ExternalDNS 활용 예제를 진행하기 전에 다음 지원 범위와 준비 사항을 확인해 주십시오.

ExternalDNS가 관리하는 레코드 유형과 조건은 다음과 같습니다.

다음 항목을 미리 준비해 주십시오.

• Ncloud Kubernetes Service 클러스터
• kubectl을 사용할 수 있는 kubeconfig
• Helm 3(수동 설치 시)
• Global DNS 서비스에 등록된 도메인
• 도메인 조회, 레코드 조회/생성/수정/삭제, 변경 사항 적용 권한

설치 과정에서 사용할 값은 다음과 같습니다.

가능하면 클러스터별로 별도의 Global DNS 도메인이나 위임한 하위 도메인을 사용해 주십시오. 여러 클러스터가 같은 도메인을 공유해야 한다면 클러스터마다 고유한 <TXT_OWNER_ID>를 사용하고 동일한 호스트 이름을 중복 관리하지 않도록 구성해 주십시오. NKS Add-on은 클러스터 UUID를 txtOwnerId 기본값으로 사용합니다.
다음 명령을 실행하여 kubeconfig context와 Ingress Class를 확인해 주십시오.

kubectl --context "<KUBE_CONTEXT>" cluster-info
kubectl --context "<KUBE_CONTEXT>" get ingressclass

Global DNS 도메인 준비

ExternalDNS에서 관리할 도메인을 Global DNS 서비스에 등록해 주십시오.

예를 들어 example.com을 관리 도메인으로 지정하면 app.example.com과 같은 하위 호스트의 레코드를 생성할 수 있습니다.
공개 DNS에서 레코드를 조회하려면 도메인 등록기관에 Global DNS의 네임 서버 정보를 설정해야 합니다.

인증 정보 준비

웹훅 프로바이더는 NKS Node IAM Role과 Sub Account 액세스 키를 지원합니다. 두 방식이 모두 설정된 경우 Sub Account 액세스 키를 먼저 사용합니다.

NKS Node IAM Role 사용

NKS Node IAM Role을 사용하면 장기 액세스 키를 Kubernetes Secret에 저장하지 않아도 됩니다. 다음 순서로 역할을 준비해 주십시오.

1. 역할 생성을 참고하여 Server 유형의 Sub Account 역할을 생성해 주십시오.
2. 역할에 Global DNS 도메인 및 레코드 관리 권한을 추가해 주십시오.
3. 노드 풀을 생성할 때 해당 역할을 Node IAM Role로 선택해 주십시오.
4. ExternalDNS 파드가 해당 노드 풀에 배치되도록 노드 레이블과 taint를 확인해 주십시오.

Global DNS의 모든 기능을 허용하려면 NCP_GLOBAL_DNS_MANAGER 관리형 정책을 사용할 수 있습니다. 최소 권한의 사용자 정의 정책을 사용하는 경우 다음 액션을 선택해 주십시오.

Sub Account는 위 액션에 필요한 getDomainDetail과 getRecordDetail을 연관 액션으로 자동 추가합니다. 자동으로 추가된 연관 액션을 선택 해제하지 마십시오. getDomainMonitor, downloadRecordList, createDomain, uploadZonefile, deleteDomain, changeDNSSECstatus는 필요하지 않습니다.

자세한 내용은 Global DNS 권한 관리를 참고해 주십시오.

Sub Account 액세스 키 사용

Sub Account 액세스 키를 사용하는 경우 ExternalDNS 파드가 실행되는 네임스페이스에 인증 정보가 포함된 Secret을 생성해 주십시오.
NKS Add-on은 kube-system 네임스페이스에 설치됩니다. 기존 클러스터에 Add-on을 설치하는 경우 다음 명령을 실행하여 Secret을 먼저 생성해 주십시오.

kubectl --context "<KUBE_CONTEXT>" --namespace kube-system \
  create secret generic ncloud-credentials \
  --from-literal=access-key="<NCLOUD_ACCESS_KEY>" \
  --from-literal=secret-key="<NCLOUD_SECRET_KEY>"

Add-on 설정의 credentials.secretName에 ncloud-credentials를 입력해 주십시오.

클러스터 생성과 동시에 ExternalDNS Add-on을 설치하는 경우에는 credentials.secretName을 먼저 입력할 수 있습니다. 클러스터 생성이 완료된 후 kube-system 네임스페이스에 Secret을 생성하고 다음 명령을 실행하여 ExternalDNS Deployment를 다시 시작해 주십시오.

kubectl --context "<KUBE_CONTEXT>" --namespace kube-system \
  rollout restart deployment/external-dns
kubectl --context "<KUBE_CONTEXT>" --namespace kube-system \
  rollout status deployment/external-dns --timeout=5m

Sub Account 액세스 키를 사용하려면 Add-on 설정의 credentials.secretName에 Secret 이름을 입력해 주십시오. Node IAM Role을 사용하려면 값을 비워 주십시오. 같은 이름의 Secret에서 액세스 키를 변경한 경우에는 ExternalDNS Deployment를 다시 시작해야 변경된 값이 적용됩니다.

Helm으로 수동 설치하는 경우 다음 명령을 실행하여 external-dns 네임스페이스와 Secret을 생성해 주십시오.

kubectl --context "<KUBE_CONTEXT>" create namespace external-dns
kubectl --context "<KUBE_CONTEXT>" --namespace external-dns \
  create secret generic ncloud-credentials \
  --from-literal=access-key="<NCLOUD_ACCESS_KEY>" \
  --from-literal=secret-key="<NCLOUD_SECRET_KEY>"

ExternalDNS 설치

ExternalDNS는 NKS Add-on 또는 Helm으로 설치할 수 있습니다.

NKS Add-on을 이용한 설치

NKS Add-on 기능에서 ExternalDNS를 선택하고 설치해 주십시오. Add-on은 ExternalDNS 컨테이너, 네이버 클라우드 플랫폼용 웹훅 프로바이더, DNSEndpoint CRD, 지원 소스인 service, ingress, crd에 필요한 RBAC을 함께 설치합니다.

Add-on은 클러스터 UUID와 이용 환경에 따른 Global DNS OpenAPI 주소 등 일부 값을 자동으로 주입합니다. 사용자는 Add-on에서 제공하는 설정 항목만 입력하며, NKS가 Add-on의 구성과 버전을 자동으로 관리합니다. Add-on에서 제공하지 않는 값을 변경해야 하는 경우 Helm을 이용한 수동 설치를 진행해 주십시오.

주요 Add-on 설정은 다음과 같습니다.

Helm을 이용한 수동 설치

ExternalDNS Add-on을 사용할 수 없거나 사용자 정의 설정을 사용해야 하는 경우 ExternalDNS 공식 Helm 차트로 수동 설치할 수 있습니다. 수동 설치에서는 설치, 값 변경, 업그레이드, 제거를 사용자가 직접 관리합니다. ExternalDNS 컨테이너와 네이버 클라우드 플랫폼용 웹훅 프로바이더는 하나의 파드에 배포됩니다.

Node IAM Role을 사용하는 경우 다음 명령을 실행하여 네임스페이스를 생성해 주십시오.

kubectl --context "<KUBE_CONTEXT>" create namespace external-dns

다음 명령을 실행하여 ExternalDNS Helm 저장소를 추가해 주십시오.

helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
helm repo update

수동 설치에서는 이용 환경에 맞는 Global DNS OpenAPI 주소를 직접 설정해야 합니다.

다음 내용을 복사하여 external-dns-values.yaml 파일로 저장해 주십시오.
<DNS_ZONE>, <DNS_BASE_URL>, <TXT_OWNER_ID>, <WEBHOOK_IMAGE_TAG>는 준비한 값으로 변경해 주십시오.

image:
  tag: v0.21.0
sources:
  - service
  - ingress
  - crd
registry: txt
policy: sync
logLevel: info
txtPrefix: "_edns."
txtOwnerId: "<TXT_OWNER_ID>"
domainFilters:
  - "<DNS_ZONE>"
extraArgs:
  - --webhook-provider-read-timeout=90s
terminationGracePeriodSeconds: 120
provider:
  name: webhook
  webhook:
    image:
      repository: nks.kr.ncr.ntruss.com/nks/external-dns-navercloud-webhook
      tag: "<WEBHOOK_IMAGE_TAG>"
    env:
      - name: DOMAIN_FILTER
        value: "<DNS_ZONE>"
      - name: NCLOUD_DNS_BASE_URL
        value: "<DNS_BASE_URL>"
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 3
      periodSeconds: 5

수동 설치에서 MX 레코드와 Kubernetes 리소스에서 직접 정의한 TXT 레코드를 관리하려면 external-dns-values.yaml에 다음 값을 추가해 주십시오.

managedRecordTypes:
  - A
  - AAAA
  - CNAME
  - MX
  - TXT

txtPrefix는 CNAME 레코드와 소유권 TXT 레코드의 이름 충돌을 방지합니다. txtOwnerId는 여러 ExternalDNS 인스턴스가 같은 레코드를 변경하지 않도록 소유자를 구분합니다.
Sub Account 액세스 키를 사용하는 경우 provider.webhook.env를 다음과 같이 설정해 주십시오.

    env:
      - name: DOMAIN_FILTER
        value: "<DNS_ZONE>"
      - name: NCLOUD_DNS_BASE_URL
        value: "<DNS_BASE_URL>"
      - name: NCLOUD_ACCESS_KEY
        valueFrom:
          secretKeyRef:
            name: ncloud-credentials
            key: access-key
      - name: NCLOUD_SECRET_KEY
        valueFrom:
          secretKeyRef:
            name: ncloud-credentials
            key: secret-key

다음 명령을 실행하여 ExternalDNS를 설치해 주십시오.

helm upgrade --install external-dns external-dns/external-dns \
  --kube-context "<KUBE_CONTEXT>" \
  --namespace external-dns \
  --version 1.21.1 \
  --values external-dns-values.yaml

Helm 차트를 설치할 때 DNSEndpoint CRD도 함께 설치됩니다. --skip-crds 옵션을 사용하지 마십시오.
다음 명령을 실행하여 ExternalDNS와 CRD 상태를 확인해 주십시오.

kubectl --context "<KUBE_CONTEXT>" --namespace external-dns \
  rollout status deployment/external-dns --timeout=5m
kubectl --context "<KUBE_CONTEXT>" --namespace external-dns get pod
kubectl --context "<KUBE_CONTEXT>" get crd dnsendpoints.externaldns.k8s.io

다음 명령을 실행하여 ExternalDNS 컨테이너와 웹훅 컨테이너의 로그를 확인해 주십시오.

kubectl --context "<KUBE_CONTEXT>" --namespace external-dns \
  logs deployment/external-dns --all-containers=true --tail=100

웹훅 프로바이더가 사용 중인 인증 방식은 로그에서 다음 값으로 확인할 수 있습니다.

• provider=ServerRoleProvider: NKS Node IAM Role 사용
• provider=EnvProvider: Sub Account 액세스 키 사용

Service DNS 레코드 생성

LoadBalancer 유형의 Service에 ExternalDNS 어노테이션을 추가하면 Service의 외부 주소를 가리키는 DNS 레코드를 생성할 수 있습니다.
예제 리소스는 external-dns 네임스페이스에 생성합니다. 해당 네임스페이스가 없는 경우 다음 명령을 실행하여 생성해 주십시오.

kubectl --context "<KUBE_CONTEXT>" create namespace external-dns

다음 내용을 복사하여 external-dns-service.yaml 파일로 저장해 주십시오. <SERVICE_HOSTNAME>은 <DNS_ZONE>의 하위 호스트 이름으로 변경해 주십시오.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: external-dns-nginx
  namespace: external-dns
spec:
  replicas: 1
  selector:
    matchLabels:
      app: external-dns-nginx
  template:
    metadata:
      labels:
        app: external-dns-nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: external-dns-nginx
  namespace: external-dns
  annotations:
    external-dns.alpha.kubernetes.io/hostname: "<SERVICE_HOSTNAME>"
    external-dns.alpha.kubernetes.io/ttl: "300"
spec:
  type: LoadBalancer
  selector:
    app: external-dns-nginx
  ports:
    - port: 80
      targetPort: 80

다음 명령을 실행하여 Deployment와 Service를 생성하고 외부 주소 할당 상태를 확인해 주십시오.

kubectl --context "<KUBE_CONTEXT>" apply -f external-dns-service.yaml
kubectl --context "<KUBE_CONTEXT>" --namespace external-dns \
  get service external-dns-nginx

다음 동기화가 완료되면 Global DNS 메뉴에서 <SERVICE_HOSTNAME>의 레코드와 소유권 TXT 레코드가 생성되었는지 확인해 주십시오. ExternalDNS는 기본적으로 1분마다 동기화합니다. Load Balancer 생성에는 수 분 이상 걸릴 수 있습니다.

Ingress DNS 레코드 생성

Ingress Controller가 Ingress에 할당한 외부 주소와 Ingress에 지정한 호스트 이름을 이용해 DNS 레코드를 생성할 수 있습니다. Ingress Controller 설치 및 Ingress 생성 방법은 ALB Ingress Controller 활용 예제를 참고해 주십시오.

다음 내용을 복사하여 external-dns-ingress.yaml 파일로 저장해 주십시오. <INGRESS_HOSTNAME>은 <DNS_ZONE>의 하위 호스트 이름으로 변경해 주십시오.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: external-dns-ingress
  namespace: external-dns
  annotations:
    external-dns.alpha.kubernetes.io/ttl: "300"
spec:
  ingressClassName: "<INGRESS_CLASS>"
  rules:
    - host: "<INGRESS_HOSTNAME>"
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: external-dns-nginx
                port:
                  number: 80

다음 명령을 실행하여 Ingress를 생성하고 외부 주소 할당 상태를 확인해 주십시오.

kubectl --context "<KUBE_CONTEXT>" apply -f external-dns-ingress.yaml
kubectl --context "<KUBE_CONTEXT>" --namespace external-dns \
  get ingress external-dns-ingress

다음 동기화가 완료되면 Global DNS 메뉴에서 <INGRESS_HOSTNAME>의 레코드와 소유권 TXT 레코드가 생성되었는지 확인해 주십시오.
Ingress Controller가 IP 주소를 제공하면 A 또는 AAAA 레코드가 생성됩니다. 호스트 이름을 제공하면 CNAME 레코드가 생성됩니다.

DNSEndpoint로 DNS 레코드 생성

DNSEndpoint를 사용하면 Service나 Ingress와 관계없이 DNS 레코드를 직접 정의할 수 있습니다.
다음 내용을 복사하여 external-dns-crd.yaml 파일로 저장해 주십시오.

<CRD_HOSTNAME>과 <IP_ADDRESS>는 사용할 호스트 이름과 IP 주소로 변경해 주십시오.

apiVersion: externaldns.k8s.io/v1alpha1
kind: DNSEndpoint
metadata:
  name: external-dns-crd
  namespace: external-dns
spec:
  endpoints:
    - dnsName: "<CRD_HOSTNAME>"
      recordTTL: 300
      recordType: A
      targets:
        - "<IP_ADDRESS>"

다음 명령을 실행하여 DNSEndpoint를 생성하고 생성 여부를 확인해 주십시오.

kubectl --context "<KUBE_CONTEXT>" apply -f external-dns-crd.yaml
kubectl --context "<KUBE_CONTEXT>" --namespace external-dns \
  get dnsendpoint external-dns-crd

다음 동기화가 완료되면 Global DNS 메뉴에서 <CRD_HOSTNAME>의 A 레코드와 소유권 TXT 레코드가 생성되었는지 확인해 주십시오.

DNS 레코드 삭제

이 예제는 policy: sync를 사용하므로 Kubernetes 리소스를 삭제하면 ExternalDNS가 관리 대상 DNS 레코드와 소유권 TXT 레코드를 삭제합니다.
다음 명령을 실행하여 예제 리소스를 삭제해 주십시오.

kubectl --context "<KUBE_CONTEXT>" delete -f external-dns-crd.yaml
kubectl --context "<KUBE_CONTEXT>" delete -f external-dns-ingress.yaml
kubectl --context "<KUBE_CONTEXT>" delete -f external-dns-service.yaml

다음 동기화가 완료되면 Global DNS 메뉴에서 DNS 레코드와 소유권 TXT 레코드가 삭제되었는지 확인해 주십시오.
ExternalDNS를 더 이상 사용하지 않는 경우 설치 방식에 따라 제거해 주십시오.

• NKS Add-on: NKS의 Add-on 관리 화면에서 ExternalDNS Add-on 제거
• Helm 수동 설치: 다음 명령을 실행하여 Helm 릴리스 제거

helm uninstall external-dns \
  --kube-context "<KUBE_CONTEXT>" \
  --namespace external-dns

Helm 릴리스를 제거해도 DNSEndpoint CRD는 삭제되지 않습니다. CRD가 더 이상 필요하지 않은 경우 사용 중인 DNSEndpoint가 없는지 확인한 후 별도로 삭제해 주십시오.
Helm 수동 설치에서 Sub Account 액세스 키를 사용한 경우 해당 Secret을 다른 워크로드에서 사용하지 않는지 확인한 후 다음 명령을 실행하여 삭제해 주십시오.

kubectl --context "<KUBE_CONTEXT>" --namespace external-dns \
  delete secret ncloud-credentials

Add-on에서 Sub Account 액세스 키를 사용한 경우 해당 Secret을 다른 워크로드에서 사용하지 않는지 확인한 후 삭제해 주십시오.

제약 사항

ExternalDNS와 네이버 클라우드 플랫폼용 웹훅 프로바이더를 사용할 때 다음 제약 사항을 확인해 주십시오.

• Global DNS 서비스에 등록되지 않은 도메인의 호스트 이름은 건너뜁니다.
• Add-on에서 domainFilter를 설정하거나 Helm 수동 설치에서 domainFilters와 DOMAIN_FILTER를 설정하면 지정한 도메인만 관리합니다.
• Global DNS에서 네임 서버에 반영하지 않은 변경 사항이 남아 있으면 ExternalDNS는 해당 도메인의 레코드를 변경하지 않습니다. [설정 적용] > [배포] 버튼을 차례로 선택해 변경 사항을 반영하거나 [변경 사항 취소] 버튼을 선택해 되돌리면 다음 동기화부터 다시 처리됩니다.
• 웹훅 프로바이더가 실행 중일 때 Global DNS 콘솔에서 같은 도메인의 레코드를 직접 변경하지 마십시오.
• SOA와 NS 기본 레코드는 관리하지 않습니다.