커스텀 도메인 매핑

사용자는 Cloud Run이 배포된 서비스에 제공하는 기본 주소가 아닌 커스텀 도메인을 설정할 수 있습니다.

Cloud Run 서비스의 커스텀 도메인을 설정하는 방법에는 다음과 같은 방법이 있습니다.

전역 외부 애플리케이션 부하 분산기 사용(권장)
Firebase 호스팅용 Cloud Run 통합 기능 사용(Firebase 호스팅을 사용하는 가장 쉬운 방법)
수동 구성으로 Firebase 호스팅 사용(통합 기능을 사용하지 않으려는 경우)
Cloud Run 도메인 매핑(제한된 가용성 및 미리보기) 사용

여러 커스텀 도메인을 동일한 Cloud Run 서비스에 매핑할 수 있습니다.

시작하기 전에

사용할 도메인이 없으면 새 도메인을 구입합니다. 모든 도메인 이름 등록기관을 사용할 수 있습니다.

전역 외부 애플리케이션 부하 분산기를 사용하여 커스텀 도메인 매핑

이 옵션을 사용하면 Cloud Run 서비스 앞에 전역 외부 애플리케이션 부하 분산기를 추가하고 부하 분산기 수준에서 커스텀 도메인을 구성합니다.

전역 외부 애플리케이션 부하 분산기를 사용할 때 한 가지 이점은 커스텀 도메인 설정에 대해 많은 제어 기능을 제공한다는 것입니다. 예를 들어 자체 TLS 인증서를 사용하거나 특정 URL 경로를 Cloud Run 서비스로 라우팅할 수 있습니다. 또한 캐싱을 위해 Cloud CDN을 구성하고 추가 보안을 위해 Google Cloud Armor를 구성할 수 있습니다.

단일 부하 분산기(예: <service>.example.com)의 커스텀 도메인 URL 패턴에서 URL 마스크를 사용하여 동적 호스트 이름 또는 경로에 여러 서비스를 매핑할 수도 있습니다.

Cloud Run 통합 사용

현재 전역 외부 애플리케이션 부하 분산기를 사용하지 않는 경우 Cloud Run 통합 기능을 사용하여 Cloud Run 서비스의 부하 분산기를 빠르게 설정할 수 있습니다. 전역 외부 애플리케이션 부하 분산기를 사용하는 Cloud Run의 커스텀 도메인에 대한 통합 페이지를 참조하세요.

전역 외부 애플리케이션 부하 분산기 직접 사용

이미 전역 외부 애플리케이션 부하 분산기를 사용 중인 경우 Cloud Run으로 전역 외부 애플리케이션 부하 분산기 설정에 대한 문서를 참조하세요. 통합 기능을 사용하면 CDN 사용 설정 등의 몇 가지 기존 부하 분산기 구성을 덮어쓸 수 있습니다.

Firebase 호스팅을 사용하여 커스텀 도메인 매핑

이 옵션을 사용할 때는 Cloud Run 서비스 앞에 Firebase 호스팅을 구성하고 구성 도메인을 Firebase 호스팅에 연결합니다.

Firebase 호스팅을 사용하면 가격을 낮출 수 있고 Cloud Run 서비스에서 제공되는 동적 콘텐츠와 함께 정적 콘텐츠를 선택적으로 호스팅 및 제공할 수 있습니다.

Cloud Run 통합 사용

Firebase 호스팅을 사용하여 커스텀 도메인을 매핑하는 가장 쉽고 권장되는 방법은 Firebase 호스팅용 Cloud Run 통합 기능을 사용하는 것입니다.

`firebase.json` 사용

Firebase 호스팅 통합 기능을 사용하지 않으려면 수동 방식을 사용하여 Firebase 호스팅을 구성할 수 있습니다.

Firebase 호스팅을 사용하여 커스텀 도메인을 수동으로 매핑하려면 다음 안내를 따르세요.

Google Cloud 프로젝트에 Firebase 추가
Firebase CLI 설치
서비스의 소스 코드와 다른 폴더에서 다음 콘텐츠가 포함된 firebase.json 파일을 만듭니다.
```
  {
    "hosting": {
      "rewrites": [{
        "source": "**",
        "run": {
          "serviceId": "SERVICE_NAME",
          "region": "REGION"
        }
      }]
    }
  }
```
SERVICE_NAME 및 REGION을 Cloud Run 서비스의 이름 및 리전으로 바꿉니다.

