IBM Cloud Docs
Ingress のセットアップ

Ingress のセットアップ

Ingress リソースを作成して、Ingress コンポーネントを構成し、要求をルーティングするためのルールを定義し、アプリ・サービスへのパスを指定します。 公開するアプリまたはサービスが含まれている名前空間ごとに、別個の Ingress リソースが必要です。

開始前に

始める前に、以下の準備手順に従ってください。

  1. Ingressをセットアップするための正しい権限を持っていることを確認してください。 以下の IBM Cloud IAM 役割 が必要です。

    • クラスターに対する管理者のプラットフォーム・アクセス役割
    • すべての名前空間に対するマネージャーのサービス・アクセス役割
  2. IBM提供の Ingress サブドメインを使用するかどうかを決定します。 提供されたサブドメインを使用しない場合は、独自の カスタム・ドメイン を作成して登録する必要があります。

    プライベート ALB を介してアプリを公開するには、カスタム・ドメインが必要です。

  3. プライベート ALB を介してアプリを公開する場合は、CLI で各プライベート ALB を有効にする必要があります。 ALB IDを取得するには、ibmcloud ks ingress alb ls --cluster CLUSTER を実行する。

    クラシック・クラスター 詳しくは、CLI リファレンス を参照してください。

    ibmcloud ks ingress alb enable classic --alb <alb_id> --cluster <cluster_name>
    

    VPC クラスター 詳細情報とコマンド・オプションについては、CLI リファレンス を参照してください。

    ibmcloud ks ingress alb enable vpc-gen2 --alb <alb_id> --cluster <cluster_name>
    
  4. 高可用性を確保し、定期的な更新を適用するために、ゾーンごとに少なくとも 2 つのワーカー・ノードがクラスターに含まれていることを確認してください。 1 つのゾーンにワーカー・ノードが 1 つしかない場合、ALB は自動更新を受信できません。 詳しくは、 ALB のワーカー・ノード要件 を参照してください。

  5. クラシック・クラスターを使用している場合は、 IBM Cloud インフラストラクチャー・アカウントの 仮想ルーター機能(VRF) を有効にします。 VRF を有効にするには、VRF の有効化を参照してください。 VRF が既に有効になっているかどうかを確認するには、ibmcloud account show コマンドを使用します。 VRF を有効にできない、または有効にしない場合は、VLAN スパンニングを有効にします。 VRF または VLAN スパンニングが有効になると、ALB は、アカウント内のさまざまなサブネットにパケットをルーティングできるようになります。

  6. VPC クラスターを使用している場合は、Ingress によってワーカー・ノードのノード・ポートにルーティングされるトラフィック要求が VPC セキュリティー・グループ で許可されていることを確認してください。

  7. 自動化やテストなどの目的で、同じまたは類似した名前のクラスターを 7 日以内に 5 回以上作成および削除すると、Let's Encrypt の重複証明書レート制限に達する可能性があります。 Ingress のサブドメインと証明書が正しく登録されるようにするには、クラスターの名前の最初の 24 文字が異なっている必要があります。

  8. ネットワーク・トラフィックをエッジ・ワーカー・ノードに制限する場合は、ALB が均等にデプロイされるように、各ゾーンで 2 つ以上のエッジ・ワーカー・ノードを有効にしてください。

ゾーンで障害が発生した場合、そのゾーンの Ingress ALB への要求で断続的に障害が発生する可能性があります。

セットアップ・ステップ

以下の手順に従って、Ingress をセットアップします。

ステップ 1: ClusterIP サービスを作成する

ClusterIP サービスは、外部要求をアプリ・ポッドに転送できるように、アプリをクラスター内から到達可能にするために必要です。 Ingress ロード・バランシングに含めるには、アプリを公開する ClusterIP サービスの名前が、クラスター内のすべての名前空間で一意でなければなりません。

