커스텀 도메인 매핑

베타

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

Knative serving 서비스에 액세스하는 데 사용할 커스텀 도메인을 구성합니다. 하나 이상의 커스텀 도메인을 개별 서비스에 매핑하거나 단일 도메인을 모든 서비스가 사용하는 클러스터에 매핑할 수 있습니다. 커스텀 도메인 매핑은 your-domain.com과 같은 기본 도메인이거나 your-subdomain.your-domain.com과 같은 하위 도메인일 수 있습니다.

기본적으로 Knative serving 클러스터에 배포하는 서비스는 nip.io 기본 도메인으로 설정됩니다. 이렇게 하면 다음과 같은 URL에서 서비스를 즉시 테스트할 수 있습니다.

http://{SERVICE_NAME}.{NAMESPACE}.kuberun.{EXTERNAL_IP}.nip.io

테스트 도메인에 대해 자세히 알아보세요.

시작하기 전에

• 서비스에 매핑할 도메인을 보유하고 있거나 구매해야 합니다. 도메인 이름 등록기관을 사용할 수 있지만 Cloud Domains를 사용할 경우 도메인이 자동으로 Knative serving에 확인되므로 도메인 확인 절차를 진행할 필요가 없습니다.

  Cloud Domains에 도메인을 등록하려면 Knative serving 콘솔 내의 Cloud Domains에 도메인 등록을 참조하세요.

• 최소한 Kubernetes Engine 개발자 Identity and Access Management 역할 또는 이에 상응하는 권한이 있어야 합니다.

• 커스텀 도메인 매핑에 HTTPS를 사용 설정하려면 관리형 TLS 인증서를 설정하거나 자체 인증서를 구성해야 합니다.

• 커스텀 도메인을 비공개 내부 네트워크의 클러스터 또는 서비스에 매핑하려면 관리형 TLS 인증서를 사용 중지해야 합니다.

커스텀 도메인 매핑

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

일반적으로 커스텀 도메인을 구성하려면 다음 안내를 따르세요.

1. 선택사항: 부하 분산기의 IP 주소를 예약합니다.
2. Knative serving의 커스텀 도메인에 서비스 또는 클러스터를 매핑합니다.
3. 도메인 등록기관에서 DNS 레코드를 업데이트합니다.

부하 분산기 IP 주소 예약

Knative serving이 설치되면 Istio 인그레스 컨트롤러는 사용 가능한 IP 주소로 부하 분산기를 만듭니다.

GKE 클러스터에 따라 Istio 인그레스 컨트롤러용 부하 분산기의 IP 주소를 예약해야 할 수 있습니다.

Google Cloud 외부

IP 주소가 관리되는 방법과 부하 분산기의 IP 주소가 고정인지 확인하려면 GKE 클러스터를 실행하는 환경의 문서를 참조하세요. GKE 클러스터의 구성 페이지도 참조하세요. 예를 들어 Google Distributed Cloud에 부하 분산을 구성한 방법에 따라 이미 해당 IP 주소를 예약했을 수 있습니다.

Google Cloud

인그레스 서비스가 삭제된 경우 동일하게 유지되도록 부하 분산기의 외부 IP 주소를 예약해야 합니다. 클러스터 구성에 따라 IP 주소는 외부에서 사용 가능하거나 내부 전용입니다(예: 비공개 클러스터).

Google Cloud의 내부 부하 분산기

내부 부하 분산기의 IP 주소를 예약하는 방법에 대한 자세한 내용은 다음 페이지를 참조하세요. 고정 내부 IP 주소 예약

Google Cloud의 외부 부하 분산기

외부 부하 분산기의 IP 주소를 예약하는 방법은 다음과 같습니다.

1. 부하 분산기의 IP 주소를 가져옵니다.

   콘솔

   Google Cloud Console에서 부하 분산기의 외부 IP 주소를 가져오려면 다음 단계를 따르세요.

   1. Google Cloud 콘솔의 GKE 페이지로 이동합니다.
      GKE로 이동
   2. 서비스 및 인그레스를 클릭합니다.
   3. 클러스터의 Istio 인그레스 서비스를 식별합니다. 서비스의 유형은 외부 부하 분산기이고 이름은 istio-ingressgateway입니다.
   4. 클러스터의 Istio 인그레스 서비스를 찾았으면 엔드포인트를 복사합니다. 이는 포트 번호가 없는 IP 주소입니다. 예를 들어 00.000.000.000:11이 엔드포인트로 표시되지만 00.000.000.000만 복사하면 됩니다.

   kubectl

   부하 분산기의 외부 IP를 가져오려면 다음 명령어를 실행합니다.

   kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE

   ASM-INGRESS-NAMESPACE를 Cloud Service Mesh 인그레스가 있는 네임스페이스로 바꿉니다. 기본 구성을 사용하여 Cloud Service Mesh를 설치한 경우 istio-system을 지정합니다.

   결과 출력은 다음과 유사합니다.

   NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
   istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

   여기서 EXTERNAL-IP 값은 부하 분산기의 외부 IP 주소입니다.

