> For the complete documentation index, see [llms.txt](https://ia-cloud.gitbook.io/cloudia-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ia-cloud.gitbook.io/cloudia-manual/network/private-dns.md).

# 내부 DNS

`내부 DNS`는 특정 VPC 내부에서 해석되는 전용 DNS 입니다. 복잡한 내부 IP 주소 대신 db.internal과 같이 기억하기 쉬운 도메인 기반의 통신 환경을 구축할 수 있습니다. 필요 시 `외부 조회 허용`을 켜면 VPC 외부에서도 이 도메인을 조회할 수 있습니다.

## 화면 개요

* `목록 화면`: 내부 DNS 목록을 조회하고 생성, 편집, 삭제 작업을 시작합니다.
* `상세 화면`: 선택한 내부 DNS의 기본 정보, 외부 조회 허용 여부와 서버 상태, 등록된 모든 레코드 리스트를 확인합니다. 서버에 이상이 있으면 복구를 시도할 수 있습니다.
* `생성 화면`: 서비스할 내부 DNS와 이를 적용할 VPC, 외부 조회 허용 여부를 정의합니다.
* `편집 화면`: DNS 존의 설명과 외부 조회 허용 여부를 수정합니다.
* `레코드 편집 화면`: 도메인 내부의 개별 레코드들을 집중적으로 관리(추가/수정/삭제)합니다.

## 내부 DNS 목록

### 주요 작업

* `생성`: 새로운 내부 DNS를 생성합니다.
* `편집`: 선택한 1개 내부 DNS의 설명을 편집합니다.
* `삭제`: 선택한 1개 내부 DNS를 삭제합니다. 기본 `NS`, `SOA` 를 제외한 레코드가 있으면 삭제할 수 없습니다.

### 테이블 컬럼

| 컬럼         | 설명                                                                            |
| ---------- | ----------------------------------------------------------------------------- |
| **도메인 이름** | 내부 DNS의 기준이 되는 존(Zone) 주소입니다. **클릭하면 상세 화면으로 이동**합니다. (예: `internal.cloudia`) |
| **ID**     | 내부 DNS 고유 ID입니다.                                                              |
| **VPC**    | 해당 도메인이 유효하게 동작하는 네트워크 범위입니다. 선택된 VPC 내 자원들만 이 도메인을 해석할 수 있습니다.               |
| **레코드 수**  | 현재 존에 등록되어 있는 레코드의 총 개수입니다.                                                   |
| **설명**     | 내부 DNS 설명 정보 입니다.                                                             |
| **생성 일시**  | 내부 DNS가 생성된 날짜와 시각입니다.                                                        |

## 내부 DNS 상세

### 상단 요약

* **도메인 이름**: 내부 DNS의 기준 도메인(Zone)입니다. 하위 레코드는 이 도메인을 기준으로 이름이 결합되어 전체 레코드 주소(FQDN)가 됩니다.
  * 예: 레코드 이름 `app` + 도메인 `example.com` → FQDN `app.example.com`
* **ID**: 내부 DNS를 식별하기 위한 시스템 고유 ID입니다.
* **VPC**: 해당 DNS 설정이 적용되는 VPC이며, 이름과 ID가 함께 표시됩니다.
* **레코드 수**: 현재 해당 도메인에 등록된 전체 레코드의 개수입니다.
* **생성 일시**: 내부 DNS가 생성된 날짜와 시각입니다.
* **설명**: 관리자가 해당 DNS의 용도를 식별하기 위해 입력한 설명입니다.
* **외부 조회 허용**: 이 도메인을 VPC 외부에서도 조회할 수 있는지 여부입니다. 허용된 경우 외부 조회에 사용할 DNS 주소(선택한 VPC의 외부 통신 IP)가 함께 표시되고, 허용하지 않으면 `허용 안 함`으로 표시됩니다.
* **서버 상태**: 내부 DNS 서버의 동작 상태입니다. `정상` 또는 `이상`으로 표시되며, 마지막 검사 시각(예: `마지막 검사 30초 전`)이 함께 표시됩니다.

### 서버 상태 및 복구

* 상세 화면 상단의 **서버 상태**로 내부 DNS 서버의 동작 상태(`정상`/`이상`)를 확인합니다.
* 서버에 이상이 감지되면 경고 안내(“DNS 서버가 응답하지 않아 도메인 조회에 실패할 수 있습니다. 복구를 시도하거나 문제가 계속되면 관리자에게 문의하세요.”)와 함께 **`서버 복구`** 버튼이 표시됩니다.
* `서버 복구`를 누르면 복구가 시작되고 버튼은 `복구 중…`으로 바뀝니다. 복구가 완료되면 “DNS 서버가 복구되었습니다.” 안내가 표시됩니다.
* 서버 상태와 마지막 검사 시각은 30초 주기로 자동 갱신됩니다.

### 하단 목록: 레코드

상세 화면 하단에서 실제 통신 경로를 정의하는 레코드 목록을 확인합니다. `편집`을 누르면 레코드 레코드 편집 화면에 진입할 수 있습니다.

| 컬럼          | 설명                                                                                   |
| ----------- | ------------------------------------------------------------------------------------ |
| **이름**      | 레코드 이름입니다. 도메인 내에서 특정 서비스(www, api 등)를 식별하기 위해 부여하며, 도메인과 결합된 전체 주소(FQDN) 형태로 표시됩니다. |
| **타입**      | VPC 내 DNS 서버가 질의에 응답할 데이터 형식입니다. (`A`, `CNAME`, `TXT` 등)                             |
| **값**       | DNS 질의에 대해 최종적으로 반환되는 목적지(IP 주소) 또는 문자열 정보입니다. 값이 여러 개인 경우 콤마(`,`)로 구분되어 표시됩니다.      |
| **TTL (초)** | TTL(Time To Live) 값입니다. 이 정보가 클라이언트 캐시에 머무르는 시간(초)을 의미합니다.                           |
| **생성 일시**   | 레코드가 생성된 날짜와 시각입니다.                                                                  |

> 💡 **참고:** 기본 레코드 안내 NS 및 SOA 레코드는 도메인 존의 권한과 관리 정보를 담고 있는 필수 레코드로, 시스템에서 관리하며 수정이나 삭제가 불가능합니다.

## 내부 DNS 생성

### 기본 정보

* **도메인 이름**: 내부 리소스들이 주소로 사용할 기본 도메인을 입력합니다. (예: `internal.cloudia`)
* **VPC**: 내부 DNS를 적용할 대상 VPC를 선택합니다.
* **외부 조회 허용**: VPC 외부에서도 이 도메인을 조회할 수 있게 할지 선택합니다. 기본값은 허용 안 함이며, 허용하면 `VPC 외부에서 사용할 DNS 주소`(선택한 VPC의 외부 통신 IP가 자동 지정) 카드가 표시됩니다. VPC를 아직 선택하지 않았으면 `VPC 선택 후 표시`로 안내됩니다.
* **설명**: 내부 DNS 설명을 입력합니다.

> ⚠️ **주의:** 외부 조회를 허용하면 도메인 이름과 내부 IP 주소가 외부에 노출될 수 있습니다.

### 입력 필드 유효성

| 필드           | 허용 값                                  | 검증 규칙                                                                                                                               | 비고                                  |
| ------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **도메인 이름**   | 최대 80자 유효한 도메인 문자열, 영문 소문자/숫자/`-`/`.` | <p>필수입니다. 점(.)으로 시작/종료하거나 연속 점(<code>..</code>)을 사용할 수 없습니다.<br>점(.)으로 구분된 각 부분(레이블)은 1\~63자 사이여야 하며, 하이픈(-)으로 시작하거나 끝날 수 없습니다.</p> | 내부 DNS 존의 루트 이름입니다.                 |
| **VPC**      | 현재 프로젝트의 VPC                          | 필수입니다. 선택 완료 후 하단 레코드 추가가 활성화됩니다.                                                                                                   | 존 적용 대상입니다.                         |
| **외부 조회 허용** | `허용` / `허용 안 함`                       | 선택 입력입니다. 기본값은 허용 안 함입니다. 허용 시 선택한 VPC의 외부 통신 IP가 외부 조회용 주소로 자동 지정됩니다.                                                              | 허용하면 도메인 이름과 내부 IP가 외부에 노출될 수 있습니다. |
| **설명**       | 최대 200자 문자열                           | 선택 입력입니다. 200자를 초과할 수 없습니다.                                                                                                         | 운영 메모용입니다.                          |

### 레코드

생성 시점에 필요한 레코드를 미리 등록할 수 있습니다.

* `추가`: 새로운 레코드를 추가합니다.
* `편집`: 선택한 레코드를 편집합니다.
* `삭제`: 선택한 레코드를 삭제합니다.

레코드 추가 버튼은 다음 조건이 만족되어야 활성화됩니다.

* 도메인 이름이 유효해야 합니다.
* VPC가 선택되어 있어야 합니다.

#### 기본 레코드

* `NS`
* `SOA`

두 레코드는 생성 화면에서 자동으로 준비되며 삭제할 수 없습니다. 도메인 이름을 바꾸면 기본 레코드도 새 도메인 기준으로 다시 세팅됩니다.

> 💡 **참고:** 시스템 자동 관리 안내
>
> `NS` 레코드는 해당 내부 DNS 영역을 관리하는 네임서버 정보를 나타내고, `SOA` 레코드는 내부 DNS 영역의 기준 정보와 관리 정보를 나타냅니다. NS와 SOA 레코드는 시스템에서 자동으로 관리합니다. 특히 SOA의 일련번호(Serial Number)는 시스템 내부적으로 관리 기준에 따라 최신 상태로 유지되므로, 사용자가 별도로 수정할 필요가 없습니다.

## 내부 DNS 편집

편집 화면에서는 **설명**과 **외부 조회 허용** 여부를 수정할 수 있습니다.

다음 항목은 편집할 수 없습니다.

* **도메인 이름**: 생성 후 고정되며 편집할 수 없습니다.
* **VPC**: 생성 후 고정되며 다른 VPC로 변경할 수 없습니다.

레코드 편집은 상세 화면의 `레코드 편집`에서 별도로 수행합니다.

### 편집 항목

* **설명**: 내부 DNS 존의 용도, 운영 메모, 참조 서비스를 갱신할 때 사용합니다.
* **외부 조회 허용**: VPC 외부 조회 허용 여부를 변경합니다. 허용으로 바꾸면 도메인 이름과 내부 IP 주소가 외부에 노출될 수 있습니다.

### 편집 입력 필드 유효성

| 필드           | 허용 값            | 검증 규칙                                               | 비고          |
| ------------ | --------------- | --------------------------------------------------- | ----------- |
| **설명**       | 최대 200자 문자열     | 선택 입력입니다. 200자를 초과할 수 없습니다.                         | 편집 가능합니다.   |
| **외부 조회 허용** | `허용` / `허용 안 함` | 선택 입력입니다. 허용 시 선택된 VPC의 외부 통신 IP가 외부 조회용 주소로 지정됩니다. | 편집 가능합니다.   |
| **도메인 이름**   | 기존 값 고정         | 편집할 수 없습니다.                                         | 생성 시 결정됩니다. |
| **VPC**      | 기존 값 고정         | 편집할 수 없습니다.                                         | 생성 시 결정됩니다. |

***

## 외부 조회 허용 안내

`외부 조회 허용`을 켜면 함께 표시되는 `VPC 외부에서 사용할 DNS 주소`로 VPC 밖에서도 이 도메인을 조회할 수 있습니다. 사용 전에 다음 동작을 알아두세요.

### 동작 범위

* 이 주소는 **허용한 도메인의 질의에만 응답**합니다. 그 외 도메인(일반 인터넷 도메인 포함)에 대한 질의는 거부됩니다.
* 같은 VPC에 내부 DNS가 여러 개 있는 경우, `외부 조회 허용`을 켠 내부 DNS만 외부에서 조회할 수 있습니다. 나머지는 계속 VPC 내부 전용으로 유지됩니다.
* 허용 여부 변경이나 레코드 수정은 DNS 서버에 수 초 내 반영됩니다. 다만 이미 조회된 적이 있는 레코드는 조회한 환경(운영체제, 사내 DNS 등)의 캐시에 TTL 동안 남아 있어, 값이 바뀌어도 TTL이 지나기 전까지는 이전 값이 응답될 수 있습니다. 값이 바뀔 수 있는 레코드는 TTL을 짧게 설정하세요.

### 외부 환경에서 사용하는 방법

* 일회성 확인은 조회 명령에 주소를 직접 지정합니다. 예: `dig @<VPC 외부에서 사용할 DNS 주소> app.example.internal`
* PC나 애플리케이션에서 상시 사용하려면, **해당 도메인의 질의만 이 주소로 보내도록** 설정합니다. 사내 DNS 서버가 있다면 이 도메인에 대한 조건부 전달(포워딩) 규칙을 등록하고, PC 단독으로 사용할 때는 운영체제의 도메인별 DNS 지정 기능을 사용합니다.

> ⚠️ **주의:** `VPC 외부에서 사용할 DNS 주소`를 PC나 서버의 **기본 DNS 서버로 등록하지 마세요.** 이 주소는 허용한 도메인 외의 질의에는 응답하지 않으므로, 기본 DNS 서버로 등록하면 일반 인터넷 도메인의 이름 해석이 되지 않습니다.

### 외부에서 실제 접속까지 하려면

## 외부 조회는 도메인 이름을 IP 주소로 해석해 줄 뿐, 해석된 IP로 접속할 수 있는지는 별개입니다. 레코드 값이 VPC 내부 IP이면 외부에서 이름은 해석되지만 접속은 되지 않습니다. 외부 사용자가 접속할 도메인은 레코드 값을 **외부에서 접근 가능한 값**(플로팅 IP, 포트 포워딩, 외부 타입 로드 밸런서 등)으로 등록하세요.

## 레코드 편집

상세 화면에서 진입하는 별도 편집 화면입니다.

### 주요 작업

* `추가`: 새 레코드를 추가합니다.
* `편집`: 선택한 1개 레코드를 편집합니다.
* `삭제`: 선택한 레코드를 삭제합니다.
* `저장`: 변경 사항을 저장합니다.
* `취소`: 저장하지 않고 내부 DNS 상세로 돌아갑니다.

### 테이블 컬럼

| 컬럼          | 설명                                                                                   |
| ----------- | ------------------------------------------------------------------------------------ |
| **이름**      | `레코드 이름.도메인 이름` 형식의 전체 레코드 주소(FQDN)입니다. 레코드 이름이 없으면 도메인 이름만 표시됩니다.                   |
| **타입**      | 레코드 타입으로 `NS`, `SOA`, `A`, `CNAME`, `TXT`, `SRV` 중 하나입니다.                            |
| **값**       | 레코드 값입니다. A 타입은 리소스 기반 IP, CNAME/TXT/SRV는 문자열 값입니다. 값이 여러 개인 경우 콤마(`,`)로 구분되어 표시됩니다. |
| **TTL (초)** | TTL(Time To Live) 값입니다.                                                              |
| **생성 일시**   | 레코드가 생성된 날짜와 시각입니다.                                                                  |

* 기본 `NS`, `SOA` 레코드는 조회만 가능하고 수정하거나 삭제할 수 없습니다.
* `저장`은 변경 사항이 있을 때만 활성화됩니다.

### 레코드 입력 항목

* **이름**: 존 내부에서 사용할 레코드 이름을 입력합니다. 입력한 이름과 도메인 이름을 합친 **전체 레코드 주소**가 표시됩니다.
* **TTL**: DNS 캐시 유지 시간을 초 단위로 지정합니다.
* **타입**: `A`, `CNAME`, `TXT`, `SRV` 중 하나를 선택합니다.
* **값**: 타입에 따라 리소스 기반 IP 주소 또는 문자열 값을 입력합니다.
  * `A` 타입 선택 시 인스턴스, 로드 밸런서 등 프로젝트 내 리소스를 직접 선택하여 IP를 자동 매핑할 수 있습니다.

> 💡 참고: "실제 서비스에서 접근에 사용되는 전체 DNS 이름입니다."

### 레코드 입력 필드 유효성

| 필드      | 허용 값                       | 검증 규칙                                                                                            | 비고                                    |
| ------- | -------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------- |
| **이름**  | 존 내부 상대 이름 문자열             | 필수입니다. 동일한 레코드 이름은 중복 생성할 수 없습니다.                                                                | 전체 주소는 `이름.도메인`으로 표시됩니다.              |
| **TTL** | 초 단위 숫자                    | 필수입니다. 숫자 형식이어야 합니다.                                                                             | 레코드 캐시 유지 시간입니다.                      |
| **타입**  | `A`, `CNAME`, `TXT`, `SRV` | 필수입니다. 타입에 따라 값 입력 방식이 달라집니다.                                                                    | 기본 `NS`, `SOA`는 수정 대상이 아닙니다.          |
| **값**   | 타입별 문자열 또는 리소스 기반 값        | 필수입니다. `CNAME`은 값 1개만 허용하고, `TXT`, `SRV`, `A`는 여러 값을 추가할 수 있습니다. 같은 레코드 안에 동일한 값을 중복 추가할 수 없습니다. | `A`는 프로젝트 리소스나 VPC 내부 IP를 선택할 수 있습니다. |

### 지원 타입과 값 입력 방식

각 레코드 타입은 아래 용도로 사용하며, 타입에 따라 값 입력 방식이 다릅니다.

* **A**: 도메인 이름을 IPv4 주소로 연결합니다. 값은 직접 입력하지 않고 인스턴스, 로드 밸런서, 포트 포워딩, 플로팅 IP, VPC 내부 IP 중에서 **리소스를 선택**하면 해당 IP를 매핑할 수 있습니다. 값을 여러 개 추가할 수 있습니다.
* **CNAME**: 도메인 이름을 다른 도메인 이름의 **별칭**으로 연결합니다(최종 목적지는 그 이름의 A 레코드로 다시 해석됩니다). 값은 **1개만** 허용하며, 점(.)을 포함한 전체 도메인 이름(FQDN) 형식으로 입력하는 것을 권장합니다. 예: `api.internal.`
* **TXT**: 도메인에 임의의 **텍스트 값**을 붙입니다. 도메인 소유 검증, SPF 같은 정책 문자열 등에 사용합니다. 값을 여러 개 추가할 수 있습니다. 예: `version=1.0`
* **SRV**: 특정 \*\*서비스의 위치(호스트와 포트)\*\*를 알립니다. 값은 `우선순위 가중치 포트 대상` 순서의 **공백으로 구분된 한 줄 문자열**로 입력합니다. 예: `10 5 443 auth.svc.internal.`
  * `우선순위`·`가중치`·`포트`는 모두 `0`\~`65535` 범위의 정수입니다.
  * `대상`은 서비스가 실제 제공되는 호스트의 도메인 이름(FQDN)입니다.
  * 값을 여러 개 추가할 수 있습니다.

### 레코드 편집 제약

* 동일 레코드 이름은 중복 생성할 수 없습니다.
* `CNAME`은 값 1개만 가질 수 있습니다.
* `TXT`, `SRV`, `A`는 여러 값을 추가할 수 있습니다.
* 동일한 값은 같은 레코드 안에 중복 추가할 수 없습니다.
* 기본 `NS`, `SOA` 레코드는 편집 화면에서도 수정하거나 삭제할 수 없습니다.

### A 레코드 활용 방식

A 레코드는 단순 문자열 대신 실제 프로젝트 리소스에서 값을 선택할 수 있습니다.

* **인스턴스**: 인스턴스와 내부 IP 주소를 선택
* **로드 밸런서**: 내부 타입이면 내부 IP, 외부 타입이면 외부 IP를 참조
* **포트 포워딩**: 포트 포워딩의 외부 IP를 참조
* **플로팅 IP**: 플로팅 IP 주소를 참조
* **IP 주소**: VPC 내부 IP를 직접 선택

> 💡 **참고:** `외부 조회 허용`으로 외부에서 사용할 도메인이라면 인스턴스 내부 IP 대신 플로팅 IP, 포트 포워딩, 외부 타입 로드 밸런서처럼 외부에서 접근 가능한 값을 선택하세요. 내부 IP는 외부에서 이름만 해석되고 실제 접속은 되지 않습니다.

***

## 내부 DNS 삭제

* 사용자 정의 레코드가 모두 삭제된 상태(`NS`, `SOA`만 남은 상태)여야 삭제 버튼이 활성화됩니다.

### 삭제 절차

내부 DNS를 안전하게 삭제하기 위해 다음 단계를 준수해주세요.

1. 사용자가 추가한 모든 사용자 정의 레코드(A, CNAME 등)를 먼저 삭제합니다.
2. 해당 도메인을 통해 통신 중인 애플리케이션 설정이 있는지 마지막으로 확인합니다.
3. 목록 화면에서 대상 존을 선택하고 삭제를 진행합니다.

> ⚠️ **주의:** 내부 DNS 삭제는 **복구할 수 없습니다.** 삭제 전에 반드시 해당 내부 DNS의 용도를 확인한 후 삭제하세요.