<p align="center">
<img src="https://raw.githubusercontent.com/maxfield-allison/dnsweaver/HEAD/docs/assets/brand/hero-banner.png" alt="dnsweaver — 컨테이너, VM 및 클러스터용 자동 DNS 레코드" width="100%">
</p>
dnsweaver
CI
Release
Docker Pulls
License
Go Version
컨테이너, VM 및 클러스터용 자동 DNS 레코드.
dnsweaver는 7개의 소스에서 호스트 이름을 읽어와 12개의 DNS 제공업체에 레코드를 작성합니다. 컨테이너가 Traefik 레이블로 시작하거나 Proxmox VM이 부팅되면 레코드가 나타나고, 사라지면 함께 사라집니다. 내부 및 외부 레코드는 동일한 레이블에서 오기 때문에 split-horizon(분할 지평선) 구성 시 추가 비용이 발생하지 않습니다.
📚 전체 문서 보기
왜 dnsweaver인가?
dnsweaver를 홈랩(homelab)을 위한 external-dns라고 생각해보세요. 대부분의 도구들이 문제의 일부 조각만 해결하는 반면, dnsweaver는 셀프 호스팅 사용자(self-hoster)가 실제로 겪게 되는 부분까지 다룹니다:
- Proxmox 지원: PVE API를 통해 VM 및 LXC에 대한 A 레코드를 자동 생성합니다. 거의 다른 DNS 자동화 도구에서는 제공하지 않는 기능입니다.
- 자체 호스팅 DNS 지원: Technitium, Pi-hole, AdGuard Home, 그리고 dnsmasq를 1급(first-class)으로 지원합니다. 추가 고려 사항이 아니며, 알파 버전도 아닙니다.
- 다중 소스 지원: Traefik, Caddy, nginx-proxy, 네이티브 레이블(native labels), Kubernetes, Proxmox VE, Incus를 하나의 바이너리로 통합했습니다. 하나 또는 모두를 한 번에 실행할 수 있습니다.
external-dns는 Kubernetes 전용입니다.
- 기본 탑재 분할 지평선(split-horizon) 기능: 동일한 레이블에서 내부 및 외부 레코드를 처리합니다. 사설 호스트 이름은 Technitium으로, 공용 이름은 Cloudflare로 동시에 라우팅할 수 있습니다.
- 단일 정적 Go 바이너리: 멀티 아키텍처(amd64/arm64)를 지원하며, 별도의 애플리케이션 런타임이나 사이드카가 필요 없습니다.
만약 Traefik, Proxmox 및 자체 호스팅 리졸버를 사용하는 홈랩을 관리하면서 여전히 DNS 레코드를 수동으로 생성하고 있다면, dnsweaver가 바로 당신을 위해 만들어진 도구입니다.
주요 기능 (Features)
- 🔀 다중 공급자 지원(Multi-Provider Support) — 매칭되는 공급자로 도메인을 라우팅하며, 미출시 소스에서는 선택적 워크로드 인스턴스 선택을 제공합니다.
- 🌐 분할 지평선 DNS(Split-Horizon DNS) — 동일한 컨테이너 레이블에서 내부 및 외부 레코드를 관리합니다.
- 🧩 7가지 소스(Seven Sources) — Traefik, Caddy, nginx-proxy, 네이티브 레이블, Kubernetes, Proxmox VE, Incus를 하나의 바이너리에서 지원합니다. 지원되는 소스를 참조하세요.
- 🏗️ 별도의 소유 네임스페이스(Separate ownership namespaces) — 여러 dnsweaver 프로세스를 위해 고유한 인스턴스 ID와 충돌하지 않는 레코드 스코프를 사용합니다. 이는 리더 선출(leader election)이나 능동-능동(active-active HA)을 제공하지는 않습니다.
- 🔒 소켓 프록시 호환(Socket Proxy Compatible) — 보안 강화를 위해 Docker 소켓 프록시에 TCP로 연결할 수 있습니다.
- 🛡️ 강화된 TLS(Hardened TLS) — 모든 HTTP 기반 공급자 및 Proxmox, Incus 소스에 대해 인스턴스별 통합 TLS 제어(사용자 지정 CA, mTLS 클라이언트 인증서, SNI 오버라이드, 구성 가능한 최소 버전; 기본값은 TLS 1.2)를 제공합니다.
- 📊 관측 가능성(Observable) — Prometheus 메트릭, 상태 확인 엔드포인트, 구조화된 로깅을 지원합니다.
- 🔑 비밀(Secrets) 지원 —
_FILE 접미사 변수를 통해 Docker secrets 및 Kubernetes Secrets를 지원합니다.
지원되는 소스 (Supported Sources)
소스는 호스트 이름이 가져오는 출처입니다. DNSWEAVER_SOURCES를 사용하여 모든 조합을 활성화할 수 있습니다.
| 소스 | 읽기 대상 | 구동 환경 |
|---|
traefik | traefik.http.routers.*.rule 레이블, 그리고 Traefik 동적 설정 파일 | Docker, Swarm, Incus |
| ... | | |
지원되는 공급자 (Supported Providers)
공급자는 레코드가 작성되는 곳입니다. 내부 및 외부 DNS를 분리하려면 여러 개를 동시에 실행하세요.
| 공급자 | 레코드 유형 | 참고 사항 |
|---|
| Technitium | A, AAAA, CNAME, SRV, TXT | 기능이 완벽한 자체 호스팅 DNS |
| ... | | |
빠른 시작 (Quick Start)
업그레이드 전
v3.0.0 버전(CHANGELOG.md#300---2026-09-17)부터는 health, readiness 및 metrics가 기본적으로 loopback에서 리스닝됩니다. 원격 스크래퍼(Remote scrapers)와 프로브(probes)는 명시적인 네트워크 리스너와 접근 제한이 필요합니다. management-listener 마이그레이션 가이드를 참조하십시오. 번들된 컨테이너와 Kubernetes 프로브는 로컬 검사를 사용합니다.
동일한 변경 사항은 폴백(falling back)하는 대신 유효하지 않은 TLS 설정 및 읽을 수 없는 자격 증명 파일(credential files)을 거부합니다. 원격 dnsmasq 업데이트를 위해서는 OpenSSH POSIX rename 확장이 있는 SFTP 서버가 필요합니다. 프로바이더 요구사항을 참조하십시오. 이 설정을 적용하기 전에 이미지 태그에 대한 릴리스 노트를 확인하십시오.
설치(Installation)
docker pull maxamill/dnsweaver:latest
...
기본 예제(Basic Example)
services:
dnsweaver:
image: maxamill/dnsweaver:latest
...
작동 방식(How It Works)
flowchart LR
subgraph sources["7개 소스"]
direction TB
...
-
컨테이너가 Traefik 레이블을 가지고 시작하거나 (또는 Kubernetes Ingress/HTTPRoute가 생성됨):
labels:
- "traefik.http.routers.myapp.rule=Host(`myapp.home.example.com`)"
-
dnsweaver는 호스트 이름을 추출하고 이를 구성된 프로바이더 도메인 패턴과 일치시킵니다.
-
일치하는 프로바이더가 DNS 레코드를 생성합니다:
- A record:
myapp.home.example.com → 192.0.2.100
- CNAME:
myapp.example.com → proxy.example.com
-
컨테이너가 중지되거나 (또는 Kubernetes 리소스가 삭제되면) DNS 레코드가 자동으로 정리됩니다.
문서(Documentation)
TLS 구성
HTTP 기반 프로바이더(Technitium, AdGuard Home, Cloudflare, OVHcloud, PowerDNS, Pi-hole, OPNsense, pfSense, Webhook)와 Proxmox 및 Incus 소스는 단일한 TLS 구성 영역을 공유합니다:
| 환경 변수 키 (인스턴스별) | 용도 |
|---|
DNSWEAVER_<NAME>_TLS_CA_FILE | 사설 CA 번들(PEM) 신뢰 |
| ... | |
Proxmox 및 Incus 소스는 DNSWEAVER_PROXMOX_TLS_*와 DNSWEAVER_INCUS_TLS_* 아래에서 동일한 키를 사용합니다 (Incus는 인증서 고정(certificate pinning)을 위해 DNSWEAVER_INCUS_TLS_PIN_SHA를 추가합니다). 레거시 변수인 *_INSECURE_SKIP_VERIFY와 DNSWEAVER_PROXMOX_VERIFY_TLS도 여전히 허용되지만, 시작 시 사용 중단(deprecation) 경고를 발생시키므로 통합된 TLS_SKIP_VERIFY 키로 마이그레이션해야 합니다. 전체 세부 정보 및 레시피는 Environment Reference와 SECURITY.md를 참조하십시오. | |
인증서 마운트? 컨테이너는 권한을 낮추어(drops privileges) uid/gid 1000으로 작동하므로, 인증서/키 파일은 해당 사용자에게 읽기 가능해야 합니다. root:root 0600 키를 사용하면 '권한 거부(permission denied)' 오류가 발생합니다. TLS 인증서 파일 권한을 참조하십시오.
Kubernetes 빠른 시작 (Quick Start)
DNS 관리를 위해 Kubernetes 리소스를 감시하도록 dnsweaver를 배포합니다:
kubectl apply -k https://github.com/maxfield-allison/dnsweaver/deploy/kustomize/base
...
dnsweaver는 Ingress, IngressRoute (Traefik), HTTPRoute (Gateway API), 및 Service 리소스에서 호스트 이름을 자동으로 감지합니다. 리소스별 재정의(per-resource overrides)를 사용하려면 dnsweaver.dev/* 어노테이션을 사용하십시오:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
...
전체 구성은 Kubernetes 배포 가이드를 참조하십시오.
Split-Horizon DNS 예제
동일한 컨테이너 레이블에서 내부 및 외부 DNS를 관리합니다:
environment:
- DNSWEAVER_INSTANCES=internal,external
...
이 구성을 사용하면 app.example.com이 시작될 때 다음이 발생합니다:
- 내부 DNS → A 레코드 →
192.0.2.100
- 외부 DNS → CNAME 레코드 →
tunnel.example.com
기여 (Contributing)
기여는 언제나 환영입니다! 가이드라인은 CONTRIBUTING를 참고해 주세요.
지원 (Support)
dnsweaver는 무료이며 MIT 라이선스를 따릅니다. 이 도구가 시간을 절약해 주었다면, GitHub Sponsors를 통해 ProbablyFine을 후원할 수 있습니다. 후원은 코드 서명(code-signing) 및 기타 개발 비용 충당에 도움이 됩니다. 이는 우선 지원, 로드맵 영향력 또는 약속된 기능을 구매하는 것은 아닙니다.
별점 기록 (Star History)
만약 dnsweaver가 시간을 절약해 주었다면, ⭐ 하나가 다른 사람들이 이 도구를 찾도록 도와줍니다.
Star History Chart
라이선스 (License)
MIT 라이선스
