경로(Route) 리소스 구성 참조

경로(Route) 리소스 구성 참조 (Route Resource Configuration Reference)

이 주제는 Route 리소스를 만들고 구성하는 방법을 설명해요. 경로는 특정 리스너와 연결되는 독립적인 구성 객체예요.

출처: 문서

본문

구성 모델 (Configuration model)

다음 개요는 Route 객체의 구성을 형식화하는 방법을 보여줘요. 최상위 spec 필드는 모든 구성의 루트예요. 속성 이름을 클릭해 구성에 대한 세부 정보를 확인할 수 있어요.

사양 (Specification)

이 주제는 구성 매개변수에 대한 세부 정보를 제공해요.

parentRefs

이 필드는 경로가 연결되어야 하는 Gateways 목록을 포함해요. 설정하지 않으면 경로는 Gateway에 연결되지 않아요. 다음 표는 parentRefs 블록에서 구성할 수 있는 객체를 설명해요:

매개변수 설명 유형 필수
group 연결할 Gateway의 Kubernetes API 그룹을 지정해요. 다음 값을 지정할 수 있어요: \n\n * gateway.networking.k8s.io \n\n. 기본값은 gateway.networking.k8s.io예요. String 선택
kind 연결할 Gateway의 Kubernetes kind를 지정해요. 다음 값을 지정할 수 있어요: \n\n * Gateway \n\n. 기본값은 Gateway예요. String 선택
name 경로가 연결되는 Gateway의 이름을 지정해요. String 필수
namespace 연결할 Gateway가 포함된 Kubernetes 네임스페이스를 지정해요. Gateway가 Route와 다른 Kubernetes 네임스페이스에 있는 경우 값을 지정해야 해요. 기본값은 Route 네임스페이스예요. String 선택
sectionName 연결할 Gateway의 특정 리스너 이름을 지정해요. Route는 Gateway의 모든 리스너에 연결을 시도해요. String 필수

rules

rules 필드는 경로를 통과하는 네트워크 트래픽에 대한 동작을 정의하는 객체 목록을 포함해요. 규칙 구성은 다음 객체를 포함해요:

  • backendRefs: Route가 트래픽을 처리할 때 참조하는 백엔드 서비스를 지정해요.
  • filters: 트래픽이 Route를 통과할 때 Consul API gateway가 수행하는 작업을 지정해요.
  • matches: Consul API gateway가 처리하는 요청을 결정해요.

규칙은 선택사항이에요.

rules.backendRefs

이 필드는 Route가 참조하는 백엔드 서비스를 지정해요. 다음 표는 backendRefs의 매개변수를 설명해요:

매개변수 설명 유형 필수
group 참조된 백엔드의 Kubernetes API 그룹을 지정해요. 다음 값을 지정할 수 있어요: \n\n * "": 핵심 Kubernetes API 그룹을 지정해요. kind가 Service로 설정된 경우 이 값을 사용해야 해요. 지정하지 않으면 기본값이에요. \n * consul.hashicorp.com: kind가 MeshService로 설정된 경우 이 값을 사용해야 해요. \n String 선택
kind 참조된 백엔드의 Kubernetes Kind를 지정해요. 다음 값을 지정할 수 있어요: \n\n * Service (default): backendRef가 Kubernetes 클러스터의 Service를 참조함을 나타내요. \n * MeshService: backendRef가 Consul 메시의 서비스를 참조함을 나타내요. 추가 정보는 MeshService 문서를 참고해요. \n String 선택
name Kubernetes Service 또는 Consul 메시 서비스 리소스의 이름을 지정해요. String 필수
namespace Kubernetes Service 또는 Consul 메시 서비스 리소스가 포함된 Kubernetes 네임스페이스를 지정해요. Service 또는 Consul 메시 서비스가 Route와 다른 네임스페이스에 정의된 경우 값을 지정해야 해요. 기본값은 Route의 네임스페이스예요. \n 다른 네임스페이스의 backendRef에 대한 경로를 만들려면 ReferenceGrant도 만들어야 해요. 네임스페이스 간 참조로 구성된 예시 경로를 참고해요. String 선택
port Kubernetes 또는 Consul 서비스에 접근하기 위한 포트 번호를 지정해요. Integer 필수
weight 백엔드로 전송되는 요청의 비율을 지정해요. 이 backendRefs 목록의 모든 가중치 합계로 나눈 가중치로 계산돼요. 기본값은 1이에요. 0 값은 백엔드로 요청을 보내지 않아야 함을 나타내요. Integer 선택

HTTPRoute 규칙에 backendRef가 하나 있는 경우 Consul API gateway는 백엔드 서비스의 Consul 디스커버리 체인(discovery chain)을 평가해요. 백엔드 서비스가 ServiceRouter를 사용해 요청을 ServiceResolver 하위 집합으로 라우팅하면 Consul은 API gateway 디스커버리 체인을 합성할 때 하위 집합 대상을 유지해요. Consul은 게이트웨이 경로 일치와 서비스 라우터 일치를 결합하므로 요청이 하위 집합 경로를 사용하려면 두 기준 집합을 모두 충족해야 해요.

