멀티 클러스터 인그레스 문제 해결 및 작업

GKE Enterprise 인그레스 컨트롤러는 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에서 멀티 클러스터 인그레스 리소스 매핑

아래 표에서는 Kubernetes 클러스터와 Google Cloud에서 생성된 리소스에 대한 Fleet 리소스 매핑을 보여줍니다.

Kubernetes 리소스 Google Cloud 리소스 설명
MultiClusterIngress 전달 규칙 HTTP(S) 부하 분산기 VIP입니다.
대상 프록시 주석 및 TLS 블록에서 가져온 HTTP/S 종단 설정입니다.
URL 맵 규칙 섹션에서 가상 호스트 경로 매핑입니다.
MultiClusterService Kubernetes 서비스 템플릿에서 파생된 리소스입니다.
백엔드 서비스 백엔드 서비스는 각 (Service, ServicePort) 쌍에 대해 생성됩니다.
네트워크 엔드포인트 그룹 서비스에 참여하는 백엔드 포드 모음입니다.

Compute Engine 부하 분산기 리소스 검사

부하 분산기를 만들면 부하 분산기를 구성하기 위해 만든 모든 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 응답이 반환되면 부하 분산기 상태 확인이 실패할 수 있습니다. 상태 확인은 두 가지 이유로 인해 실패할 수 있습니다.

  1. 애플리케이션 포드가 정상이 아님(Cloud 콘솔 디버깅에서 예시 참조)
  2. 잘못 구성된 방화벽으로 인해 Google 상태 확인기에서 상태 확인을 수행하지 못함

1번의 경우 애플리케이션에서 실제로 '/' 경로에서 200 응답을 반환해야 합니다.

2번의 경우 VPC에 'mci-default-l7'이라는 방화벽이 있어야 합니다. 인그레스 컨트롤러는 Google 상태 확인기가 백엔드에 도달할 수 있도록 VPC에 방화벽을 만듭니다. 방화벽이 없으면 방화벽을 만들 때 이 방화벽을 삭제하는 외부 자동화 기능이 없는지 확인합니다.

클러스터에 트래픽이 추가 또는 삭제되지 않음

새 멤버십을 추가할 경우 해당되는 경우 트래픽이 기본 클러스터의 백엔드에 도달해야 합니다. 마찬가지로, 멤버십이 삭제되면 기본 클러스터의 백엔드에 어떠한 트래픽도 도달해서는 안 됩니다. 이 동작이 관찰되지 않으면 MultiClusterIngress 및 MultiClusterService 리소스에 오류가 있는지 확인합니다.

일반적으로 VPC 기반 모드가 아닌 GKE 클러스터에 새 멤버십을 추가하거나 새 멤버십을 추가하되 GKE 클러스터에 애플리케이션을 배포하지 않으면 이 오류가 발생합니다.

  1. MultiClusterService를 설명합니다.

    kubectl describe mcs zone-svc

  2. MultiClusterIngress를 설명합니다.

    kubectl describe mci zone-mci

구성 클러스터 마이그레이션

마이그레이션 사용 사례에 대한 자세한 내용은 구성 클러스터 설계 개념을 참조하세요.

올바르게 구성하지 않으면 구성 클러스터 마이그레이션이 중단될 수 있습니다. 구성 클러스터 마이그레이션을 수행할 때 다음 가이드라인을 따르세요.

  1. MultiClusterIngress 리소스에 static-ip 주석을 사용해야 합니다. 그렇지 않으면 마이그레이션 중에 트래픽이 중단됩니다. 구성 클러스터를 마이그레이션할 때 임시 IP가 다시 생성됩니다.
  2. MultiClusterIngress 리소스와 MultiClusterService 리소스는 기존 구성 클러스터와 새 구성 클러스터에 동일하게 배포되어야 합니다. 두 클러스터의 차이로 인해 새 구성 클러스터에서 다른 MultiClusterService 리소스와 MultiClusterIngress 리소스가 조정됩니다.
  3. 언제든지 구성 클러스터 하나만 활성화됩니다. 구성 클러스터가 변경될 때까지 새 구성 클러스터의 MultiClusterIngress 리소스와 MultiClusterService 리소스는 부하 분산기 리소스에 영향을 주지 않습니다.

구성 클러스터를 마이그레이션하려면 다음 명령어를 실행합니다.

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

특성 상태에 표시되는 오류가 없는지 확인하여 명령어가 작동하는지 확인합니다.

  gcloud container fleet ingress describe

Console 디버깅

대부분의 경우 부하 분산기의 정확한 상태를 확인하면 문제를 디버깅할 때 유용합니다. Google Cloud 콘솔에서 부하 분산으로 이동하여 부하 분산기를 찾을 수 있습니다.

