Gateway API 문제 해결

Gateway API 문제 해결 (Troubleshooting)

이 페이지는 Gateway API의 다양한 메커니즘과 문제 해결 방법을 안내해요. Troubleshooting Ingress & Service Mesh 페이지의 Generic 및 Setup Verification 단계를 반드시 따라주세요.

출처: Troubleshooting

본문

이 페이지는 Gateway API의 다양한 메커니즘과 문제 해결 방법을 안내해요.

Troubleshooting Ingress & Service Mesh 페이지의 Generic 및 Setup Verification 단계를 반드시 따라주세요.

리소스 확인하기 (Checking resources)

  • Gateway 리소스 확인
$ kubectl get gateway -A
NAMESPACE                   NAME                 CLASS    ADDRESS          PROGRAMMED   AGE
website                     http-gateway         cilium   172.21.255.202   True         5h
webshop                     tls-gateway          cilium   172.21.255.203   True         5h

앞선 명령은 클러스터의 모든 Gateway에 대한 개요를 반환해요. 다음을 확인해주세요:

  • Gateway가 프로그래밍됐나요?
    • 프로그래밍된 Gateway란 Cilium이 그에 대한 구성을 준비했다는 뜻이에요.
    • Programmed true 표시가 없다면 Cilium 구성에서 Gateway API가 활성화됐는지 확인해주세요.
  • Gateway에 주소가 있나요?
    • kubectl get service로 서비스를 확인할 수 있어요.
    • Gateway에 주소가 있다면 LoadBalancer 서비스가 gateway에 할당됐다는 뜻이에요.
    • IP가 나타나지 않는다면 LoadBalancer 구현이 빠졌을 수 있어요.
  • 클래스가 cilium인가요?
    • Cilium은 cilium 클래스의 Gateway만 프로그래밍해요.
  • Gateway API 리소스 유형(Gateway, HTTPRoute 등)이 발견되지 않으면 Gateway API CRD가 설치됐는지 확인해주세요.

kubectl describe gateway로 문제를 더 자세히 조사할 수 있어요.

$ kubectl describe gateway <name>

  Conditions:
    Message:               Gateway successfully scheduled
    Reason:                Accepted
    Status:                True
    Type:                  Accepted
    Message:               Gateway successfully reconciled
    Reason:                Programmed
    Status:                True
    Type:                  Programmed
    [...]
  Listeners:
    Attached Routes:  2
    Conditions:
      Message:               Listener Ready
      Reason:                Programmed
      Status:                True
      Type:                  Programmed
      Message:               Listener Accepted
      Reason:                Accepted
      Status:                True
      [...]

gateway의 일반 상태와 구성된 리스너의 상태를 볼 수 있어요.

리스너 상태는 리스너에 성공적으로 연결된 라우트 수를 표시해요.

gateway와 listener 모두에 대한 상태 조건을 볼 수 있어요:

  • Accepted: Gateway 구성이 수락됐어요.
  • Programmed: Gateway 구성이 Envoy에 프로그래밍됐어요.
  • ResolvedRefs: 참조된 모든 시크릿이 발견됐고 사용 권한이 있어요.

이 조건 중 하나라도 false로 설정되면, Message와 Reason 필드가 더 많은 정보를 제공해요.

  • HTTPRoute 리소스 확인

Gateway가 동작하면 라우트를 확인해서 올바르게 구성됐는지 검증할 수 있어요. 라우트 상태를 확인하는 방법은 gateway 리소스 상태를 확인하는 것과 비슷해요.

이 지침은 HTTPRoute용으로 작성됐지만, 다른 라우트 유형에도 적용돼요.

$ kubectl get httproute -A
NAMESPACE                 NAME              HOSTNAMES         AGE
website                   homepage          www.example.org   17m
webshop                   catalog-service                     17m
webshop                   cart-service                        17m

더 많은 정보를 얻으려면 kubectl describe httproute <name>을 입력해주세요.

$ kubectl describe httproute <name>
Status:
  Parents:
    Conditions:
      Last Transition Time:  2023-06-05T15:11:53Z
      Message:               Accepted HTTPRoute
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2023-06-05T15:11:53Z
      Message:               Service reference is valid
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
    Controller Name:         io.cilium/gateway-controller
    Parent Ref:
      Group:  gateway.networking.k8s.io
      Kind:   Gateway
      Name:   same-namespace