2. IP 주소를 고정 IP로 예약합니다.

   gcloud compute addresses create ADDRESS-NAME --addresses EXTERNAL-IP --region REGION

   다음과 같이 바꿉니다.

   • ADDRESS-NAME을 정적 IP로 지정할 이름으로 바꿉니다.
   • EXTERNAL-IP를 이전 단계에서 가져온 부하 분산기의 외부 IP 주소로 바꿉니다.
   • REGION을 클러스터가 있는 리전으로 바꿉니다.

부하 분산기의 IP 주소를 가져온 후 이를 사용하여 커스텀 도메인을 매핑할 수 있습니다.

• 서비스에 매핑
• 클러스터에 매핑

서비스 매핑

다음 방법 중 하나를 선택하여 커스텀 도메인을 Knative serving 서비스에 매핑합니다. 각 개별 서비스는 여러 도메인에 매핑될 수 있습니다.

콘솔

1. Google Cloud 콘솔에서 도메인 매핑 페이지를 엽니다.

   도메인 매핑으로 이동

   디스플레이 창 크기가 너무 작을 경우 커스텀 도메인 매핑 버튼이 표시되지 않습니다. 이 경우 페이지의 오른쪽에 있는 세로 점 3개 아이콘을 클릭해야 합니다.

2. 매핑 추가를 클릭하고 서비스 도메인 매핑 추가를 선택하여 도메인을 개별 서비스에 매핑합니다. 여러 도메인을 각 서비스에 매핑할 수 있습니다.

3. 매핑 추가 양식의 드롭다운 목록에서 커스텀 도메인을 매핑할 서비스를 선택합니다.

4. 도메인 이름을 입력합니다. 예를 들면 your-domain.com 또는 subdomain.your-domain.com입니다. 도메인 요구사항:

   • 기본 경로 매핑은 지원되지 않습니다. 기본 경로는 도메인 이름 뒤에 오는 URL 경로 이름을 나타냅니다. 예를 들어 users는 your-domain.com/users의 기본 경로입니다. Knative serving을 사용하면 특정한 기본 경로가 아닌 /에 도메인을 매핑할 수 있습니다. 따라서 모든 경로 라우팅은 서비스 컨테이너 내부의 라우터를 사용하거나 Firebase 호스팅을 사용하여 처리해야 합니다.
   • 도메인을 서비스의 URL과 일치하는 하위 도메인에 매핑할 수 없습니다. 서비스의 URL은 http://{service}.{namespace}.{your-domain.com}와 같이 정의됩니다. 따라서 test.default.your-domain.com에 서비스가 있는 경우 동일한 하위 도메인 test.default.your-domain.com에 대한 도메인 매핑을 만들어서는 안 됩니다.

5. 계속을 클릭합니다.

6. 마지막 단계에 표시된 DNS 레코드를 사용하여 도메인 등록기관 웹사이트에서 DNS 레코드를 업데이트합니다. 도메인 매핑의 '...'작업 메뉴에서 DNS 레코드를 클릭하면 언제든지 레코드를 표시할 수 있습니다.

7. 완료를 클릭합니다.

gcloud

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

   gcloud run domain-mappings create --service SERVICE --domain DOMAIN

   다음과 같이 바꿉니다.

   • SERVICE를 서비스 이름으로 바꿉니다.
   • DOMAIN을 커스텀 도메인으로 바꿉니다. 예를 들면 your-domain.com 또는 subdomain.your-domain.com입니다. 도메인 요구사항:
     • 기본 경로 매핑은 지원되지 않습니다. 기본 경로는 도메인 이름 뒤에 오는 URL 경로 이름을 나타냅니다. 예를 들어 users는 your-domain.com/users의 기본 경로입니다. Knative serving을 사용하면 특정한 기본 경로가 아닌 /에 도메인을 매핑할 수 있습니다. 따라서 모든 경로 라우팅은 서비스 컨테이너 내부의 라우터를 사용하거나 Firebase 호스팅을 사용하여 처리해야 합니다.
     • 도메인을 서비스의 URL과 일치하는 하위 도메인에 매핑할 수 없습니다. 서비스의 URL은 http://{service}.{namespace}.{your-domain.com}와 같이 정의됩니다. 따라서 test.default.your-domain.com에 서비스가 있는 경우 동일한 하위 도메인 test.default.your-domain.com에 대한 도메인 매핑을 만들어서는 안 됩니다.