오류/경고 코드

멀티 클러스터 인그레스는 알려진 문제에 대해 gcloud multiclusteringress 설명 필드와 MultiClusterIngress 리소스 및 MultiClusterService 리소스에 대한 오류 및 경고 코드를 내보냅니다. 이 메시지에는 오류 코드와 경고 코드가 문서화되므로 정상적으로 작동하지 않을 때 그 의미를 쉽게 파악할 수 있습니다. 각 코드에는 AVMBR123 형식의 오류 ID로 구성됩니다. 여기서 123는 오류나 경고 및 권장 해결 방법에 해당하는 고유 번호입니다.

AVMBR101: Annotation [NAME] not recognized

이 오류는 인식되지 않는 MultiClusterIngress 또는 MultiClusterService 매니페스트에 주석이 지정되면 표시됩니다. 다음과 같은 이유로 인해 주석이 인식되지 않을 수 있습니다.

  1. 멀티 클러스터 인그레스에서 지원되지 않는 주석입니다. 이 문제는 GKE Enterprise 인그레스 컨트롤러에서 사용하지 않을 것으로 예상되는 리소스에 주석을 추가할 때 발생할 수 있습니다.

  2. 지원되지만 맞춤법이 틀려 인식되지 않는 주석입니다.

두 경우 모두 문서를 참조하여 지원되는 주석과 주석 지정 방법을 알아보세요.

AVMBR102: [RESOURCE_NAME] not found

이 오류는 MultiClusterIngress에 보조 리소스가 지정되었지만 구성 멤버십에서 찾을 수 없으면 표시됩니다. 예를 들어 이 오류는 MultiClusterIngress에서 찾을 수 없는 MultiClusterService를 참조하거나 MultiClusterService에서 찾을 수 없는 BackendConfig를 참조할 때 발생합니다. 다음과 같은 이유로 인해 리소스를 찾을 수 없습니다.

  1. 리소스가 올바른 네임스페이스에 있지 않습니다. 서로 참조하는 리소스는 모두 동일한 네임스페이스에 있어야 합니다.
  2. 리소스 이름의 철자가 잘못되었습니다.
  3. 리소스가 실제로 올바른 네임스페이스 + 이름으로 존재하지 않습니다. 이 경우 새로 만드세요.

AVMBR103: [CLUSTER_SELECTOR] is invalid

이 오류는 MultiClusterService에 지정된 클러스터 선택기가 잘못된 경우에 표시됩니다. 다음과 같은 이유로 인해 이 선택기가 유효하지 않습니다.

  1. 제공된 문자열에 오타가 있습니다.
  2. 제공된 문자열이 Fleet에 더 이상 존재하지 않는 클러스터 멤버십을 참조합니다.

AVMBR104: Cannot find NEGs for Service Port [SERVICE_PORT]

이 오류는 지정된 MultiClusterService 및 서비스 포트 쌍의 NetworkEndpointGroup(NEG)을 찾을 수 없으면 발생합니다. NEG는 각 백엔드 클러스터의 포드 엔드포인트가 포함된 리소스입니다. NEG가 존재하지 않는 주된 이유는 백엔드 클러스터에서 파생 서비스를 만들거나 업데이트하는 중에 오류가 발생했기 때문입니다. 자세한 내용은 MultiClusterService 리소스의 이벤트를 확인하세요.

AVMBR105: Missing GKE Enterprise license.

이 오류는 기능 상태 아래에 표시되며, GKE Enterprise API(anthos.googleapis.com)가 사용 설정되지 않았음을 나타냅니다.

AVMBR106: Derived service is invalid: [REASON].

이 오류는 MultiClusterService 리소스의 이벤트 아래에 표시됩니다. 이 오류가 발생하는 일반적인 이유 중 하나는 MultiClusterService에서 파생된 서비스 리소스에 잘못된 사양이 있기 때문입니다.

예를 들어 이 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"

이 오류는 기능 상태 아래에 표시되며, 멤버십 리소스의 기저를 이루는 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 클러스터가 경로 기반 클러스터인 경우에 발생합니다. 멀티 클러스터 인그레스 컨트롤러는 NEG를 사용하여 컨테이너 기반 부하 분산기를 만듭니다. 컨테이너 기반 부하 분산기를 사용하려면 클러스터가 VPC 기반이어야 합니다.

자세한 내용은 VPC 기반 클러스터 만들기를 참조하세요.

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

이 오류는 기능 상태 아래에 표시됩니다. 다음 두 가지 이유로 발생합니다.

  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 리소스를 만들면 이 오류가 표시됩니다.