본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

커스텀 도메인

원문 보기 위키 갱신

Fly App을 만들면 앱 이름을 바탕으로 fly.dev 하위 도메인이 자동으로 주어져요. 테스트에는 좋지만, 완전한 프로덕션으로 나아가면 여러분만의 도메인에서 앱이 보이고 HTTPS가 자동으로 설정되기를 원할 거예요. 이 페이지에서는 Fly App에 도메인을 추가하고 DNS 레코드를 구성하는 방법, 자체 인증서 사용, 관련 명령과 문제 해결 방법을 안내합니다.

출처: 문서

본문

Fly App을 만들면 앱 이름을 바탕으로 fly.dev 하위 도메인이 자동으로 부여됩니다. 테스트에는 좋지만, 완전한 프로덕션으로 전환할 때는 앱이 여러분만의 도메인에 나타나고 .fly.dev 도메인과 마찬가지로 HTTPS가 자동으로 설정되기를 원할 거예요. 그러려면 Fly App에 도메인을 추가한 다음 DNS 제공자를 통해 DNS 레코드를 구성하면 됩니다.

앱에 커스텀 도메인 추가

커스텀 도메인을 추가하려면 먼저 도메인을 Fly App에 연결해 DNS 구성 지침을 받은 다음, DNS 제공자로 DNS 레코드를 구성하세요.

앱에 도메인 추가

도메인을 Fly App에 연결합니다. 그러면 앱이 커스텀 도메인용 TLS 인증서를 생성하고 트래픽을 처리할 준비가 되며, 여러분의 설정에 맞는 DNS 구성 옵션을 보여줘요.

flyctl로 또는 앱 대시보드의 Certificates 아래에서 도메인을 추가할 수 있습니다.

예를 들어, CLI를 사용하면:

fly certs add example.com

이 명령은 여러분의 설정에 적용되는 DNS 구성 옵션을 보여줍니다.

와일드카드 도메인을 CLI로 추가한다면 셸 확장을 피하기 위해 호스트네임을 따옴표로 묶으세요.

fly certs add "*.example.com"

fly certs check <hostname>으로 인증서 상태와 검증 진행 상황을 확인하거나, fly certs setup <hostname>으로 모든 설정 옵션을 볼 수 있어요.

DNS 레코드 구성

이제 앱에 도메인을 추가했으니, DNS 제공자로 DNS 레코드를 구성해 트래픽을 Fly App으로 보내세요. 대시보드나 fly certs add의 설정 지침이 여러분 상황에 맞는 권장 DNS 구성을 보여줍니다.

상황에 맞는 DNS 설정을 선택하세요.

중요: Fly.io가 인증서를 발급하거나 갱신하려면 다음 중 하나 이상으로 도메인을 검증해야 해요: 앱을 가리키는 IPv6 주소(AAAA 레코드), CNAME _acme-challenge, 또는 _fly-ownership TXT 레코드.

A 및 AAAA 레코드 (권장)

대부분의 직접 연결에는 A와 AAAA 레코드를 사용하세요. 이 레코드는 도메인을 앱의 IP 주소로 바로 가리킵니다.

설정해야 하는 A와 AAAA 레코드는 대시보드와 fly certs add의 출력에 표시됩니다. 앱에 IPv4와 IPv6 주소가 없다면 fly ips allocate로 할당하세요.

CNAME 레코드

CNAME 레코드는 하위 도메인(www.example.com이나 app.example.com 같은)에 잘 작동해요. CNAME은 커스텀 도메인을 앱의 고유한 .fly.dev 호스트네임으로 가리킵니다. CNAME 레코드는 앱에 많은 IP 주소가 할당되어 있거나 앞으로 변경할 예정일 때도 좋은 옵션입니다.

DNS 제공자에서 CNAME 레코드를 설정하세요. 각 앱에는 인증서의 대시보드나 fly certs setup의 출력에 표시되는 고유한 CNAME 대상이 있어요.

apex 도메인에 CNAME 레코드를 설정하는 것은 문제가 될 수 있어 피해야 합니다. DNS 제공자가 CNAME 플래트닝(flattening)을 지원하지 않는다면 말이죠. 일부 제공자는 ANAME이나 ALIAS 같은 특별한 이름을 사용하며, 일부는 apex에서 CNAME을 자동으로 플래트닝합니다. 일반적으로 apex 도메인에는 A/AAAA 레코드를 설정하는 것을 권장해요.

DNS 챌린지

와일드카드 인증서가 필요하거나, 트래픽을 앱으로 보내기 전에 인증서를 생성하고 싶다면 DNS-01 챌린지를 사용하세요.

