DNS 존
dns 카테고리의 API 작업 8개를 다룹니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | /v1/orgs/{orgSlug}/dns/zones | DNS 존 목록 (runlot dns zones) |
| POST | /v1/orgs/{orgSlug}/dns/zones | DNS 존을 생성합니다 (runlot dns create) |
| GET | /v1/orgs/{orgSlug}/dns/zones/{zone} | 단일 DNS 존과 그 안의 모든 레코드 |
| DELETE | /v1/orgs/{orgSlug}/dns/zones/{zone} | DNS 존을 삭제합니다 (runlot dns delete) |
| PUT | /v1/orgs/{orgSlug}/dns/zones/{zone}/rrsets/{name}/{type} | 레코드를 생성하거나 업데이트합니다 (runlot dns set) |
| DELETE | /v1/orgs/{orgSlug}/dns/zones/{zone}/rrsets/{name}/{type} | 레코드를 삭제합니다 (runlot dns rm) |
| POST | /v1/orgs/{orgSlug}/dns/zones/{zone}/dnssec | 존 서명을 켜거나 끕니다 |
| PUT | /v1/orgs/{orgSlug}/dns/zones/{zone}/dnssec/ds | 부모 존에 등록할 DS를 저장합니다 |
GET /v1/orgs/{orgSlug}/dns/zones
이 org가 Runlot 네임서버에서 운영하는 DNS 존 목록입니다(docs/domains.md §4). rrsets는 포함되지 않으며, 단일 항목 조회에서만 제공됩니다. viewer 이상이 사용할 수 있습니다.
operationId listZones
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 목록 조회 | ZoneList |
| 403 | — | — |
| 404 | — | — |
| 503 | 배포에서 자체 DNS가 꺼져 있거나(dns_not_configured), cp-public이 cp-core 주소 없이 시작되었습니다(no_core). | Error |
POST /v1/orgs/{orgSlug}/dns/zones
멱등적입니다 — 이미 존재하는 존은 변경 없이 그대로 반환됩니다. 존은 SOA(생성기가 serial로 만듭니다)와 apex NS rrset을 갖고 생성되며, 이 NS는 managed_by = system이기 때문에 편집기에서 잠겨 있습니다. 사용자가 이를 삭제하면 도메인이 전혀 해석되지 않습니다(§7).
존을 생성하는 것만으로는 아직 어떤 이름도 우리의 응답을 받지 않습니다. 위임이 적용되려면 레지스트라에서 NS를 nameservers로 변경해야 합니다(delegation 배지가 그 상태를 반영합니다). admin 이상이 필요합니다. dns.zone.create로 감사됩니다.
operationId createZone
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 생성되었거나 이미 존재하던 존 | ZoneDetail |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 409 | 다른 org가 이미 사용 중인 DNS 존입니다 (zone_taken) | Error |
| 503 | 배포에서 자체 DNS가 꺼져 있거나(dns_not_configured), cp-public이 cp-core 주소 없이 시작되었습니다(no_core). | Error |
GET /v1/orgs/{orgSlug}/dns/zones/{zone}
viewer 이상이 필요합니다.
operationId getZone
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | DNS 존과 RRset | ZoneDetail |
| 403 | — | — |
| 404 | — | — |
| 503 | 배포에서 자체 DNS가 꺼져 있거나(dns_not_configured), cp-public이 cp-core 주소 없이 시작되었습니다(no_core). | Error |
DELETE /v1/orgs/{orgSlug}/dns/zones/{zone}
모든 레코드와 DNS 존 파일을 함께 삭제합니다. 위임이 여전히 Runlot 네임서버를 가리키고 있으면 도메인이 제대로 연결되지 않습니다. 삭제하기 전에 레지스트라에서 NS를 변경해야 합니다. admin 이상입니다. Audit dns.zone.delete.
operationId deleteZone
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 204 | 삭제됨 | — |
| 403 | — | — |
| 404 | — | — |
| 503 | 배포에서 자체 DNS가 꺼져 있거나(dns_not_configured), cp-public이 cp-core 주소 없이 시작되었습니다(no_core). | Error |
PUT /v1/orgs/{orgSlug}/dns/zones/{zone}/rrsets/{name}/{type}
rrset(name + type) 하나 전체를 교체합니다 — 값 하나를 추가하는 것이 아니라 records가 그 rrset의 새로운 전체 내용이 됩니다.
검증은 저장 시점에 이루어집니다(§4.3): CNAME은 apex에 둘 수 없고 같은 이름에 다른 타입과 공존할 수 없으며, A/AAAA, MX, SRV, CAA는 형식을 검사합니다. 255바이트를 초과하는 TXT 레코드는 존 파일에서 여러 조각으로 분할됩니다. managed_by가 설정된 레코드(프로젝트 연결, ACME, 또는 DNS 존의 NS)는 409 managed_rrset을 반환합니다.
member 이상의 권한이 필요합니다. dns.rrset.set으로 감사 기록됩니다.
operationId putRRset
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 저장된 rrset | RRset |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 409 | 프로젝트가 관리하는 레코드(managed_rrset)이거나 CNAME 공존 금지에 해당하는 레코드(cname_conflict) | Error |
| 503 | 배포에서 자체 DNS가 꺼져 있거나(dns_not_configured), cp-public이 cp-core 주소 없이 시작되었습니다(no_core). | Error |
DELETE /v1/orgs/{orgSlug}/dns/zones/{zone}/rrsets/{name}/{type}
관리되는 레코드는 409 managed_rrset을 반환합니다. 프로젝트 연결을 해제하려면 레코드를 삭제하는 대신 프로젝트의 Domains 화면에서 연결 해제하세요(§7). member 이상의 권한이 필요합니다. 감사 이벤트 dns.rrset.delete.
operationId deleteRRset
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 204 | 삭제됨 | — |
| 403 | — | — |
| 404 | — | — |
| 409 | 앱이 관리하는 행(managed_rrset) | Error |
| 503 | 배포에서 자체 DNS가 꺼져 있거나(dns_not_configured), cp-public이 cp-core 주소 없이 시작되었습니다(no_core). | Error |
POST /v1/orgs/{orgSlug}/dns/zones/{zone}/dnssec
off → signing. 서명은 네임서버(Knot)가 수행하며, 키 자료는 CP에 저장되지 않습니다(§4.5). 기능을 비활성화하면 기록된 DS도 삭제됩니다. 상위 존에 오래된 키의 DS를 등록하면 도메인이 올바르게 검증되지 않습니다. admin 이상 사용할 수 있습니다.
operationId setZoneDNSSEC
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 변경된 존 | Zone |
| 403 | — | — |
| 404 | — | — |
| 503 | 배포에서 자체 DNS가 꺼져 있거나(dns_not_configured), cp-public이 cp-core 주소 없이 시작되었습니다(no_core). | Error |
PUT /v1/orgs/{orgSlug}/dns/zones/{zone}/dnssec/ds
CP는 상위 존을 조회하지 않습니다. 이 값은 네임서버가 DS 레코드를 생성했다는 사실을 운영자(또는 D3의 레지스트라 동기화)가 보고한 것이며, 상태는 signing → ds_pending으로 이동합니다. 빈 목록은 "아직"을 의미하므로 상태를 진행시키지 않습니다. admin 이상의 권한이 필요합니다.
operationId setZoneDS
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 변경된 존 | Zone |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 409 | 존의 DNSSEC이 꺼져 있음(dnssec_off) | Error |
| 503 | 배포에서 자체 DNS가 꺼져 있거나(dns_not_configured), cp-public이 cp-core 주소 없이 시작되었습니다(no_core). | Error |