Firebase 호스팅 구성을 배포합니다.

firebase deploy --only hosting --project PROJECT_ID

Firebase 호스팅에 커스텀 도메인 연결

Firebase 호스팅 및 Cloud Run에 대해 자세히 알아보세요.

Cloud Run 도메인 매핑을 사용하여 커스텀 도메인 매핑(제한된 가용성 및 미리보기)

Cloud Run 도메인 매핑 제한사항

Cloud Run 도메인 매핑에는 다음 고려사항이 적용됩니다.

Cloud Run 도메인 매핑은 미리보기 출시 단계에 있습니다. 지연 시간 문제로 인해 프로덕션에 즉시 사용할 수 없으며 일반 안정화 버전으로 지원되지 않습니다. 현재 이 옵션은 프로덕션 서비스에 권장되지 않습니다.
서비스를 커스텀 도메인에 매핑하면 HTTPS 연결에 필요한 Google 관리형 인증서가 자동으로 발급되고 갱신됩니다.
일반적으로 SSL 인증서를 프로비저닝하는 데 약 15분 정도 걸리지만 최대 24시간까지 걸릴 수도 있습니다.
TLS 1.0 및 1.1은 사용 중지할 수 없습니다. 이것이 문제가 될 경우 Firebase 호스팅 또는 Cloud Load Balancing을 사용하여 TLS 1.2 전용 트래픽을 사용 설정할 수 있습니다.
자체 관리형 인증서를 업로드하고 사용할 수 없습니다.
Cloud Run 도메인 매핑은 64자로 제한됩니다.
도메인 매핑은 다음 리전에서 사용할 수 있습니다.
- asia-east1
- asia-northeast1
- asia-southeast1
- europe-north1
- europe-west1
- europe-west4
- us-central1
- us-east1
- us-east4
- us-west1
다른 리전의 커스텀 도메인을 매핑하려면 다른 매핑 옵션 중 하나를 사용해야 합니다.
Cloud Run 도메인 매핑을 사용하면 커스텀 도메인을 서비스에 매핑한 후 DNS 레코드를 업데이트합니다.
example.com과 같은 도메인 또는 subdomain.example.com과 같은 하위 도메인을 매핑할 수 있습니다.
도메인을 /users와 같은 특정 URL 경로에 매핑하지 않고 /에만 매핑할 수 있습니다.
이 기능에 와일드카드 인증서를 사용할 수 없습니다.

커스텀 도메인을 서비스에 매핑

Google Cloud 콘솔, gcloud CLI 또는 Terraform을 사용하여 커스텀 도메인을 서비스에 매핑할 수 있습니다.

콘솔

Google Cloud Console에서 도메인 매핑 페이지를 엽니다.
도메인 매핑 페이지
매핑 추가를 클릭합니다.

디스플레이 창 크기가 너무 작을 경우 매핑 추가 버튼이 표시되지 않습니다. 이 경우 페이지의 오른쪽에 있는 세로 점 3개 아이콘을 클릭해야 합니다.
드롭다운 목록에서 커스텀 도메인을 매핑할 서비스를 선택합니다.
선택한 서비스에 설정된 리전에 따라 커스텀 도메인을 추가하는 데 사용할 수 있는 옵션이 양식에 표시됩니다.
- Cloud Run 통합을 사용한 Firebase 호스팅
- 커스텀 도메인 - Cloud Run 통합을 사용하는 Google Cloud Load Balancing
- Cloud Run 도메인 매핑
Cloud Run 도메인 매핑을 선택합니다.
매핑 추가 양식에서 새 도메인 확인을 선택합니다.
Google에서 도메인을 구입하지 않았으면 확인할 기본 도메인 필드에서 도메인을 사용하기 전에 도메인 소유권을 확인해야 합니다.

subdomain.example.com 또는 subdomain1.subdomain2.example.com을 매핑하려면 example.com의 소유권을 확인해야 합니다. 도메인 소유권 확인에 대한 자세한 내용은 Search Console 도움말을 참조하세요.
계속을 클릭합니다.
도메인 확인이 완료되면 확인 계속 및 닫기를 클릭합니다.
마지막 단계에 표시된 DNS 레코드를 사용하여 도메인 등록기관 웹사이트에서 DNS 레코드를 업데이트합니다. 도메인 매핑의 '...'작업 메뉴에서 DNS 레코드를 클릭하면 언제든지 레코드를 표시할 수 있습니다.
완료를 클릭합니다.