예시 구성은 Example cross-namespace backendRef를 참고해요.

rules.filters

filters 블록은 요청 처리 단계를 정의해요. 필터를 구성해 일치하는 수신 요청의 속성을 수정하고 경로 접두사 재작성 같은 Consul API gateway 기능(추가 정보는 Reroute HTTP requests 참조)을 활성화할 수 있어요.

  • 유형: objects 배열
  • 필수: 선택

rules.filters.type

경로에 적용하려는 필터 유형을 지정해요. 이 매개변수는 선택사항이며 문자열 값을 취해요.

다음 값을 지정할 수 있어요:

rules.filters.requestHeaderModifier

rules.filters.type이 RequestHeaderModifier로 구성된 경우 일치하는 요청 헤더에서 수행할 작업을 정의해요. 이 필드는 다음 구성 객체를 포함해요:

매개변수 설명 유형 필수
set HTTP 요청 헤더를 재작성하도록 이 필드를 구성해요. 덮어쓸 HTTP 헤더의 이름과 설정할 새 값을 지정해요. 헤더 이름과 관련된 기존 값은 모두 덮어써져요. 다음 구성을 지정할 수 있어요: \n\n * name: 설정할 HTTP 헤더의 이름을 지정하는 필수 문자열. \n * value: 설정할 HTTP 헤더의 값을 지정하는 필수 문자열. \n objects 목록 선택
add 요청 헤더에 새 값을 추가하도록 이 필드를 구성해요. 추가할 HTTP 헤더의 이름과 추가할 값(들)을 지정해요. 다음 구성을 지정할 수 있어요: \n\n * name: 추가할 HTTP 헤더의 이름을 지정하는 필수 문자열. \n * value: 추가할 HTTP 헤더의 값을 지정하는 필수 문자열. \n objects 목록 선택
remove 요청 헤더에서 제거할 헤더 이름 배열을 지정하도록 이 필드를 구성해요. strings 배열 선택

rules.filters.responseHeaderModifier

rules.filters.type이 ResponseHeaderModifier로 구성된 경우 일치하는 응답 헤더에서 수행할 작업을 정의해요. 이 필드는 다음 구성 객체를 포함해요:

매개변수 설명 유형 필수
set HTTP 응답 헤더를 재작성하도록 이 필드를 구성해요. 덮어쓸 HTTP 헤더의 이름과 설정할 새 값을 지정해요. 헤더 이름과 관련된 기존 값은 모두 덮어써져요. 다음 구성을 지정할 수 있어요: \n\n * name: 설정할 HTTP 헤더의 이름을 지정하는 필수 문자열. \n * value: 설정할 HTTP 헤더의 값을 지정하는 필수 문자열. \n objects 목록 선택
add 응답 헤더에 새 값을 추가하도록 이 필드를 구성해요. 추가할 HTTP 헤더의 이름과 추가할 값(들)을 지정해요. 다음 구성을 지정할 수 있어요: \n\n * name: 추가할 HTTP 헤더의 이름을 지정하는 필수 문자열. \n * value: 추가할 HTTP 헤더의 값을 지정하는 필수 문자열. \n objects 목록 선택
remove 응답 헤더에서 제거할 헤더 이름 배열을 지정하도록 이 필드를 구성해요. strings 배열 선택

rules.filters.urlRewrite

rules.filters.type이 URLRewrite로 구성된 경우 수신 요청의 URL을 재작성하는 규칙을 지정해요.

  • 유형: Object
  • 필수: 선택

rules.filters.urlRewrite.path

Consul API gateway가 URL 경로를 재작성하는 방법을 결정하는 객체 목록을 지정해요(추가 정보는 Reroute HTTP requests 참조).

다음 표는 path의 매개변수를 설명해요:

매개변수 설명 유형 필수
replacePrefixMatch 수신 HTTP 요청의 경로 접두사를 대체하는 값을 지정해요. 이 작업은 경로 접두사에만 영향을 미쳐요. 나머지 경로는 변경되지 않아요. String 필수
type URL 경로에 사용할 대체 유형을 지정해요. 다음 값을 지정할 수 있어요: \n\n * ReplacePrefixMatch: URL 경로의 일치하는 접두사를 대체해요 (default). \n String 선택

rules.filters.extensionRef

rules.filters.type이 ExtensionRef로 설정된 경우 HTTP 경로에 확장 참조를 연결하는 맵이에요. 경로에 대한 요청의 JWT 검증 정의 같은 서로 다른 동작을 활성화하는 확장을 만들고 경로에 연결할 수 있어요.

다음 매개변수를 구성할 수 있어요:

매개변수 설명 데이터 유형 기본값
group 리소스 그룹을 지정해요. String 없음
kind 확장 참조 유형을 지정해요. 다음 유형을 지정할 수 있어요: \n\n * RouteAuthFilter: JWT 검증 설정을 포함해요. 추가 정보는 Use JWTs to verify requests to API gateways on Kubernetes를 참고해요. \n * RouteRetryFilter: 요청이 실패한 경우 경로에 대한 재시도 로직을 정의해요. 추가 정보는 RouteRetryFilter configuration reference를 참고해요. \n * RouteTimeoutFilter: 특정 경로에 대한 타임아웃 설정을 지정해요. 추가 정보는 RouteTimeoutFilter configuration reference를 참고해요. \n * RouteExtProc: 경로와 일치하는 요청에 대한 ext-proc Envoy 확장을 비활성화하거나 재정의해요. 추가 정보는 RouteExtProc configuration reference를 참고해요. \n String 없음
name 경로에 연결할 필터의 이름을 지정해요. String 없음