이제 커스텀 도메인이 Knative serving에 매핑되었으므로 도메인 등록기관에서 DNS 레코드를 추가해야 합니다.

클러스터 매핑

커스텀 도메인을 클러스터에 매핑하려면 다음 방법 중 하나를 선택합니다.

콘솔

1. Google Cloud 콘솔에서 도메인 매핑 페이지를 엽니다.

   도메인 매핑으로 이동

   디스플레이 창 크기가 너무 작을 경우 커스텀 도메인 매핑 버튼이 표시되지 않습니다. 이 경우 페이지의 오른쪽에 있는 세로 점 3개 아이콘을 클릭해야 합니다.

2. 매핑 추가를 클릭하고 기본 도메인 추가를 선택하여 도메인을 클러스터의 모든 서비스에 매핑합니다. 기본적으로 배포하는 새 서비스는 매핑된 도메인을 사용합니다.

3. 체크박스를 클릭하여 클러스터의 모든 기존 서비스에 새 도메인 매핑을 적용합니다.

4. 매핑 추가 양식의 드롭다운 목록에서 커스텀 도메인을 매핑할 클러스터를 선택합니다.

5. 도메인 이름을 입력합니다. 예를 들면 your-domain.com 또는 subdomain.your-domain.com입니다. 도메인 요구사항:

   • 기본 경로 매핑은 지원되지 않습니다. 기본 경로는 도메인 이름 뒤에 오는 URL 경로 이름을 나타냅니다. 예를 들어 users는 your-domain.com/users의 기본 경로입니다. Knative serving을 사용하면 특정한 기본 경로가 아닌 /에 도메인을 매핑할 수 있습니다. 따라서 모든 경로 라우팅은 서비스 컨테이너 내부의 라우터를 사용하거나 Firebase 호스팅을 사용하여 처리해야 합니다.
   • 도메인을 서비스의 URL과 일치하는 하위 도메인에 매핑할 수 없습니다. 서비스의 URL은 http://{service}.{namespace}.{your-domain.com}와 같이 정의됩니다. 따라서 test.default.your-domain.com에 서비스가 있는 경우 동일한 하위 도메인 test.default.your-domain.com에 대한 도메인 매핑을 만들어서는 안 됩니다.

6. 계속을 클릭합니다.

7. 마지막 단계에 표시된 DNS 레코드를 사용하여 도메인 등록기관 웹사이트에서 DNS 레코드를 업데이트합니다. 도메인 매핑의 '...'작업 메뉴에서 DNS 레코드를 클릭하면 언제든지 레코드를 표시할 수 있습니다.

8. 완료를 클릭합니다.

kubectl

1. 다음 명령어를 실행하여 config-domain ConfigMap에서 기존 기본 도메인을 삭제하고 커스텀 도메인으로 바꿉니다.

   kubectl patch configmap config-domain --namespace knative-serving --patch \
   '{"data": {"nip.io": null, "DOMAIN": ""}}'

   DOMAIN을 커스텀 도메인으로 바꿉니다. 예를 들면 your-domain.com 또는 subdomain.your-domain.com입니다. 도메인 요구사항:

   • 기본 경로 매핑은 지원되지 않습니다. 기본 경로는 도메인 이름 뒤에 오는 URL 경로 이름을 나타냅니다. 예를 들어 users는 your-domain.com/users의 기본 경로입니다. Knative serving을 사용하면 특정한 기본 경로가 아닌 /에 도메인을 매핑할 수 있습니다. 따라서 모든 경로 라우팅은 서비스 컨테이너 내부의 라우터를 사용하거나 Firebase 호스팅을 사용하여 처리해야 합니다.
   • 도메인을 서비스의 URL과 일치하는 하위 도메인에 매핑할 수 없습니다. 서비스의 URL은 http://{service}.{namespace}.{your-domain.com}와 같이 정의됩니다. 따라서 test.default.your-domain.com에 서비스가 있는 경우 동일한 하위 도메인 test.default.your-domain.com에 대한 도메인 매핑을 만들어서는 안 됩니다.