명령줄

Google에서 커스텀 도메인을 구입하지 않은 경우 Google Cloud 프로젝트에서 해당 도메인을 처음 사용할 때 도메인 소유권을 확인해야 합니다. 다음 명령어를 사용하여 사용할 커스텀 도메인이 확인되었는지 여부를 확인할 수 있습니다.
```
gcloud domains list-user-verified
```
도메인 소유권을 확인해야 하는 경우 Search Console 확인 페이지를 엽니다.
```
gcloud domains verify BASE-DOMAIN
```
여기서 BASE-DOMAIN은 확인할 기본 도메인입니다. 예를 들어 subdomain.example.com을 매핑하려면 example.com의 소유권을 확인해야 합니다.

Search Console에서 도메인 소유권 확인을 완료합니다. 자세한 내용은 Search Console 도움말을 참조하세요.
서비스를 커스텀 도메인에 매핑합니다.
```
gcloud beta run domain-mappings create --service SERVICE --domain DOMAIN
```
- SERVICE를 서비스 이름으로 바꿉니다.
- DOMAIN을 커스텀 도메인으로 바꿉니다(예: example.com 또는 subdomain.example.com).

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요.

Cloud Run 서비스를 만들려면 다음을 기존 main.tf 파일에 추가합니다.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloud-run-srv"
  location = "us-central1"
  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }
}

name 값을 자체 서비스 이름으로 바꿉니다.

Cloud Run 서비스를 커스텀 도메인에 매핑합니다.

data "google_project" "project" {}

resource "google_cloud_run_domain_mapping" "default" {
  name     = "verified-domain.com"
  location = google_cloud_run_v2_service.default.location
  metadata {
    namespace = data.google_project.project.project_id
  }
  spec {
    route_name = google_cloud_run_v2_service.default.name
  }
}

verified-domain.com을 확인된 커스텀 도메인(예: example.com 또는 subdomain.example.com)으로 바꿉니다.

도메인 등록기관에서 DNS 레코드 추가

서비스를 Cloud Run의 커스텀 도메인에 매핑했으면 도메인 등록기관의 DNS 레코드를 업데이트해야 합니다. Cloud Run은 편의를 위해 입력해야 하는 DNS 레코드를 생성 및 표시합니다. 매핑을 적용하려면 도메인 등록기관의 Cloud Run 서비스를 가리키는 이러한 레코드를 추가해야 합니다.

DNS 제공업체로 Cloud DNS를 사용하는 경우 레코드 추가를 참조하세요.

다음을 사용하여 도메인 매핑에 대한 DNS 레코드 정보를 검색합니다.
콘솔
1. Cloud Run 도메인 매핑 페이지로 이동합니다.
  도메인 매핑 페이지
2. 서비스의 오른쪽에 있는 세로 3개 점 아이콘을 클릭한 다음 DNS 레코드를 클릭하여 모든 DNS 레코드를 표시합니다.
명령줄
```
gcloud beta run domain-mappings describe --domain [DOMAIN]
```
[DOMAIN]을 커스텀 도메인으로 바꿉니다(예: example.com 또는 subdomain.example.com).