rules.matches

수신 요청을 일치시키기 위한 규칙을 지정해요. 정의된 규칙과 일치하는 요청에 filters를 적용할 수 있어요. 다음 요소를 기반으로 수신 요청을 일치시킬 수 있어요:

각 규칙은 요청을 독립적으로 일치시켜요. 그 결과, 조건 중 하나와 일치하는 요청은 일치로 간주돼요. 일치를 넓히거나 좁히기 위해 각 유형에 대해 여러 일치 규칙을 구성할 수 있어요.

rules.matches.path

URL 경로를 기반으로 일치 항목을 정의하는 객체 목록을 지정해요. 다음 표는 path 필드의 매개변수를 설명해요:

매개변수 설명 유형 필수
type 경로 값을 일치시키는 데 사용할 비교 유형을 지정해요. 다음 유형을 지정할 수 있어요. \n\n * Exact: 전체 경로가 value 필드와 일치할 때만 일치를 반환해요 (default). \n * PathPrefix: 경로가 value 필드에 정의된 접두사를 가질 때 일치를 반환해요. \n * RegularExpression: 경로가 value 필드에 정의된 regex와 일치할 때 일치를 반환해요. \n String 필수
value 일치시킬 값을 지정해요. type이 Exact 또는 PathPrefix일 때 특정 문자열을 지정할 수 있어요. type이 RegularExpression이면 정규식을 지정할 수 있어요. String 필수

rules.matches.headers

HTTP 요청 헤더를 기반으로 일치 항목을 정의하는 객체 목록을 지정해요. 다음 표는 headers 필드의 매개변수를 설명해요:

매개변수 설명 유형 필수
type 헤더 값을 일치시키는 데 사용할 비교 유형을 지정해요. 다음 유형을 지정할 수 있어요. \n\n * Exact: 전체 헤더가 value 필드와 일치할 때만 일치를 반환해요 (default). \n * RegularExpression: 헤더가 value 필드에 정의된 regex와 일치할 때 일치를 반환해요. \n String 필수
name 일치시킬 헤더의 이름을 지정해요. String 필수
value 일치시킬 값을 지정해요. 특정 문자열 또는 정규식을 지정할 수 있어요. String 필수

rules.matches.queryParams

쿼리 매개변수를 기반으로 일치 항목을 정의하는 객체 목록을 지정해요. 다음 표는 queryParams 필드의 매개변수를 설명해요:

매개변수 설명 유형 필수
type 쿼리 매개변수 값을 일치시키는 데 사용할 비교 유형을 지정해요. 다음 유형을 지정할 수 있어요. \n\n * Exact: 쿼리 매개변수가 value 필드와 일치할 때만 일치를 반환해요 (default). \n * RegularExpression: 쿼리 매개변수가 value 필드에 정의된 regex와 일치할 때 일치를 반환해요. \n String 필수
name 일치시킬 쿼리 매개변수의 이름을 지정해요. String 필수
value 일치시킬 값을 지정해요. 특정 문자열 또는 정규식을 지정할 수 있어요. String 필수

rules.matches.method

HTTP 요청 메서드를 기반으로 일치 항목을 정의하는 문자열 목록을 지정해요. 다음 값을 지정할 수 있어요:

예시 (Examples)

추가 정보는 다음 Consul 및 Kubernetes Gateway API 문서를 참고해요:

기본 경로 (Basic route)

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

routes.yaml:

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

서비스 하위 집합으로 경로 (Route to a service subset)

다음 예시는 api 서비스에 대한 stable 및 canary 하위 집합을 만들어요. ServiceRouter는 x-version: canary 헤더가 있는 요청을 canary 하위 집합으로 라우팅해요. HTTPRoute는 example-gateway를 통해 api 서비스를 노출해요; Consul API gateway는 일치하는 요청을 백엔드 서비스로 라우팅할 때 서비스 라우터 규칙을 적용해요.

route_to_service_subset.yaml:

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/v1
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

교차 네임스페이스 backendRef 예시 (Example cross-namespace backendRef)

다음 예시는 gateway-namespace 네임스페이스에 example-route라는 경로를 만들어요. 이 경로에는 service-namespace 네임스페이스에 backendRef가 있어요. service-namespace에 있는 reference-grant라는 ReferenceGrant가 gateway-namespace의 HTTPRoutes에서 service-namespace의 Services로의 트래픽을 허용하므로 트래픽이 허용돼요.

route_with_referencegrant.yaml:

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

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: reference-grant
  namespace: service-namespace
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: gateway-namespace
    to:
      - group: ""
        kind: Service
        name: echo

더 알아보기 (Learn more)