マルチクラスタ Ingress のトラブルシューティングとオペレーション


GKE Enterprise Ingress コントローラによって、Compute Engine リソースが管理されます。MultiClusterIngress リソースと MultiClusterService リソースは別々の Compute Engine リソースにマッピングされるため、これらのリソースの関係を理解するとトラブルシューティングに役立ちます。たとえば、次の MultiClusterIngress リソースを調べます。

apiVersion: extensions/v1beta1
kind: MultiClusterIngress
metadata:
  name: foo-ingress
spec:
  template:
    spec:
      rules:
      - host: store.foo.com
        http:
          paths:
          - backend:
              serviceName: store-foo
              servicePort: 80
      - host: search.foo.com
        http:
          paths:
          - backend:
              serviceName: search-foo
              servicePort: 80

Compute Engine からマルチクラスタ Ingress リソースへのマッピング

次の表に、Kubernetes クラスタと Google Cloud で作成されたリソースへのフリート リソースのマッピングを示します。

Kubernetes リソース Google Cloud リソース 説明
MultiClusterIngress 転送ルール HTTP(S) ロードバランサの VIP。
ターゲット プロキシ アノテーションと TLS ブロックから取得した HTTP/S 終端設定。
URL マップ ルール セクションからの仮想ホストパス マッピング。
MultiClusterService Kubernetes Service テンプレートから派生したリソース。
バックエンド サービス (Service、ServicePort)ペアごとにバックエンド サービスが作成されます。
ネットワーク エンドポイント グループ Service に参加するバックエンド Pod のセット。

Compute Engine ロードバランサ リソースの検査

ロードバランサを作成すると、マルチクラスタ Ingress のステータスには、ロードバランサを構築するために作成されたすべての Compute Engine リソースの名前が含まれます。次に例を示します。

Name:         shopping-service
Namespace:    prod
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1beta1
Kind:         MultiClusterIngress
Metadata:
  Creation Timestamp:  2019-07-16T17:23:14Z
  Finalizers:
    mci.finalizer.networking.gke.io
Spec:
  Template:
    Spec:
      Backend:
        Service Name:  shopping-service
        Service Port:  80
Status:
  VIP:  34.102.212.68
  CloudResources:
    Firewalls: "mci-l7"
    ForwardingRules: "mci-abcdef-myforwardingrule"
    TargetProxies: "mci-abcdef-mytargetproxy"
    UrlMap: "mci-abcdef-myurlmap"
    HealthChecks: "mci-abcdef-80-myhealthcheck"
    BackendServices: "mci-abcdef-80-mybackendservice"
    NetworkEndpointGroups: "k8s1-neg1", "k8s1-neg2", "k8s1-neg3"

VIP が作成されません

VIP が表示されない場合は、作成中にエラーが発生した可能性があります。エラーが発生したかどうかを確認するには、次のコマンドを実行します。

kubectl describe mci shopping-service

出力は次のようになります。

Name:         shopping-service
Namespace:    prod
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1beta1
Kind:         MultiClusterIngress
Metadata:
  Creation Timestamp:  2019-07-16T17:23:14Z
  Finalizers:
    mci.finalizer.networking.gke.io
Spec:
  Template:
    Spec:
      Backend:
        Service Name:  shopping-service
        Service Port:  80
Status:
  VIP:  34.102.212.68
Events:
  Type     Reason  Age   From                              Message
  ----     ------  ----  ----                              -------
  Warning  SYNC    29s   multi-cluster-ingress-controller  error translating MCI prod/shopping-service: exceeded 4 retries with final error: error translating MCI prod/shopping-service: multiclusterservice prod/shopping-service does not exist

この例では、ユーザーが MultiClusterIngress によって参照された MultiClusterService リソースを作成しなかったためにエラーが発生しています。

502 レスポンス

ロードバランサが VIP を取得したが、一貫して 502 レスポンスを送信している場合、ロードバランサのヘルスチェックが失敗している可能性があります。ヘルスチェックが失敗する原因は 2 つあります。

  1. アプリケーションの Pod が正常ではありません(サンプルについては、Cloud Console のデバッグを参照)。
  2. 正しく構成されていないファイアウォールは、Google Health Checker のヘルスチェックをブロックします。

1 の場合、アプリケーションが「/」パスで 200 のレスポンスを実際に送信しているかを確認します。