resourceRecords 제목 아래에 반환된 레코드가 모두 필요합니다.
본인 계정으로 도메인 등록기관에 로그인하고 DNS 구성 페이지를 엽니다.
도메인 구성 페이지의 호스트 레코드 섹션을 찾은 다음 도메인을 Cloud Run 서비스에 매핑할 때 받은 각 리소스 레코드를 추가합니다.
위의 각 DNS 레코드를 DNS 제공업체의 계정에 추가하려면 다음을 수행하세요.
- 이전 단계에서 DNS 레코드에 반환된 유형을 선택합니다(A, AAAA 또는 CNAME).
- www 이름을 사용하여 www.example.com을 매핑합니다.
- @ 이름을 사용하여 example.com을 매핑합니다.
도메인 계정의 DNS 구성 페이지에 변경사항을 저장합니다. 대부분의 경우 변경사항이 적용되는 데 몇 분 정도 걸리지만 도메인에 대한 이전 DNS 레코드의 등록기관 및 TTL(수명)에 따라 몇 시간이 걸릴 수도 있습니다. 이 온라인 dig 버전과 같이 dig 도구를 사용하여 DNS 레코드가 성공적으로 업데이트되었는지 확인할 수 있습니다.
새 URL(예: https://www.example.com)을 통해 서비스를 탐색하여 성공 여부를 테스트합니다. 관리형 SSL 인증서를 발급하는 데 몇 분 정도 걸릴 수 있습니다.

다른 사용자 또는 서비스 계정에 확인된 도메인 소유자 추가

사용자가 도메인을 확인하면 해당 도메인은 해당 사용자의 계정으로만 확인됩니다. 즉, 해당 사용자만 해당 도메인을 사용하는 도메인 매핑을 추가할 수 있습니다. 따라서 다른 사용자가 해당 도메인을 사용하는 매핑을 추가할 수 있도록 설정하려면 인증된 소유자로 추가해야 합니다.

도메인의 확인된 소유자를 다른 사용자나 서비스 계정에 추가해야 하는 경우 Search Console 페이지를 통해 권한을 추가할 수 있습니다.

웹브라우저에서 다음 주소로 이동합니다.

https://search.google.com/search-console/welcome
속성에서 사용자 또는 서비스 계정을 추가할 도메인을 클릭합니다.
확인된 소유자 목록까지 아래로 스크롤하고 소유자 추가를 클릭한 다음 Google 계정 이메일 주소 또는 서비스 계정 ID를 입력합니다.

서비스 계정 목록을 보려면 Google Cloud 콘솔에서 서비스 계정 페이지를 엽니다.

서비스 계정 페이지로 이동

Cloud Run 도메인 매핑 삭제

Google Cloud Console 또는 gcloud 명령줄 도구를 사용하여 도메인 매핑을 삭제할 수 있습니다.

콘솔

Google Cloud Console에서 도메인 매핑 페이지를 엽니다.
도메인 매핑 페이지
도메인 매핑 페이지에서 삭제하려는 도메인 매핑을 선택하고 삭제를 클릭합니다.

명령줄

도메인 매핑을 삭제합니다.
```
gcloud beta run domain-mappings delete --domain DOMAIN
```
- DOMAIN을 커스텀 도메인으로 바꿉니다(예: example.com 또는 subdomain.example.com).

인증된 서비스에 커스텀 도메인 사용

인증된 서비스는 IAM으로 보호됩니다. 이러한 Cloud Run 서비스에는 사용자 인증 정보 생성 시 요청의 의도된 수신자(대상)를 선언하는 클라이언트 인증이 필요합니다.

대상은 일반적으로 타겟 서비스의 전체 URL이며, 기본적으로 Cloud Run 서비스의 경우 run.app으로 끝나는 생성 URL입니다. 그러나 커스텀 도메인을 사용하는 경우 자동으로 생성된 run.app URL을 대상으로 사용하지 않아야 합니다. 대신 커스텀 도메인이 유효한 인증 대상으로 수락되도록 커스텀 대상을 위한 서비스를 구성합니다.

다음 단계

Terraform과 함께 전역 외부 애플리케이션 부하 분산기를 사용하여 Cloud Run용 커스텀 도메인을 설정하려면 이 샘플 코드를 살펴보세요.

커스텀 도메인 매핑

시작하기 전에

전역 외부 애플리케이션 부하 분산기를 사용하여 커스텀 도메인 매핑

Cloud Run 통합 사용

전역 외부 애플리케이션 부하 분산기 직접 사용

Firebase 호스팅을 사용하여 커스텀 도메인 매핑

Cloud Run 통합 사용

firebase.json 사용

Cloud Run 도메인 매핑을 사용하여 커스텀 도메인 매핑(제한된 가용성 및 미리보기)

Cloud Run 도메인 매핑 제한사항

커스텀 도메인을 서비스에 매핑

콘솔

명령줄

Terraform

도메인 등록기관에서 DNS 레코드 추가

콘솔

명령줄

다른 사용자 또는 서비스 계정에 확인된 도메인 소유자 추가

Cloud Run 도메인 매핑 삭제

콘솔

명령줄

인증된 서비스에 커스텀 도메인 사용

다음 단계

`firebase.json` 사용