Kubernetes에서 API 게이트웨이 라우트 정의

Kubernetes 오케스트레이션 네트워크에서 HTTP 및 TCP 라우트를 구성하고 Consul API 게이트웨이 리스너에 연결하는 방법을 설명해 드릴게요. 라우트는 외부 클라이언트가 메시의 서비스에 요청을 보낼 수 있게 하는 규칙 기반 구성이에요.

출처: 문서

본문

이 문서는 Kubernetes 오케스트레이션 네트워크에서 HTTP 및 TCP 라우트를 구성하고 Consul API 게이트웨이 리스너에 연결하는 방법을 설명해요. 라우트는 외부 클라이언트가 메시의 서비스에 요청을 보낼 수 있게 하는 규칙 기반 구성이에요.

개요

다음 단계는 라우트를 정의하고 배포하기 위한 일반적인 워크플로를 설명해요:

프로토콜 유형, 연결할 게이트웨이 이름, 요청 라우팅 규칙을 지정하는 라우트 구성을 정의해요.
구성을 배포하여 라우트를 만들고 게이트웨이에 연결해요.

라우트와 그것이 연결된 게이트웨이는 eventual-consistent(최종 일관성) 객체예요. 일련의 상태 조건을 통해 현재 상태에 대한 피드백을 제공해요. 결과적으로 라우트가 게이트웨이에 성공적으로 바인딩되었는지 확인하려면 라우트 상태를 수동으로 확인해야 해요.

요구 사항

환경이 Kubernetes 기술 사양에 지정된 요구 사항을 충족하는지 확인해 주세요.

OpenShift

Kubernetes 오케스트레이션 네트워크가 OpenShift에서 실행되는 경우 Consul 설치에 OpenShift가 활성화되어 있는지 확인해 주세요. 자세한 내용은 OpenShift 요구 사항을 참고해 주세요.

라우트 정의

Consul이 들어오는 요청을 메시의 서비스로 라우팅할 수 있도록 라우트 구성을 정의하고 게이트웨이에 구성된 리스너에 바인딩해 주세요.

구성 파일을 만들고 다음 필드를 지정해 주세요:

apiVersion: Kubernetes API 게이트웨이 버전을 지정해요. 표준 API 게이트웨이에서는 gateway.networking.k8s.io/v1, Consul API 게이트웨이에서는 consul.hashicorp.com/v1beta1로 설정해야 해요. API 버전에 대한 자세한 내용은 Consul API 게이트웨이 참조 객체를 참고해 주세요.
kind: HTTPRoute 또는 TCPRoute로 설정해 주세요.
metadata.name: 라우트의 이름을 지정해 주세요. 이름은 Consul 작업을 수행할 때 구성을 참조하는 데 사용할 수 있는 메타데이터예요.
spec.parentRefs.name: 라우트가 바인딩되는 API 게이트웨이 목록을 지정해요.
spec.rules: 리스너를 서비스에 매핑하는 라우팅 테이블을 구성하기 위한 라우팅 규칙 목록을 지정해요.

라우트 규칙 구성에 대한 자세한 내용은 Routes 구성 참조를, 올바른 게이트웨이 유형 선택에 대한 지침은 Kubernetes용 API 게이트웨이 활성화 가이드를 참고해 주세요.

사용 사례에 필요한 추가 필드(네임스페이스 또는 admin 파티션 등)를 구성해 주세요.
구성을 저장해 주세요.

다음 예시는 example-gateway에 정의된 리스너와 연결된 example-route라는 라우트를 만들어요.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - backendRefs:
    - kind: Service
      name: echo
      port: 8080

서비스 하위 집합으로 라우팅

HTTPRoute가 단일 백엔드 서비스로 트래픽을 보낼 때 Consul API 게이트웨이는 백엔드 서비스의 디스커버리 체인도 평가해요. 백엔드 서비스에 일치하는 요청을 ServiceResolver 하위 집합으로 라우팅하는 ServiceRouter가 있다면, API 게이트웨이는 게이트웨이 디스커버리 체인을 구축할 때 해당 하위 집합 라우팅을 보존해요.

Consul 서비스 메시 트래픽 관리를 사용하면서 게이트웨이에서 HTTP 라우트를 노출할 수 있어요. 예를 들어 요청 하위 집합을 카나리아 서비스 버전으로 라우팅하는 경우가 있어요. Consul은 HTTPRoute 매치와 ServiceRouter 매치를 둘 다 적용해요. 예를 들어 Consul이 요청을 하위 집합 대상으로 라우팅하기 전에 요청이 게이트웨이 라우트와 service-router 규칙을 모두 일치해야 해요.

다음 예시는 x-version: canary 헤더가 있는 요청을 api 서비스의 canary 하위 집합으로 라우팅해요. 라우트와 일치하는 다른 모든 요청은 stable 기본 하위 집합을 사용해요.

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: api
spec:
  defaultSubset: stable
  subsets:
    stable:
      filter: Service.Meta.version == stable
    canary:
      filter: Service.Meta.version == canary
---
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
  name: api
spec:
  routes:
    - match:
        http:
          header:
            - name: x-version
              exact: canary
      destination:
        service: api
        serviceSubset: canary
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - kind: Service
      name: api
      port: 8080

HTTP 라우트용 TLS SDS 백엔드 재정의

Kubernetes에서 HTTP 라우트에 대한 백엔드 수준의 SDS 인증서 재정의는 HTTPRoute.rules[].backendRefs[].filters[] 아래에 연결된 RouteTLSSDSFilter로 구성돼요.

필터 필드:

spec.sds.certResource (필수)
spec.sds.clusterName (리스너/게이트웨이 SDS에서 상속된 경우 선택)

동작:

clusterName이 생략되면 부모 참조에서 리스너 수준/전역 SDS 클러스터가 정확히 하나 해석될 때 상속될 수 있어요.
상속된 clusterName이 없거나 모호하면 필터가 거부돼요.
규칙 수준 필터 배치(HTTPRoute.rules[].filters[])는 이 재정의 유형에 유효하지 않아요.

예시: RouteTLSSDSFilter를 사용한 HTTPRoute backendRef 재정의

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: api-route-override
  namespace: default
spec:
  parentRefs:
  - name: sds-gateway
    sectionName: https
  hostnames:
  - b.example.test
  rules:
  - backendRefs:
    - name: svc-b
      port: 5678
      filters:
      - type: ExtensionRef
        extensionRef:
          group: consul.hashicorp.com
          kind: RouteTLSSDSFilter
          name: route-sds-override-http
---
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteTLSSDSFilter
metadata:
  name: route-sds-override-http
  namespace: default
spec:
  sds:
    clusterName: sds-cluster-2
    certResource: foo.example.com

유효 TLS SDS 우선순위

구성된 경우 인증서 선택 우선순위는 다음과 같아요:

라우트 서비스 재정의 TLS.SDS
리스너 TLS.SDS
게이트웨이 수준 TLS.SDS

문제 해결 체크리스트

RouteTLSSDSFilter가 backendRefs[].filters[] 아래에 연결되었는지 확인.
spec.sds.certResource가 비어 있지 않은지 확인.
clusterName이 제공되거나 리스너/게이트웨이 SDS에서 상속될 수 있는지 확인.
호스트 이름 기반 라우팅 검사의 경우 hostnames와 요청 호스트 헤더가 예상 값과 일치하는지 확인.

라우트 구성 배포

kubectl 명령으로 클러스터에 구성을 적용해 주세요. 다음 명령은 consul 네임스페이스에 구성을 적용해요:

$ kubectl apply -f my-route.yaml -n consul

Kubernetes에서 API 게이트웨이 라우트 정의