이를 위해서는 도메인에 _acme-challenge CNAME 레코드를 설정해야 해요. 필요한 레코드는 대시보드나 fly certs setup의 출력에 표시됩니다.

도메인 소유권 검증

다른 검증 방법을 사용할 수 없는 설정이라면 _fly-ownership TXT 레코드로 도메인 소유권을 검증하세요. 다음 경우에 유용해요.

  • 도메인이 직접 검증을 막는 CDN이나 프록시 뒤에 있는 경우
  • 커스텀 인증서를 가져오는 경우
  • IPv6 주소를 할당하거나 사용하고 싶지 않은 경우

필요한 레코드는 대시보드나 fly certs setup의 출력에 표시됩니다. 단일 TXT 레코드에 여러 값을 세미콜론으로 구분해 넣을 수 있어요.

인증서 검증

DNS를 구성한 후 Fly.io는 자동으로 도메인 소유권을 검증하고 인증서를 발급합니다. 이는 다음 방법 중 하나로 이루어져요.

  • TLS-ALPN 챌린지: Fly Proxy와의 TLS 핸드셰이크로 검증합니다. 선호되는 방법이며 직접 연결에서 자동으로 작동해요.
  • HTTP-01 챌린지: 도메인에서 특정 파일을 요청해 검증합니다. TLS-ALPN을 사용할 수 없을 때 자동으로 사용됩니다.
  • DNS-01 챌린지: 도메인 소유권을 검증하기 위해 DNS 레코드를 직접 추가합니다. 와일드카드 인증서에 필요하거나, 트래픽을 앱으로 보내기 전에 인증서를 생성하는 데 필요해요.

자체 인증서 사용

Fly.io가 관리하는 자동 Let's Encrypt 인증서 외에도 자체 TLS 인증서와 프라이빗 키를 업로드할 수 있어요. CLI를 사용해 PEM 형식으로 인증서와 프라이빗 키를 업로드합니다.

fly certs import example.com --fullchain fullchain.pem --private-key private-key.pem

앱 대시보드의 Certificates 아래에서도 인증서를 가져올 수 있어요.

커스텀 인증서를 업로드한 후에는 도메인 소유권이 검증될 때까지 pending_ownership 상태로 표시될 수 있습니다. 소유권은 앱을 가리키는 IPv6 DNS 레코드나 _fly-ownership TXT 레코드로 검증됩니다.

