### Initialize documentation development environment

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/contributing/dev-guide

Commands to enter a virtual environment, install documentation dependencies, and start the local MkDocs server.

```bash
❯❯ pipenv shell
❯❯ pip install -r docs/scripts/requirements.txt
❯❯ mkdocs serve
$$ ...
$$ Serving on http://127.0.0.1:8000/
```

--------------------------------

### EKS configuration example

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/aws

An effective starting point for EKS with an ingress controller, using a 5-minute interval, events, ingress source, domain filter, and zone cache duration.

```text
--interval=5m
--events
--source=ingress
--domain-filter=example.com
--aws-zones-cache-duration=1h
```

--------------------------------

### Example startup flags output

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/contributing/bug-report

An example of the expected format for startup flags.

```text
--provider=aws
--registry=txt
--txt-owner-id=my-cluster
--source=ingress
--domain-filter=example.com
--log-level=debug
```

--------------------------------

### Example nameserver output

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/aws

Example output from the previous command showing the nameservers assigned to the new hosted zone.

```text
ns-695.awsdns-22.net.
ns-1313.awsdns-36.org.
ns-350.awsdns-43.com.
ns-1805.awsdns-33.co.uk.
```

--------------------------------

### BIND zone file example

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/rfc2136

Example content for a BIND zone file.

```text
$TTL 60 ; 1 minute
k8s.example.org         IN SOA  k8s.example.org. root.k8s.example.org. (
                                16         ; serial
                                60         ; refresh (1 minute)
                                60         ; retry (1 minute)
                                60         ; expire (1 minute)
                                60         ; minimum (1 minute)
                                )
                        NS      ns.k8s.example.org.
ns                      A       123.456.789.012
```

--------------------------------

### Delete tutorial example resources

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/ovh

Deletes the example resources created during the tutorial, including the nginx deployment and the ExternalDNS configuration.

```bash
kubectl delete -f nginx.yaml
kubectl delete -f externaldns.yaml

```

--------------------------------

### Install Sample Service

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/contour

Command to apply a sample Deployment and Service to the cluster.

```bash
$ kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: kuard
  name: kuard
spec:
  replicas: 3
  selector:
    matchLabels:
      app: kuard
  template:
    metadata:
      labels:
        app: kuard
    spec:
      containers:
      - image: gcr.io/kuar-demo/kuard-amd64:1
        name: kuard
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app: kuard
  name: kuard
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 8080
  selector:
    app: kuard
  sessionAffinity: None
  type: ClusterIP
EOF
```

--------------------------------

### Install Helm tools

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/contributing/dev-guide

Installs the required plugins for Helm chart management.

```bash
❯❯ scripts/helm-tools.sh --install
```

--------------------------------

### Order informer configuration before factory.Start

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/contributing/sources-and-providers

Configure the informer in this order before starting the factory. Must* helpers panic after factory.Start(), so call them before starting.

```go
informers.MustSetTransform(myInformer.Informer(), ...)       // 1. how objects are stored
informers.MustAddIndexers(myInformer.Informer(), ...)        // 2. how objects are looked up
informers.MustAddEventHandler(myInformer.Informer(), ...)    // 3. who is notified
factory.Start(ctx.Done())                                    // 4. start — Must* helpers panic after this
```

--------------------------------

### Example Services for Selector-Based Filtering

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/advanced/fqdn-templating

Two example Service manifests: one with an 'app' selector that will generate an FQDN, and one without that will not.

```yaml
apiVersion: v1
kind: Service
metadata:
  name: web-frontend
spec:
  selector:
    app: nginx        # This selector will be used in the FQDN
    tier: frontend
  ports:
    - port: 80
---
apiVersion: v1
kind: Service
metadata:
  name: database
spec:
  selector:
    tier: backend     # Won't generate FQDN - no "app" key in selector
  ports:
    - port: 5432

```

--------------------------------

### Delete tutorial example services

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/gandi

Deletes the example services created during the tutorial to clean up resources after verifying ExternalDNS manages Gandi DNS records.

```bash
kubectl delete service -f nginx.yaml
kubectl delete service -f externaldns.yaml

```

--------------------------------

### List Go tools

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/contributing/dev-guide