公開するアプリ・デプロイメントごとに、Kubernetes ClusterIP サービスを作成します。 アプリを Ingress ロード・バランシングに含めるには、Kubernetes サービスを介してアプリを公開する必要があります。

kubectl expose deploy <app_deployment_name> --name my-app-svc --port <app_port> -n <namespace>

ステップ 2: TLS 証明書と Kubernetes シークレットを使用して TLS 終端をセットアップする

TLS 証明書は、アプリが存在する各名前空間に Kubernetes シークレットとして保管する必要があります。

ステップ 3: Ingress リソースを作成する

Ingressリソースを作成し、Ingressコントローラーがアプリサービスにトラフィックをルーティングするために使用するルーティングルールを定義します。

  1. YAML ファイルに Ingress リソースを作成します。

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: my-ingress-resource
    spec:
      ingressClassName: nginx-example
      tls:
      - hosts:
        - <domain_name>
        secretName: <tls_secret_name>
      rules:
      - host: HOSTNAME
        http:
          paths:
          - path: <app_path_1>
            pathType: Prefix
            backend:
              service:
                name: <app_service_1>
                port:
                  number: 80
          - path: <app_path_2>
            pathType: Prefix
            backend:
              service:
                name: <app_service_2>
                port:
                  number: 80
    
    
    annotations
    kubernetes.io/ingress.class: 適用する Ingress クラスを指定します。 IBM提供の Ingress クラスは、パブリック ALB の場合は "public-iks-k8s-nginx" 、プライベート ALB の場合は "private-iks-k8s-nginx" です。
    このカスタム・クラスは、 IngressClass リソースおよび ibm-ingress-deploy-config 構成マップで指定します。 Ingressのルーティングをカスタマイズするには、Kubernetes NGINXアノテーション (nginx.ingress.kubernetes.io/<annotation>) を追加します。カスタム IBM Cloud Kubernetes Service アノテーション (ingress.bluemix.net/<annotation>) はサポートされていません。
    注意: Ingress が Helm チャートの一部としてデプロイされている場合など、他のコンポーネントが Ingress ALB を管理する構成では、このアノテーションを指定しないでください。 代わりに、あなたの設定にあったIngressクラスを見つけて、spec.ingressClassName: <class_name> フィールドでそのクラスを指定してください。
    ingressClassName
    Ingress クラス名。 IBM提供の Ingress クラスは、パブリック ALB の場合は public-iks-k8s-nginx 、プライベート ALB の場合は private-iks-k8s-nginx です。
    tls.hosts
    TLS を使用するには、<domain> を、IBM 提供の Ingress サブドメインまたはカスタム・ドメインで置き換えます。
    tls.secretName
    <tls_secret_name> を、 TLS 証明書 が保管されている Kubernetes シークレットの名前に置き換えます。
    host
    <domain> を、IBM 提供の Ingress サブドメインまたはカスタム・ドメインに置き換えます。
    path
    <app_path> を、スラッシュまたはアプリが listen しているパスに置き換えます。 指定したIngressドメインにパスが付加され、アプリへのユニークなルートが作成される。 この経路を Web ブラウザーに入力すると、ネットワーク・トラフィックが ALB にルーティングされます。 ALB は、関連付けられたサービスを検索し、ネットワーク・トラフィックをそのサービスに送信します。 そして、サービスが、アプリを実行するポッドにトラフィックを転送します。
    pathType
    URL パス・マッチング方式。 サポートされている値は、ImplementationSpecificExact、または Prefix です。 各パスタイプの詳細と例については、community Kubernetes documentation を参照してください。
    service.name
    app1_service および app2_service などを、アプリを公開するために作成したサービスの名前に置き換えます。 指定するアプリが同じ名前空間内にあることを確認してください。
    service.name
    <app1_service> および <app2_service> などを、アプリを公開するために作成したサービスの名前に置き換えます。 指定するアプリが同じ名前空間内にあることを確認してください。
    service.port.number
    サービスが listen するポート。 アプリ用に Kubernetes サービスを作成したときに定義したものと同じポートを使用します。
  2. Ingressリソースをクラスタに適用します。 リソースで指定したアプリ・サービスと同じ名前空間にリソースがデプロイされていることを確認します。

    kubectl apply -f community-ingress-resource.yaml -n <namespace>
    

