Namecheap DNS 서브도메인 프로비저닝 (전파 대기)
Namecheap 서브도메인 A 레코드 추가 + DNS 전파 대기 자동화.
새 서브도메인 띄울 때, A 레코드 추가 → DNS 전파 → cert 발급. DNS 부분 (API 추가 + 전파 확인) 한 번에 끝냄.
스크립트: /home/son/prj/log/deploy/namecheap_dns.py, 자격증명: .env.
A 레코드 추가 + 전파 대기 (멱등):
cd /home/son/prj/log
SITE_DOMAIN=[도메인] PUBLIC_IP=[공인IP] \
.venv/bin/python deploy/namecheap_dns.py provision
# A record added, waiting for 8.8.8.8 propagation
전파만 기다릴 때:
SITE_DOMAIN=[도메인] PUBLIC_IP=[공인IP] \
.venv/bin/python deploy/namecheap_dns.py wait
동작: ensure_a_record는 기존 레코드 보존하며 A 레코드 변경. wait_for_dns는 dig @8.8.8.8로 5초마다 폴링, 기대 IP 확인 (timeout 600초). 8.8.8.8 사용으로 ISP 캐시 무관 전파 가시성 보장.
주의: TTL은 전파 시간 아님 (보통 10초~수 분). PUBLIC_IP 정확히 일치해야 함 (CDN/Anycast 부적합). API Access 화이트리스트 (NAMECHEAP_CLIENT_IP in .env) Namecheap 대시보드 WAN IP와 일치해야 함.
여기서 배울 것
- Namecheap DNS API로 A 레코드 추가하고 전파 대기 자동화 가능.
- `dig @8.8.8.8`로 public DNS 전파 확인.
- `PUBLIC_IP` 정확히 맞아야 대기 끝남.
- API 화이트리스트 IP 잘 관리해야 함.
- DNS 프로비저닝 후 certbot HTTP-01 발급 연동.
원본 파일 보기 (.claude/skills/tn-namecheap-dns-provision/SKILL.md)
---
name: Namecheap DNS API로 서브도메인 프로비저닝 (전파 대기 포함)
description: Use when bringing up a new subdomain on a Namecheap-managed domain end-to-end - adds the A record via API and blocks until the record is observable via a public resolver (8.8.8.8). Returns only when DNS is ready, so the next step (e.g. certbot HTTP-01) can proceed without manual polling. Builds on tn-namecheap-dns; use that skill instead if you only need to mutate records without waiting.
version: 1.0.0
---
# 서브도메인 프로비저닝 (Namecheap API + DNS 전파 대기)
새 서브도메인을 띄울 때, A 레코드 추가 → DNS 전파 → cert 발급은 항상 같은 순서다.
이 스킬은 그 중 **DNS 부분(API로 추가 + 전파 확인)**을 한 번의 호출로 끝낸다.
## 위치
- 스크립트: `/home/son/prj/log/deploy/namecheap_dns.py`
- 자격증명: `/home/son/prj/log/.env`
- 함수: `ensure_a_record`, `wait_for_dns` (Python에서 import 가능)
## CLI 사용법
A 레코드 추가 + 전파 대기 (멱등):
```bash
cd /home/son/prj/log
SITE_DOMAIN=learn.ericfromkorea.com PUBLIC_IP=125.131.103.44 \
.venv/bin/python deploy/namecheap_dns.py provision
# ensure A learn.ericfromkorea.com -> 125.131.103.44 ... created
# wait propagation learn.ericfromkorea.com via 8.8.8.8 ... ok (12s)
```
이미 다른 경로(웹 UI 등)로 레코드를 추가했고 전파만 기다리고 싶으면:
```bash
SITE_DOMAIN=foo.ericfromkorea.com PUBLIC_IP=125.131.103.44 \
.venv/bin/python deploy/namecheap_dns.py wait
```
## Python에서 직접 호출
```python
from deploy.namecheap_dns import ensure_a_record, wait_for_dns
action = ensure_a_record("foo.ericfromkorea.com", "125.131.103.44")
elapsed = wait_for_dns("foo.ericfromkorea.com", "125.131.103.44", timeout=600)
print(f"{action} in {elapsed}s")
```
## 동작 원리
- `ensure_a_record`는 `getHosts → 변경 → setHosts` 패턴이라 다른 레코드 보존됨
(`tn-namecheap-dns` 스킬 참조).
- `wait_for_dns`는 `dig +short <fqdn> @8.8.8.8`을 5초 간격으로 폴링.
기대 IP가 응답에 포함되면 성공 (경과 초 반환), 기본 timeout 600초.
- public resolver(`8.8.8.8`)로 확인하므로 ISP DNS 캐시와 무관하게 전파 가시성 보장.
## 함정 / 한계
- **TTL은 전파 시간이 아님**: Namecheap의 1800초 TTL은 "변경 후 갱신 빈도"이지
"처음 등장 시간"이 아님. 새 서브도메인은 보통 10초~수 분 안에 보임.
- **NXDOMAIN → 정답 갈아엎기**: 첫 등록 시 NXDOMAIN이 캐시되어 있으면 8.8.8.8에서도
몇 분 걸릴 수 있음. 이 스크립트는 그 동안 polling만 하므로 대기는 안전.
- **`PUBLIC_IP` 일치 필요**: 헬퍼는 *정확히 그 IP*가 응답에 포함될 때까지 기다림.
CDN/Anycast나 RR DNS면 부적합.
- **API Access 화이트리스트**: `NAMECHEAP_CLIENT_IP` (.env)가 Namecheap 대시보드에
등록된 WAN IP와 일치해야 함. 가정 회선 WAN IP 변경 시 재등록.
## 다음 단계 (보통 같이 함)
1. 이 스킬로 DNS provisioning 완료
2. nginx HTTP-only stub 작성 + reload (`/.well-known/acme-challenge/` 경로 노출)
3. `sudo certbot certonly --webroot -w /var/www/letsencrypt -d <fqdn>` 로 HTTP-01 발급
4. nginx HTTPS 풀 설정으로 교체 + reload
→ 이 4단계 통째로 자동화한 예시: `/home/son/prj/thesis/scripts/setup_server.sh`
(관련 스킬: `tn-thesis-publish`).