Lists all Go-based tools installed for the project.

```bash
make go-tools
```

--------------------------------

### Example service output

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/aws

Expected output showing the load balancer details.

```text
NAME    TYPE           CLUSTER-IP     EXTERNAL-IP                                                                   PORT(S)        AGE
nginx   LoadBalancer   10.100.47.41   ae11c2360188411e7951602725593fd1-1224345803.eu-central-1.elb.amazonaws.com.   80:32749/TCP   12m
```

--------------------------------

### Install Sample Service and Route

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/openshift

Command to apply a Deployment, Service, and Route to verify ExternalDNS functionality.

```bash
$ oc apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: hello-openshift
  name: hello-openshift
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello-openshift
  template:
    metadata:
      labels:
        app: hello-openshift
    spec:
      containers:
      - image: openshift/hello-openshift
        name: hello-openshift
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app: hello-openshift
  name: hello-openshift
spec:
  ports:
  - port: 8080
    protocol: TCP
    targetPort: 8080
  selector:
    app: hello-openshift
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: hello-openshift
spec:
  host: hello-openshift.example.com
  to:
    kind: Service
    name: hello-openshift
    weight: 100
  wildcardPolicy: None
EOF
```

--------------------------------

### Install NGINX Ingress Controller with Helm

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/azure-private-dns

Use Helm to add the ingress-nginx repository and install the controller with the publishService enabled.

```bash
$ helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
$ helm repo update
$ helm install [RELEASE_NAME] ingress-nginx/ingress-nginx
     --set controller.publishService.enabled=true
```

--------------------------------

### DNSEndpoint manifest for A record

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/crd

Example configuration for an A record.

```yaml
apiVersion: externaldns.k8s.io/v1alpha1
kind: DNSEndpoint
metadata:
  name: examplearecord
spec:
  endpoints:
  - dnsName: example.com
    recordTTL: 60
    recordType: A
    targets:
    - 10.0.0.1
```

--------------------------------

### Install external-dns

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/coredns-etcd

Deploy external-dns using Helm with the provided configuration file.

```bash
helm upgrade --install external-dns external-dns/external-dns \
  -f docs/snippets/tutorials/coredns/values-extdns-coredns.yaml \
  -n default

❯❯ Release "external-dns" does not exist. Installing it now.
```

--------------------------------

### Launch debug pod

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/coredns-etcd

Starts a temporary pod using the infoblox/dnstools image for testing.

```bash
kubectl run --rm -it dnsutils --image=infoblox/dnstools --restart=Never
```

--------------------------------

### Gateway annotation example with kubectl apply

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/gloo-proxy

Applies a Proxy, Gateway, and Ingress to support setups where an Ingress resource provisions an external LB. The Gateway annotation external-dns.kubernetes.io/ingress uses $ingressNamespace/$ingressName; the Ingress namespace can be omitted if it is in the same namespace as the gateway.

```bash
$ cat <<EOF | kubectl apply -f -
apiVersion: gloo.solo.io/v1
kind: Proxy
metadata:
  labels:
    created_by: gloo-gateway
  name: gateway-proxy
  namespace: gloo-system
spec:
  listeners:
  - bindAddress: '::'
    metadataStatic:
      sources:
      - resourceKind: '*v1.Gateway'
        resourceRef:
          name: gateway-proxy
          namespace: gloo-system
---
apiVersion: gateway.solo.io/v1
kind: Gateway
metadata:
  annotations:
    external-dns.kubernetes.io/ingress: "$ingressNamespace/$ingressName"
  labels:
    app: gloo
  name: gateway-proxy
  namespace: gloo-system
spec: {}
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  labels:
    gateway-proxy-id: gateway-proxy
    gloo: gateway-proxy
  name: gateway-proxy
  namespace: gloo-system
spec:
  ingressClassName: alb
EOF

```

--------------------------------

### Verify DNSEndpoint CRD Installation

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/aws-localstack

Checks if the dnsendpoints.externaldns.k8s.io CRD is installed in the cluster.

```bash
kubectl get crd dnsendpoints.externaldns.k8s.io
```

--------------------------------

### Build documentation locally

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/contributing/docs

