커스텀 도메인
커스텀 도메인 카테고리의 API 작업 4개를 다룹니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames | 프로젝트에 연결된 도메인 목록 (runlot domain list) |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames | 커스텀 도메인을 연결합니다 (runlot domain add) |
| DELETE | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host} | 커스텀 도메인 연결을 해제합니다 (runlot domain rm) |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}/verify | 지금 도메인을 검증합니다 (runlot domain verify) |
GET /v1/orgs/{orgSlug}/projects/{projectName}/hostnames
기본 호스트네임(kind: default)과 커스텀 도메인(kind: custom)을 함께 반환합니다. 각 커스텀 도메인 레코드에는 게시해야 할 DNS 레코드(verify)와 현재 상태가 포함됩니다. viewer 이상의 권한이 필요합니다.
operationId listHostnames
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 목록 조회 | HostnameList |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/projects/{projectName}/hostnames
이름은 저장되기 전에 소문자 퓨니코드로 정규화됩니다. 와일드카드와 runlot 자체 도메인(*.runlot.app, *.runlot.dev, *.runlot.io, 앱 도메인) 하위의 이름은 허용되지 않습니다.
레코드는 pending_dns 상태로 생성되며, 그 순간부터 해당 이름을 예약합니다. 검증이 진행되는 동안에는 다른 프로젝트가 같은 이름을 사용할 수 없습니다. 연결되기 전까지는 라우팅되지 않으므로, 그동안 해당 이름으로의 요청은 404 unknown_hostname을 반환합니다.
같은 프로젝트에서 같은 이름을 다시 전송하면 기존 레코드가 변경 없이 반환되므로, 이미 게시한 검증 토큰이 계속 유효합니다. member 이상의 권한이 필요합니다. 감사 로그에 hostname.add로 기록됩니다.
operationId addHostname
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 새로 생성된 레코드 또는 기존 레코드 | Hostname |
| 400 | 유효한 이름 형식이 아니거나(bad_request), 와일드카드이거나, 자체 도메인 아래에 있는 경우 | Error |
| 403 | — | — |
| 404 | — | — |
| 409 | 두 가지 거부 사유가 이 상태를 공유합니다. hostname_taken — 이름이 이미 다른 프로젝트에 속해 있습니다. hostname_limit — 프로젝트가 이미 커스텀 도메인에 대한 플랜의 상한에 도달했습니다(프로젝트당 Free 1개, Pro 50개). details에는 limit, count, plan이 담겨 있어, 클라이언트가 텍스트를 파싱하는 대신 숫자로 메시지를 구성할 수 있습니다. 프로젝트가 이미 소유한 이름을 다시 전송하는 경우는 이런 식으로 거부되지 않으며, 여전히 200을 응답합니다. | Error |
DELETE /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}
커스텀 호스트네임과 runlot DNS 영역 내 관리 레코드를 함께 제거합니다. 이후 해당 이름으로의 요청은 프로젝트에 도달하지 않습니다. 기본 호스트네임은 삭제할 수 없습니다(400). member 이상의 권한이 필요합니다. 감사 로그에 hostname.delete로 기록됩니다.
operationId deleteHostname
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 204 | 연결 끊김 | — |
| 400 | 기본 호스트네임입니다 | Error |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}/verify
백그라운드 작업이 매분 실행하는 것과 동일한 검증을 즉시 실행합니다. 다음 세 조건 중 하나라도 충족되면 소유권이 통과합니다: 이름이 같은 org가 소유한 runlot 호스팅 영역에 있는 경우, _runlot-verify.<host> TXT 레코드가 일치하는 경우, 또는 <host>의 CNAME이 폴백 오리진을 가리키는 경우입니다.
도메인은 소유권 증명 없이는 active 상태가 될 수 없습니다. 검증을 통과하지 못하면 상태는 변경되지 않으며 lastError가 관찰된 내용을 설명합니다. member 이상의 권한이 필요합니다.
operationId verifyHostname
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 검증 후 호스트네임 | Hostname |
| 403 | — | — |
| 404 | — | — |