2 の場合は、「mci-default-l7」という名前のファイアウォールが VPC にあることを確認します。Ingress コントローラは VPC 内にファイアウォールを作成して、Google Health Checker がバックエンドに到達できるようにします。ファイアウォールが存在しない場合は、作成時にこのファイアウォールを削除する外部自動化機能がないことを確認します。

クラスタへのトラフィックの追加、またはクラスタからのトラフィックの削除

新しいメンバーシップを追加するとき、該当する場合は、基盤となるクラスタのバックエンドにトラフィックが届きます。同様に、メンバーシップが削除されても、基盤となるクラスタのバックエンドにトラフィックは届きません。この動作が見られない場合は、MultiClusterIngress リソースと MultiClusterService リソースにエラーがないか確認してください。

このエラーが発生しがちなケースには、VPC ネイティブ モードではない GKE クラスタに新しいメンバーシップを追加した場合や、GKE クラスタにアプリケーションをデプロイしないで新しいメンバーシップを追加した場合が含まれます。

  1. MultiClusterService を記述します。

    kubectl describe mcs zone-svc
    
  2. MultiClusterIngress を記述します。

    kubectl describe mci zone-mci
    

構成クラスタの移行

移行のユースケースの詳細については、構成クラスタの設計コンセプトをご覧ください。

構成クラスタの移行は、正しく処理されないと中断される可能性があります。構成クラスタを移行する場合は、次のガイドラインに従ってください。

  1. MultiClusterIngress リソースで必ず静的 IP アノテーションを使用してください。そうしないと、移行中にトラフィックが中断されます。エフェメラル IP は構成クラスタの移行時に再作成されます。
  2. MultiClusterIngress リソースと MultiClusterService リソースは、既存の構成クラスタと新しい構成クラスタに対して同じようにデプロイする必要があります。これらに相違があると、新しい構成クラスタでの異なる MultiClusterService リソースと MultiClusterIngress リソースが調整されます。
  3. 常に 1 つの構成クラスタのみがアクティブになります。構成クラスタが変更されるまで、新しい構成クラスタ内の MultiClusterIngress リソースと MultiClusterService リソースはロードバランサ リソースに影響しません。

構成クラスタを移行するには、次のコマンドを実行します。

  gcloud container fleet ingress update \
    --config-membership=projects/project_id/locations/global/memberships/new_config_cluster

機能の状態に目に見えるエラーがないことを確認して、コマンドが機能したことを確認します。

  gcloud container fleet ingress describe

コンソールのデバッグ

ほとんどの場合、ロードバランサの正確なステータスを確認すると、問題をデバッグするときに役立ちます。ロードバランサを確認するには、Google Cloud Console で [負荷分散] に移動します。

エラー / 警告コード

マルチクラスタ Ingress では、MultiClusterIngress リソースと MultiClusterService リソースに関するエラーコードと警告コード、既知の問題に関する gcloud multiclusteringress 説明フィールドが出力されます。これらのメッセージにはエラーや警告のコードが記載されており、正常に動作しない場合に何を意味するかを理解しやすくなります。各コードは、AVMBR123 という形式のエラー ID で構成されます。123 は、エラーまたは警告に対応する一意の番号であり、解決方法の提案です。

AVMBR101: Annotation [NAME] not recognized

このエラーは、MultiClusterIngress または MultiClusterService マニフェストで認識されないアノテーションが指定されている場合に表示されます。アノテーションが認識されない理由はいくつかあります。

  1. アノテーションがマルチクラスタ Ingress ではサポートされていない。これは、GKE Enterprise Ingress コントローラによって使用されることが想定されていないリソースにアノテーションを付ける場合が想定されます。

  2. アノテーションはサポートされているものの、スペルが間違っているため認識されない。

どちらの場合も、サポートされているアノテーションとその指定方法を理解するために、ドキュメントをご覧ください。

AVMBR102: [RESOURCE_NAME] not found

このエラーは、MultiClusterIngress で補助リソースが指定されているものの、構成メンバーシップで見つからない場合に表示されます。たとえば、MultiClusterIngress が参照している MultiClusterService が見つからない場合や、MultiClusterService が参照している BackendConfig が見つからない場合に、このエラーがスローされます。リソースが見つからなかった理由はいくつかあります。

  1. 適切な名前空間にない。相互に参照しているリソースがすべて同じ名前空間にあることを確認します。
  2. リソース名のスペルが間違っている。
  3. 適切な名前空間と名前のリソースが存在しない。この場合は、作成してください。

