TrueCharts-Bot
121 lines
4.8 KiB
Markdown
121 lines
4.8 KiB
Markdown
---
|
|
title: External-DNS Setup Guide
|
|
---
|
|
|
|
ExternalDNS synchronizes exposed Kubernetes Services and Ingresses with DNS providers.
|
|
|
|
## What it does?
|
|
|
|
Inspired by Kubernetes DNS, Kubernetes' cluster-internal DNS server, ExternalDNS makes Kubernetes resources discoverable via public DNS servers. Like KubeDNS, it retrieves a list of resources (Services, Ingresses, etc.) from the Kubernetes API to determine a desired list of DNS records. Unlike KubeDNS, however, it's not a DNS server itself, but merely configures other DNS providers accordingly—e.g. AWS Route 53 or Google Cloud DNS.
|
|
|
|
### Prerequisites (required for Support on TrueCharts Discord)
|
|
|
|
- Traefik
|
|
- Clusterissuer / Cert-manager deployed
|
|
|
|
## Installation instructions
|
|
|
|
This guide will cover 2 scenarios, `Cloudflare` and `Pi-hole`. For more external DNS record providers, see [External-DNS Docs](https://github.com/kubernetes-sigs/external-dns/tree/master/docs/tutorials).
|
|
|
|
### Cloudflare
|
|
|
|
These instructions taken from [external-dns cloudflare tutorial](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/cloudflare.md)
|
|
|
|
#### Step 1
|
|
|
|
Set the env. `CF_API_TOKEN` (preferred) or `CF_API_EMAIL`/`CF_API_KEY`. <br>
|
|
When using API Token authentication, the token should be granted Zone Read, DNS Edit privileges, and access to All zones.
|
|
|
|
#### Step 2
|
|
|
|
- Enter preferences for Logs and DNS updates (Suggested >5m to prevent log spam)
|
|
- Set `cloudflare` as provider
|
|
- set sources `ingress` and `service` should covers everything.
|
|
- If you want to filter by multiple domains add your `domainFilters`
|
|
- Recommend using `noop` for `registry` and leaving the rest as default,
|
|
- You can add DNS Zone filters `zoneidFilters` as necessary as well
|
|
|
|
For more details of all option, see upstream docs of external-dns.
|
|
|
|
```yaml
|
|
externaldns:
|
|
logLevel: "info"
|
|
logFormat: "text"
|
|
interval: "60m"
|
|
provider: "cloudflare"
|
|
sources:
|
|
- "service"
|
|
- "ingress"
|
|
domainFilters:
|
|
- "${BASE_DOMAIN}"
|
|
zoneidFilters: []
|
|
cloudflareProxied: ""
|
|
registry: "noop"
|
|
policy: "upsert-only" # would prevent ExternalDNS from deleting any records, omit to enable full synchronization
|
|
```
|
|
|
|
#### Step 3
|
|
|
|
Verify it works, check the logs for updates to DNS records
|
|
|
|
```bash
|
|
time="2025-03-02T17:19:28+01:00" level=info msg="Instantiating new Kubernetes client"
|
|
time="2025-03-02T17:19:28+01:00" level=info msg="Using inCluster-config based on serviceaccount-token"
|
|
time="2025-03-02T17:19:28+01:00" level=info msg="Created Kubernetes client https://172.17.0.1:443"
|
|
time="2025-03-02T17:19:31+01:00" level=info msg="Changing record." action=CREATE record=chart1.domain.tld ttl=1 type=A zone=f8d01e5d4a8927a99d2e2655edcc40fc
|
|
time="2025-03-02T17:19:32+01:00" level=info msg="Changing record." action=CREATE record=chart2.domain.tld ttl=1 type=A zone=f8d01e5d4a8927a99d2e2655edcc40fc
|
|
time="2025-03-02T17:19:33+01:00" level=info msg="Changing record." action=CREATE record=chart3.domain.tld ttl=1 type=A zone=f8d01e5d4a8927a99d2e2655edcc40fc
|
|
```
|
|
|
|
If this works, you'll see DNS entries inside Cloudflare's DNS page.
|
|
|
|
### PiHole
|
|
|
|
:::danger[Temporally broken]
|
|
|
|
Because of API changes in Pi-hole v6 this is temporally broken.
|
|
More info: https://github.com/kubernetes-sigs/external-dns/issues/5113
|
|
|
|
:::
|
|
|
|
#### Step 1
|
|
|
|
- Set `pihole` as provider
|
|
- set sources `ingress` and `service` should covers everything
|
|
- Recommend using `noop` for `registry`
|
|
- Set PiHole Server Address `piholeServer` and PiHole Server Password `piholePassword`
|
|
|
|
```yaml
|
|
externaldns:
|
|
logLevel: "info"
|
|
logFormat: "text"
|
|
interval: "60m"
|
|
provider: "pihole"
|
|
sources:
|
|
- "service"
|
|
- "ingress"
|
|
domainFilters: []
|
|
zoneidFilters: []
|
|
registry: "noop"
|
|
policy: "upsert-only" # would prevent ExternalDNS from deleting any records, omit to enable full synchronization
|
|
piholeServer: "http://pihole.pihole.svc.cluster.local:8089"
|
|
piholePassword: "DitIsSuperGeheim"
|
|
```
|
|
|
|
#### Step 2
|
|
|
|
Verify logs from `External-DNS` to see if it connects and updates `PiHole`
|
|
|
|
```bash
|
|
... PiholeServer:http://pihole.ix-pihole.svc.cluster.local:9089 PiholePassword:****** PiholeTLSInsecureSkipVerify:false PluralCluster: PluralProvider:}"
|
|
2023-11-07 10:29:07.801555-05:00time="2023-11-07T10:29:07-05:00" level=info msg="Instantiating new Kubernetes client"
|
|
2023-11-07 10:29:07.801568-05:00time="2023-11-07T10:29:07-05:00" level=info msg="Using inCluster-config based on serviceaccount-token"
|
|
2023-11-07 10:29:07.801861-05:00time="2023-11-07T10:29:07-05:00" level=info msg="Created Kubernetes client https://172.17.0.1:443"
|
|
2023-11-07 10:29:08.008741-05:00time="2023-11-07T10:29:08-05:00" level=info msg="add firezone.DOMAIN.com IN A -> 192.168.88.105"
|
|
2023-11-07 10:29:10.048171-05:00time="2023-11-07T10:29:10-05:00" level=info msg="add scrutiny.DOMAIN.com IN A -> 192.168.88.105"
|
|
```
|
|
|
|
Check `PiHole` GUI for A records under `Local DNS`
|
|
|
|
|