ステップ 4: Ingress セットアップを確認する

  1. ALB をリストアップし、Kubernetes Ingress イメージを実行する 1 つの ALB の IP アドレス (classic) またはホスト名 (VPC) をコピーします。 出力で、Build が形式 <community_version>_<ibm_build>_iks になっている ALB を選択します。

    ibmcloud ks ingress alb ls -c <cluster>
    
  2. ALBのIPアドレス(クラシック)またはホスト名(VPC)、アプリのパス、およびドメインを使用して、このALBを介してアプリにトラフィックを正常に送信できることを確認します。

    curl http://<ALB_IP>/<app_path> -H "Host: <ingress_subdomain>"
    

    例えば、デフォルトのIngressサブドメインを使って myapp というアプリにリクエストを送るには、以下のコマンドを実行する。

    curl http://169.X.X.X/myapp -H "Host: mycluster-a1b2cdef345678g9hi012j3kl4567890-0000.us-south.containers.appdomain.cloud"
    

Ingress を介したアプリへの接続に問題が発生していますか? Ingress のトラブルシューティングを試してください。 ibmcloud ks ingress status-report get -c <cluster_name_or_ID> を実行すれば、Ingress コンポーネントの正常性と状況を確認できます。

Ingress を使用するカスタム・ドメイン

IBM提供の Ingress サブドメインを使用しない場合は、Ingress リソース内で指定する独自のカスタム・ドメインを使用できます。 プライベート ALB を介して Ingress で公開されるアプリには、カスタム・ドメインが必要であることに注意してください。

パブリック ALB 用のカスタム・ドメインの作成

パブリック ALB のカスタム・ドメインを作成するには、以下の手順を実行します。

  1. カスタム・ドメインを作成します。 カスタム・ドメインを登録する時には、Domain Name Service (DNS) プロバイダーまたは IBM Cloud DNS を使用してください。 Ingress で公開するアプリが 1 つのクラスター内の別々の名前空間にある場合は、カスタム・ドメインをワイルドカード・ドメイン (*.custom_domain.net など) として登録します。 Kubernetes バージョン 1.20 以降では、ドメインは 130 文字以下に制限されていることに注意してください。

  2. IBM 提供サブドメインを正規名レコード (CNAME) として指定することで、カスタム・ドメインの別名を定義します。 IBM 提供の Ingress ドメインを確認するには、ibmcloud ks cluster get --cluster <cluster_name> を実行し、Ingress サブドメインフィールドを見つけます。

    IBM提供のサブドメインを CNAME として指定することは、自動ヘルス・チェックで DNS 応答から失敗した IP を削除するため、および ALB を追加または削除するときにカスタム・ドメインが更新されるようにするために必要です。

プライベート ALB 用のカスタム・ドメインの作成

プライベート ALB のカスタム・ドメインを作成するには、以下の手順を実行します。 プライベート ALB で Ingress を使用するには、カスタム・ドメインが必要であることに注意してください。

プライベート VLAN のみを使用するクラシック・クラスターの場合は、まず、プライベート・ネットワークで使用可能な独自の DNS サービスを構成する必要があります。

  1. DNS サービス・プロバイダーを介してカスタム・ドメインを作成します。 Ingress URL は 130 文字以下でなければならないことに注意してください。

  2. プライベート ALB の IP アドレスを A レコードとして追加するか (クラシック・クラスター)、VPC ホスト名を CNAME として追加して (VPC クラスター)、カスタム・ドメインをプライベート ALB にマップします。 ALB の IP アドレス (クラシック) またはホスト名 (VPC) を見つけるには、ibmcloud ks ingress alb ls -c <cluster_name_or_ID> を実行します。