Commands to set up a virtual environment and serve or build the documentation using mkdocs. Requires python3, pip, and virtualenv.

```bash
# Pre-requisite: python3, pip and virtualenv
DOCS="/tmp/extdns-docs"
mkdir "$DOCS"
virtualenv "$DOCS"
source "$DOCS/bin/activate"
pip install -r docs/scripts/requirements.txt
mkdocs serve # or mkdocs build
```

--------------------------------

### Install sample service with automatic sidecar injection

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/istio

Deploys the httpbin sample service using automatic sidecar injection.

```bash
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.25/samples/httpbin/httpbin.yaml
```

--------------------------------

### Example debug log entries

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/contributing/bug-report

Examples of log lines to look for when debugging reconciliation issues.

```text
level=debug msg="Desired change: CREATE example.com A [1.2.3.4]"
level=debug msg="No endpoints could be generated from ingress ..."
level=info  msg="All records are already up to date"
```

--------------------------------

### Install external-dns chart with Helm

Source: https://kubernetes-sigs.github.io/external-dns/latest/charts/external-dns

Installs or upgrades the external-dns chart using Helm with version 1.21.1.

```bash
helm upgrade --install external-dns external-dns/external-dns --version 1.21.1

```

--------------------------------

### Deployment and Service for echo server

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/pdns

Spin up a simple 'Hello World' HTTP server using hashicorp/http-echo. The Service uses the annotation external-dns.kubernetes.io/hostname: echo.example.com. Remember to change example.com to your own domain.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
spec:
  selector:
    matchLabels:
      app: echo
  template:
    metadata:
      labels:
        app: echo
    spec:
      containers:
      - image: hashicorp/http-echo
        name: echo
        ports:
        - containerPort: 5678
        args:
          - -text="Hello World"
---
apiVersion: v1
kind: Service
metadata:
  name: echo
  annotations:
    external-dns.kubernetes.io/hostname: echo.example.com
spec:
  selector:
    app: echo
  type: LoadBalancer
  ports:
    - protocol: TCP
      port: 80
      targetPort: 5678

```

--------------------------------

### DNSEndpoint resource example

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/crd

Example YAML configuration for a DNSEndpoint resource that includes the required annotation for the filter.

```yaml
apiVersion: externaldns.k8s.io/v1alpha1
kind: DNSEndpoint
metadata:
  name: examplednsrecord
  annotations:
    external-dns: public
spec:
  endpoints:
  - dnsName: foo.bar.com
    recordTTL: 180
    recordType: A
    targets:
    - 192.168.99.216
```

--------------------------------

### Install Emissary-ingress 3.10

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/ambassador

Installs Emissary-ingress 3.10.0 by applying CRDs and the Emissary namespace, then waits for the deployments to be ready.

```bash
kubectl apply -f https://app.getambassador.io/yaml/emissary/3.10.0/emissary-crds.yaml
kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system

kubectl create namespace emissary
kubectl apply -f https://app.getambassador.io/yaml/emissary/3.10.0/emissary-emissaryns.yaml
kubectl -n emissary rollout status deployment/emissary-ingress

