カスタム ドメインのマッピング

ベータ版

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

Knative serving サービスへのアクセスに使用するカスタム ドメインを構成します。1 つ以上のカスタム ドメインを個々のサービスにマッピングすることも、すべてのサービスが使用するクラスタに 1 つのドメインをマッピングすることもできます。カスタム ドメイン マッピングは、ベースドメイン（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 コンソールかコマンドライン ツールを使用してマッピングできます。

一般に、カスタム ドメインを構成するには:

1. 省略可: ロードバランサの IP アドレスを予約します。
2. Knative serving でカスタム ドメインにサービスまたはクラスタをマッピングします。
3. ドメイン登録事業者にある DNS レコードを更新します。

ロードバランサの IP アドレスを予約する

Knative serving をインストールすると、Istio Ingress コントローラによって使用可能な IP アドレスを持つロードバランサが作成されます。

GKE クラスタによっては、Istio Ingress コントローラに対するロードバランサの IP アドレスを予約する必要があります。

Google Cloud 以外

GKE クラスタを実行する環境のドキュメントを参照して、IP アドレスの管理方法とロードバランサの IP アドレスが静的であるかどうかを判断してください。GKE クラスタの構成ページもご覧ください。たとえば、Google Distributed Cloud のロード バランシングをどのように構成したかに応じて、これらの IP アドレスはすでに予約されている可能性があります。

Google Cloud

ロードバランサの外部 IP アドレスは、Ingress サービスが削除されても変わらず残るように予約する必要があります。その IP アドレスは、クラスタの構成によって、外部使用可能なものか、内部専用（限定公開クラスタなど）になります。

Google Cloud の内部ロードバランサ

内部ロードバランサの IP アドレスを予約する方法については、静的内部 IP アドレスの予約をご覧ください。

Google Cloud の外部ロードバランサ

外部ロードバランサの IP アドレスを予約するには:

1. ロードバランサの IP アドレスを取得します。

   コンソール

   Google Cloud コンソールからロードバランサの外部 IP アドレスを取得するには:

   1. Google Cloud コンソールの GKE ページに移動します。
      GKE に移動
   2. [Services と ingress] をクリックします。
   3. クラスタの Istio Ingress のサービスを特定します。Service のタイプは外部ロードバランサで、名前は istio-ingressgateway になります。
   4. クラスタの Istio Ingress サービスが見つかったら、そのエンドポイントをコピーします。これは、ポート番号なしの 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 Ingress が配置されている Namespace に置き換えます。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 コンソールで [ドメイン マッピング] ページを開きます。

   [ドメイン マッピング] に移動

   表示ウィンドウが小さすぎると、カスタム ドメインのマッピング ボタンは表示されないので、ページの右上にあるその他アイコンをクリックする必要があります。

2. [マッピングを追加] をクリックし、[サービス ドメイン マッピングを追加] を選択して、個々のサービスにドメインをマッピングします。各サービスに複数のドメインをマッピングできます。

3. [マッピングを追加] フォームのプルダウン リストから、カスタム ドメインをマッピングするサービスを選択します。

4. ドメイン名を入力します。例: your-domain.com、subdomain.your-domain.com など。ドメインの要件:

   • 基本パスのマッピングはサポートされていません。基本パスという用語は、ドメイン名の後の URL パス名を指します。たとえば、users は your-domain.com/users の基本パスです。Knative serving では、ドメインを特定の基本パスではなく / にのみマッピングできます。そのため、パスのルーティングは、サービスのコンテナ内のルーターを使用するか、Firebase Hosting を使用して処理する必要があります。
   • ドメインを自分のサービスの 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 Hosting を使用して処理する必要があります。
     • ドメインを自分のサービスの URL と一致するサブドメインにマッピングすることはできません。サービスへの URL は http://{service}.{namespace}.{your-domain.com} のように定義されます。そのため、サービスが test.default.your-domain.com にある場合は、同じサブドメイン（test.default.your-domain.com）へのドメイン マッピングを作成しないでください。

カスタム ドメインが Knative serving にマッピングされたら、ドメイン登録事業者で DNS レコードを追加する必要があります。

クラスタのマッピング

次のいずれかの方法で、カスタム ドメインをクラスタにマッピングします。

コンソール

1. Google Cloud コンソールで [ドメイン マッピング] ページを開きます。

   [ドメイン マッピング] に移動

   表示ウィンドウが小さすぎると、カスタム ドメインのマッピング ボタンは表示されないので、ページの右上にあるその他アイコンをクリックする必要があります。

2. [マッピングを追加] をクリックし、[Add default domain] を選択して、クラスタ内のすべてのサービスにドメインをマッピングします。デフォルトの場合、デプロイする新しいサービスはマッピングされたドメインを使用します。

3. チェックボックスをオンにして、新しいドメイン マッピングをクラスタ内の既存のサービスすべてに適用します。

4. [マッピングを追加] フォームのプルダウン リストから、カスタム ドメインをマッピングするクラスタを選択します。

5. ドメイン名を入力します。例: your-domain.com、subdomain.your-domain.com など。ドメインの要件:

   • 基本パスのマッピングはサポートされていません。基本パスという用語は、ドメイン名の後の URL パス名を指します。たとえば、users は your-domain.com/users の基本パスです。Knative serving では、ドメインを特定の基本パスではなく / にのみマッピングできます。そのため、パスのルーティングは、サービスのコンテナ内のルーターを使用するか、Firebase Hosting を使用して処理する必要があります。
   • ドメインを自分のサービスの 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 Hosting を使用して処理する必要があります。
   • ドメインを自分のサービスの 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] タブの [Edge Certificates] で [Always use 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

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

Knative serving のコンソール内から Cloud Domains にドメインを登録するには:

1. Knative serving の [ドメイン マッピング] ページに移動します。

   [ドメイン マッピング] に移動

2. [ドメインを登録] をクリックします。

3. ドメインの登録の手順で登録プロセスを完了します。

4. このページに前述のドメインを Knative serving にマッピングする手順を完了してから、ドメイン登録事業者で DNS レコードを追加します。

トラブルシューティング

カスタム ドメインとマネージド TLS のトラブルシューティングで、一般的な問題を確認する。