AVMBR103: [CLUSTER_SELECTOR] is invalid

このエラーは、MultiClusterService で指定されたクラスタ セレクタが無効な場合に表示されます。このセレクタが無効になる理由はいくつかあります。

  1. 指定された文字列に入力ミスがある。
  2. 指定された文字列が、フリートに存在していないクラスタ メンバーシップを参照している。

AVMBR104: Cannot find NEGs for Service Port [SERVICE_PORT]

このエラーは、特定の MultiClusterService とポートのペアに対する NetworkEndpointGroup(NEG)が見つからない場合にスローされます。NEG は、各バックエンド クラスタの Pod エンドポイントが含まれるリソースです。NEG が存在しない主な原因は、バックエンド クラスタ内の派生サービスを作成中または更新中にエラーが発生したためです。詳細については、MultiClusterService リソースのイベントをご覧ください。

AVMBR105: Missing GKE Enterprise license.

このエラーは、機能の状態の下に表示され、GKE Enterprise API(anthos.googleapis.com)が有効になっていない場合に発生します。

AVMBR106: Derived service is invalid: [REASON].

このエラーは、MultiClusterService リソースのイベントの下に表示されます。このエラーの一般的な理由の 1 つとして、MultiClusterService から派生した Service リソースの仕様が無効であることが挙げられます。

たとえば、この MultiClusterService では、その仕様で定義されている ServicePort が定義されていません。

apiVersion: networking.gke.io/v1
kind: MultiClusterService
metadata:
  name: zone-mcs
  namespace: whereami
spec:
  clusters:
  - link: "us-central1-a/gke-us"
  - link: "europe-west1-c/gke-eu"

このエラーは、機能の状態の下に表示されます。これは、Membership リソースの基礎となる GKE クラスタがないためです。これを検証するには、以下のコマンドを実行します。

gcloud container fleet memberships describe membership-name

次に、エンドポイント フィールドの下に GKE クラスタのリソースリンクがないことを確認します。

AVMBR108: GKE cluster [NAME] not found.

このエラーは、機能の状態の下に表示されます。メンバーシップの基盤となる GKE クラスタが存在しない場合、スローされます。

AVMBR109: [NAME] is not a VPC-native GKE cluster.

このエラーは、機能の状態の下に表示されます。このエラーは、指定した GKE クラスタがルートベース クラスタである場合にスローされます。マルチクラスタ Ingress コントローラは、NEG を使用してコンテナ ネイティブのロードバランサを作成します。コンテナ ネイティブのロードバランサを使用するには、クラスタが VPC ネイティブである必要があります。

詳細については、VPC ネイティブ クラスタの作成をご覧ください。

AVMBR110: [IAM_PERMISSION] permission missing for GKE cluster [NAME].

このエラーは、機能の状態の下に表示されます。このエラーには、以下の 2 つの原因が考えられます。

  1. メンバーシップの基盤となる GKE クラスタが、メンバーシップ自体とは別のプロジェクトに存在する。
  2. 指定された IAM 権限が MultiClusterIngress サービス エージェントから削除された。

AVMBR111: Failed to get Config Membership: [REASON].

このエラーは、機能の状態の下に表示されます。このエラーが発生する主な理由としては、この機能が有効になっている間に構成メンバーシップが削除されたことが考えられます。

構成メンバーシップを削除する必要はありません。変更する場合は、構成クラスタの移行手順に沿って操作してください。

AVMBR112: HTTPLoadBalancing Addon is disabled in GKE Cluster [NAME].

このエラーは機能の状態の下に表示され、GKE クラスタで HTTPLoadBalancing アドオンが無効になっている場合に発生します。GKE クラスタを更新して HTTPLoadBalancing アドオンを有効にできます。

gcloud container clusters update name --update-addons=HttpLoadBalancing=ENABLED

AVMBR113: This resource is orphaned.

あるリソースの有用性が、別のリソースからの参照が前提となっている場合があります。このエラーは、Kubernetes リソースが作成されたものの、別のリソースから参照されていない場合にスローされます。たとえば、MultiClusterService で参照されていない BackendConfig リソースを作成すると、このエラーが表示されます。