```

--------------------------------

### Install sample service without automatic sidecar injection

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/istio

Deploys the httpbin sample service using istioctl to manually inject the sidecar.

```bash
kubectl apply -f <(istioctl kube-inject -f https://raw.githubusercontent.com/istio/istio/release-1.25/samples/httpbin/httpbin.yaml)
```

--------------------------------

### Delete Traefik example resources

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/traefik-proxy

Use these commands to remove the tutorial's example IngressRoute and ExternalDNS configuration.

```bash
kubectl delete -f docs/snippets/traefik-proxy/ingress-route-default.yaml
kubectl delete -f externaldns.yaml
```

--------------------------------

### Create Azure DNS zone for example.com

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/azure

Creates an Azure DNS zone for 'example.com' in the specified resource group. Substitute a domain you own for 'example.com' if desired. The 'nameServers' field from the JSON output should be used to point your domain's name servers if registered with a third-party registrar.

```bash
az network dns zone create --resource-group "MyDnsResourceGroup" --name "example.com"
```

--------------------------------

### Create Azure Private DNS zone for example.com

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/azure-private-dns

Creates the private DNS zone. Substitute 'example.com' with your own domain if desired.

```bash
az network private-dns zone create -g externaldns -n example.com

```

--------------------------------

### Deploy foo-app

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/aws-localstack

Applies the foo-app configuration to the cluster.

```bash
kubectl apply -f docs/snippets/tutorials/aws-localstack/foo-app.yml
```

--------------------------------

### Start PowerDNS authoritative server with Docker

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/pdns

Starts a PowerDNS container with the HTTP API enabled and zone caching disabled for immediate updates.

```bash
docker run -d --name pdns -p 1053:53 -p 1053:53/udp -p 8081:8081 \
  powerdns/pdns-auth-49 \
  --api=yes --api-key=secret --webserver=yes \
  --webserver-address=0.0.0.0 --webserver-allow-from=0.0.0.0/0 \
  --zone-cache-refresh-interval=0
```

--------------------------------

### Key-based Authentication: Create oci.yaml Config File

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/oracle

Create a new file (oci.yaml) and modify the contents to match the example. Adjust the values to match your own credentials and the OCID of the compartment containing the zone.

```yaml
auth:
  region: us-phoenix-1
  tenancy: ocid1.tenancy.oc1...
  user: ocid1.user.oc1...
  key: |
    -----BEGIN RSA PRIVATE KEY-----
    -----END RSA PRIVATE KEY-----
  fingerprint: af:81:71:8e...
  # Omit if there is not a password for the key
  passphrase: Tx1jRk...
compartment: ocid1.compartment.oc1...

```

--------------------------------

### GatewayDNSConfig and RouteDNSConfig CRD Example

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/proposal/004-gateway-api-annotation-placement

Example of defining DNS configuration using dedicated CRDs to separate concerns and provide a clear precedence model.

```yaml
apiVersion: externaldns.k8s.io/v1alpha1
kind: GatewayDNSConfig
metadata:
  name: cloudflare-defaults
spec:
  gatewayRef:
    name: my-gateway
  defaults:
    ttl: 300
    providerSpecific:
      - name: cloudflare-proxied
        value: "true"
---
apiVersion: externaldns.k8s.io/v1alpha1
kind: RouteDNSConfig
metadata:
  name: api-route-dns
spec:
  routeRef:
    kind: HTTPRoute
    name: api-route
  overrides:
    ttl: 60  # Override Gateway default
```

--------------------------------

### Install ExternalDNS with Helm

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/cloudflare

Adds the ExternalDNS Helm repository, updates it, and installs or upgrades the ExternalDNS chart using the values.yaml file. Run these commands in sequence.

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

```

```bash
helm repo update

```

```bash
helm upgrade --install external-dns external-dns/external-dns --values values.yaml

```

--------------------------------

### Create the deployment and service with kubectl

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/gandi

Runs kubectl create -f nginx.yaml to create the deployment and service defined in the previous snippet. After the service gets an external IP, ExternalDNS will synchronize the Gandi DNS records.

```bash
kubectl create -f nginx.yaml

```

--------------------------------

### Install ExternalDNS with RFC2136 configuration via Helm

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/rfc2136

Installs or upgrades the external-dns chart with the RFC2136 provider values file. The output indicates a new release is being created.

```bash
helm upgrade --install external-dns external-dns/external-dns \
  -f docs/snippets/tutorials/rfc2136/values-extdns-rfc2136.yaml \
  -n default
```

```bash
❯❯ Release "external-dns" does not exist. Installing it now.
```

--------------------------------

### Example metrics output for external_dns_registry_endpoints_total

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/monitoring

Example output from the /metrics endpoint showing help, type, and current value of the external_dns_registry_endpoints_total counter. This snippet demonstrates the Prometheus exposition format.

```text
# HELP external_dns_registry_endpoints_total Number of Endpoints in the registry
# TYPE external_dns_registry_endpoints_total gauge
external_dns_registry_endpoints_total 11

```

--------------------------------

### Customize domain with --fqdn-template

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/fake

Use --fqdn-template to replace the default example.com domain with a custom domain or template expression.

```bash
# plain domain
external-dns --source=fake --provider=webhook --webhook-provider-url=http://localhost:8888 \
  --fqdn-template=my-company.com

# template expression
external-dns --source=fake --provider=webhook --webhook-provider-url=http://localhost:8888 \
  --fqdn-template={{.Name}}.my-company.com
```

--------------------------------

### Test a PR on Linux or WSL

Source: https://kubernetes-sigs.github.io/external-dns/latest/CONTRIBUTING

Instructions for cloning the repository, checking out a specific pull request, and running the application locally using the Go toolchain.

```bash
gh repo clone kubernetes-sigs/external-dns
cd external-dns
gh pr checkout XXX # <=== Set PR number here
go run main.go \
  --kubeconfig=<kubeconfig_path> \
  --log-format=text \
  --log-level=debug \
  --interval=1m
  --provider=xxx
  --source=yyy
```

--------------------------------

### Configure GKE and DNS Projects

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/gke

Set environment variables and enable necessary APIs for both the GKE workload project and the Cloud DNS project.

```bash
# set variables to appropriate desired values
GKE_PROJECT_ID="my-workload-project"
DNS_PROJECT_ID="my-cloud-dns-project"
ClOUD_BILLING_ACCOUNT="<my-cloud-billing-account>"
# enable billing and APIs for DNS project if not done already
gcloud config set project $DNS_PROJECT_ID
gcloud beta billing projects link $CLOUD_DNS_PROJECT \
  --billing-account $ClOUD_BILLING_ACCOUNT
gcloud services enable "dns.googleapis.com"
# enable billing and APIs for GKE project if not done already
gcloud config set project $GKE_PROJECT_ID
gcloud beta billing projects link $CLOUD_DNS_PROJECT \
  --billing-account $ClOUD_BILLING_ACCOUNT
gcloud services enable "container.googleapis.com"
```

--------------------------------

### Combine annotation key and value filters

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/advanced/fqdn-templating

This example shows a Service with annotations and a template that filters by both key containing 'dns/' and value containing 'example.com'. The result is a comma-separated list of matching values.

```yaml
apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    dns/primary: api.example.com
    dns/secondary: api-backup.example.com
    other/hostname: internal.other.org  # Won't match - value doesn't contain "example.com"
    logging/level: debug                # Won't match - key doesn't contain "dns/"

```

```yaml
args:
  --fqdn-template='{{ if eq .Kind "Service" }}{{ range $k, $v := .Annotations }}{{ if and (contains $k "dns/") (contains $v "example.com") }}{{ $v }}{{ printf "," }}{{ end }}{{ end }}{{ end }}'

# Result: api.example.com, api-backup.example.com

```

--------------------------------

### DNSEndpoint manifest for DNAME record

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/crd

Example configuration for a DNAME record.

```yaml
apiVersion: externaldns.k8s.io/v1alpha1
kind: DNSEndpoint
metadata:
  name: dname-record
spec:
  endpoints:
  - dnsName: sub.example.com
    recordTTL: 300
    recordType: DNAME
    targets:
    - example.net
```

--------------------------------

### Create and configure Minikube cluster

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/contributing/dev-guide

Initialize a local Minikube cluster with specific resource constraints and Kubernetes version, then set the active profile.

```bash
minikube start \
  --profile=external-dns \
  --memory=2000 \
  --cpus=2 \
  --disk-size=5g \
  --kubernetes-version=v1.31 \
  --driver=docker

minikube profile external-dns

```

--------------------------------

### DNSEndpoint manifest for NS record

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/crd

Example configuration for an NS record.

```yaml
apiVersion: externaldns.k8s.io/v1alpha1
kind: DNSEndpoint
metadata:
  name: ns-record
spec:
  endpoints:
  - dnsName: zone.example.com
    recordTTL: 300
    recordType: NS
    targets:
    - ns1.example.com
    - ns2.example.com
```

--------------------------------

### DNSEndpoint manifest for CNAME record

Source: https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/crd

Example configuration for a CNAME record.

```yaml
apiVersion: externaldns.k8s.io/v1alpha1
kind: DNSEndpoint
metadata:
  name: examplecnamerecord
spec:
  endpoints:
  - dnsName: test-a.example.com
    recordTTL: 300
    recordType: CNAME
    targets:
    - example.com
```