이제 커스텀 도메인이 Knative serving에 매핑되었으므로 도메인 등록기관에서 DNS 레코드를 추가해야 합니다.

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

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

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

참고: 일부 서드 파티 CDN 제공업체는 의도치 않게 유효성 검사 요청을 가로채 Knative serving 서비스에 도달하지 못하게 하므로 도메인 매핑이 실패하거나 인증서 갱신이 실패할 수 있습니다. 예를 들어 Cloudflare CDN을 사용하는 경우 SSL/TLS 탭의 '에지 인증서' 탭에서 '항상 https 사용' 옵션을 사용 중지해야 합니다.

1. 다음을 사용하여 도메인 매핑에 대한 DNS 레코드 정보를 검색합니다.

   콘솔

   1. Knative serving 도메인 매핑 페이지로 이동합니다.

      도메인 매핑으로 이동

   2. 서비스의 오른쪽에 있는 세로 3개 점 아이콘을 클릭한 다음 DNS 레코드를 클릭하여 모든 DNS 레코드를 표시합니다.

   gcloud

   gcloud run domain-mappings describe --domain DOMAIN

   DOMAIN을 커스텀 도메인으로 바꿉니다. 예를 들면 your-domain.com 또는 subdomain.your-domain.com입니다.

   resourceRecords 제목 아래에 반환된 레코드가 모두 필요합니다.

2. 본인 계정으로 도메인 등록기관에 로그인하고 DNS 구성 페이지를 엽니다.

3. 도메인 구성 페이지의 호스트 레코드 섹션을 찾은 다음 도메인을 Knative serving 서비스에 매핑할 때 받은 각 리소스 레코드를 추가합니다.

4. 위의 각 DNS 레코드를 DNS 제공업체의 계정에 추가하려면 다음을 수행하세요.

   • 이전 단계에서 DNS 레코드에 반환된 유형을 선택합니다(A, AAAA 또는 CNAME).
   • www 이름을 사용하여 www.your-domain.com을 매핑합니다.
   • @ 이름을 사용하여 your-domain.com을 매핑합니다.
   • 와일드 카드 *를 사용하여 *.your-domain.com에 매핑합니다.

5. 도메인 계정의 DNS 구성 페이지에 변경사항을 저장합니다. 대부분의 경우 변경사항이 적용되는 데 몇 분 정도 걸리지만 도메인에 대한 이전 DNS 레코드의 등록기관 및 TTL(수명)에 따라 몇 시간이 걸릴 수도 있습니다. 이 온라인 dig 버전과 같이 dig 도구를 사용하여 DNS 레코드가 성공적으로 업데이트되었는지 확인할 수 있습니다.

6. 새 URL(예: https://www.your-domain.com)을 통해 서비스를 탐색하여 성공 여부를 테스트합니다. 관리형 SSL/TLS 인증서를 발급하는 데 몇 분 정도 걸릴 수 있습니다.

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

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

참고: 확인된 도메인 소유자는 확인 후 다른 프로젝트의 기존 도메인 매핑을 재정의할 수 있습니다.

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

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

   https://search.google.com/search-console/welcome

2. 속성에서 사용자 또는 서비스 계정을 추가할 도메인을 클릭합니다.

3. 확인된 소유자 목록까지 아래로 스크롤하여 소유자 추가를 클릭한 다음 Google 계정 이메일 주소 또는 서비스 계정 ID를 입력합니다.

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

   서비스 계정 페이지로 이동

Knative serving 콘솔 내에서 Cloud Domains에 도메인 등록

미리보기 — Registering a domain with Cloud Domains within the Knative serving console

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

Knative serving 콘솔 내에서 Cloud Domains에 도메인을 등록하려면 다음 안내를 따르세요.

1. Knative serving 도메인 매핑 페이지로 이동합니다.

   도메인 매핑으로 이동

2. 도메인 등록을 클릭합니다.

3. 도메인 등록의 안내에 따라 등록 프로세스를 완료합니다.

4. 이 페이지의 앞부분에 있는 도메인을 Knative serving에 매핑한 다음 도메인 등록기관에서 DNS 레코드를 추가합니다.

문제 해결

커스텀 도메인 및 관리형 TLS 문제 해결에서 일반적인 문제를 확인합니다.