Status는 특정 HTTPRoute와 관련된 조건들을 나열해요. 조건은 gateway에 대한 부모 참조별로 나열돼요. 라우트를 여러 gateway에 연결했다면 여러 항목이 나타나요. 조건에는 Reason, Type, Status, Message가 포함돼요. Type은 조건 유형을 나타내고, Status는 조건 유형이 충족되는지 여부를 boolean으로 나타내요. 선택적으로 Message가 조건에 대한 추가 정보를 제공해요.

다음 조건 유형을 주목해주세요:

  • Accepted: HTTPRoute 구성이 올바르고 수락됐어요.
  • ResolvedRefs: 참조된 서비스가 발견됐고 유효한 참조예요.

이 중 하나라도 false로 설정되면 Message와 Reason 필드를 살펴보면 더 많은 정보를 얻을 수 있어요.

  • Cilium Operator 로그 확인

Cilium Operator 로그에는 추가 디버깅 정보가 있을 수 있어요. 예를 들어 필요한 CRD(Custom Resource Definitions)가 설치되지 않으면 오류가 기록돼요:

$ kubectl logs -n kube-system deployments/cilium-operator | grep gateway
level=error msg="Required GatewayAPI resources are not found, please
refer to docs for installation instructions" error="customresourcedefinitions.apiextensions.k8s.io \"gatewayclasses.gateway.networking.k8s.io\" not found
customresourcedefinitions.apiextensions.k8s.io \"gateways.gateway.networking.k8s.io\" not found
customresourcedefinitions.apiextensions.k8s.io \"httproutes.gateway.networking.k8s.io\" not found
customresourcedefinitions.apiextensions.k8s.io \"referencegrants.gateway.networking.k8s.io\" not found
customresourcedefinitions.apiextensions.k8s.io \"grpcroutes.gateway.networking.k8s.io\" not found
customresourcedefinitions.apiextensions.k8s.io \"tlsroutes.gateway.networking.k8s.io\" not found" subsys=gateway-api

흔한 실수 (Common mistakes)

경고

Gateway API는 Kubernetes에 최근에 추가된 것이며, Cilium 프로젝트는 아직 많은 사용자 피드백을 받지 못했어요. 이 섹션에 아직 나열되지 않은 문제를 만난다면 이 목록에 여러분의 문제를 추가하는 PR을 여는 것을 고려해보세요.

  • 백엔드 서비스가 존재하지 않아요.
    • 백엔드 서비스가 발견됐는지 확인하려면 kubectl describe httproute <name>을 실행하고 conditions 필드를 검사해주세요:
Parents:
  Conditions:
    Last Transition Time:  2023-06-06T13:55:10Z
    Message:               Service "backend" not found
    Observed Generation:   1
    Reason:                BackendNotFound
    Status:                False
    Type:                  ResolvedRefs
    Last Transition Time:  2023-06-06T13:55:10Z
    Message:               Accepted HTTPRoute
    Observed Generation:   1
    Reason:                Accepted
    Status:                True
    Type:                  Accepted
  Controller Name:         io.cilium/gateway-controller
  • parentRefs 아래에 지정된 gateway가 존재하지 않아요.
    • gateway가 발견됐는지 확인하려면 kubectl describe httproute <name>을 실행하고 conditions 필드를 검사해주세요:
Parents:
  Conditions:
    Last Transition Time:  2023-06-06T13:56:40Z
    Message:               Gateway.gateway.networking.k8s.io "my-gateway" not found
    Observed Generation:   2
      Reason:                InvalidHTTPRoute
      Status:                False
      Type:                  Accepted

기본 메커니즘: 높은 수준 개요 (Underlying mechanics: a high level overview)

Cilium 배포에는 Gateway API 리소스를 처리하는 두 부분이 있어요: Cilium agent와 Cilium operator예요.

Cilium operator는 모든 Gateway API 리소스를 감시하고 리소스가 유효한지 검증해요. 리소스가 유효하면 operator가 이를 accepted로 표시해요. 그러면 Cilium Envoy Configuration 리소스로의 변환 과정이 시작돼요.

그 다음 Cilium agent가 Cilium Envoy Configuration 리소스를 가져와요.

Cilium agent는 이 리소스들을 사용해 내장 Envoy 또는 Envoy DaemonSet에 구성을 공급해요. Envoy가 트래픽을 처리해요.

더 알아보기 (Learn more)