커스텀 인증서와 Fly 관리(Let's Encrypt) 인증서는 같은 호스트네임에 공존할 수 있어요. 둘 다 있으면 커스텀 인증서가 기본 인증서로 제공되고, Fly 관리 인증서가 자동 대체(fallback) 역할을 합니다.

기타 fly cert 명령

  • fly certs list - 앱과 연결된 인증서를 나열합니다.
  • fly certs check <hostname> - 주어진 호스트네임에 대한 도메인 검증과 DNS 구성을 확인하고 fly certs show와 같은 형식으로 결과를 반환합니다.
  • fly certs setup <hostname> - 기존 인증서에 대한 DNS 레코드 구성 지침을 보여줍니다.
  • fly certs remove <hostname> - 주어진 호스트네임에 대한 인증서를 앱에서 제거합니다. --custom으로 커스텀 인증서만 제거하거나 --acme로 ACME 발급만 중지할 수 있어요.

커스텀 도메인을 앱에 가르치기

애플리케이션 코드는 커스텀 도메인을 수용하고 그에 맞게 응답을 조정하는 방법을 알아야 해요. 사용자를 대신해 콘텐츠를 호스팅한다면, 보통 들어오는 호스트네임을 애플리케이션 데이터베이스의 특정 ID에 매핑하는 것을 의미합니다.

사용자가 요청할 때 브라우저는 Host 헤더를 보내므로 이를 사용해 애플리케이션 동작을 바꿀 수 있어요. Fly.io에서 앱 서버를 직접 실행한다면 Host 헤더의 내용을 가져와 요청을 식별하면 됩니다.

애플리케이션을 다른 제공자에서 실행한다면 nginx 같은 프록시 애플리케이션을 만들어 트래픽을 Fly.io로 라우팅해야 해요. 그러면 애플리케이션은 X-Forwarded-Host 헤더로 요청을 처리하는 방법을 결정할 수 있습니다.

지원되는 최상위 도메인

IANA 목록의 최상위 도메인을 지원합니다. 최상위 도메인 지원은 주기적으로만 업데이트하므로 새 최상위 도메인에 대한 지원이 추가되기까지 지연이 있을 수 있다는 점에 유의하세요.

인증서 생성 문제 해결

인증서 생성이나 검증이 멈추거나, 지연되거나, 실패하는 것 같아요

*Let's Encrypt™*는 Fly.io가 커스텀 도메인용 TLS 인증서를 발급하는 데 사용하는 무료, 자동, 오픈 인증 기관(CA)입니다. 하지만 Let's Encrypt는 공정한 사용을 보장하기 위해 일정 비율 제한을 부과해요. Fly.io에서 커스텀 도메인용 인증서를 생성하거나 검증할 때 문제가 발생한다면 이 비율 제한에 걸렸을 가능성이 있습니다.

적용되는 Let's Encrypt 비율 제한은 다음과 같아요.

  • 등록 도메인당 인증서: 주당 50개
  • 중복 인증서 제한: 주당 5개
  • 실패한 검증 제한: 호스트네임당 시간당 5회

인증서 갱신은 등록 도메인당 인증서 제한에 포함되지 않는다는 점에 유의하세요.

Fly.io에서 커스텀 도메인용 인증서를 추가하거나 검증할 때 문제가 발생하면 다음 방법으로 문제를 해결할 수 있어요.

  • Let's Debug 사용: Let's Encrypt에서 인증서를 발급하지 못하는 이유를 알아내는 데 도움을 주는 진단 도구/웹사이트. 일련의 테스트로 기본 DNS 설정 문제, 네임서버 문제, 비율 제한, 네트워킹 문제, CA 정책 문제, 흔한 웹사이트 설정 오류 등 다양한 문제를 식별할 수 있어요.
  • 기다렸다가 다시 시도: 비율 제한에 걸렸다면 비율 제한 기간이 지날 때까지 기다린 후에야 인증서를 다시 성공적으로 만들거나 검증할 수 있어요. 재설정할 방법은 없습니다.

비율 제한을 피하는 가장 좋은 방법은 테스트와 개발에 스테이징 환경과 도메인을 사용하고, 인증서 발급을 제한 안에 들어오도록 신중히 계획하는 거예요. 충돌하는 레코드 없이 DNS 레코드가 올바르게 구성되어 있는지 확인해 실패한 검증을 피하세요.

Fly.io 위에 플랫폼을 만들고 있고 사용자가 짧은 시간 안에 같은 리소스를 삭제했다가 다시 만드는 일이 잦을 것으로 예상한다면, Fly.io 리소스를 일정 기간 유지하는 "소프트 삭제" 로직을 플랫폼에 구현해 인증서를 자주 다시 만들 필요가 없게 하는 것을 고려해 보세요.

Cloudflare를 사용하는데 Fly.io TLS 인증서 발급이나 검증에 문제가 있는 것 같아요

Cloudflare의 프록시 기능(주황색 구름)을 사용 중이라면 _fly-ownership TXT 레코드를 추가해 도메인 소유권을 검증하세요. 소유권이 검증되면 Fly.io는 Cloudflare 프록시를 통해 HTTP-01 챌린지로 인증서를 발급할 수 있어요.

이것이 작동하려면:

  1. 도메인 소유권 검증: 인증서 세부정보에 표시된 값으로 _fly-ownership TXT 레코드를 추가합니다. 도메인 소유권 검증을 참조하세요.
  2. SSL 모드 설정: Cloudflare에서 "Full" 또는 "Full (Strict)" SSL 모드를 사용합니다. "Flexible" 모드는 리디렉션 루프를 유발할 수 있어요.

Cloudflare 구성에 따라 HTTP-01 챌린지가 차단되어 생성이 여전히 실패할 수 있습니다. 이런 경우 Cloudflare Origin Certificate를 가져오고 같은 _fly-ownership TXT 레코드로 소유권을 검증하면 ACME 인증서 생성을 완전히 우회할 수 있어요.

관련 자료

  • 네트워킹 개요 Fly.io가 라우팅, DNS, IP, 인증서를 처리하는 방법을 더 넓게 살펴봅니다.
  • 인증서 API 레퍼런스 Machines API로 인증서 프로비저닝과 도메인 검증을 자동화하세요.
  • Fly Proxy의 TLS 종료 — Fly.io가 앱의 HTTPS를 처리하고 뒷단에서 TLS 인증서를 자동으로 관리하는 방법.
  • Cloudflare 이해하기 Fly.io를 Cloudflare 뒤에 둘 때 일어나는 일과 흔한 함정을 피하는 방법.

더 알아보기 (Learn more)