HTTPRoute
HTTPRoute는 Service 같은 "부모(parent)" 리소스에 연결되어 해당 리소스로 가는 HTTP 요청을 매칭하는 일련의 규칙을 정의하는 Kubernetes 리소스예요. 이 규칙들은 경로(path), 메서드, 헤더, HTTP 요청의 다른 측면 같은 파라미터를 기반으로 할 수 있어요.
HTTPRoute는 Linkerd 동작의 다양한 측면을 구성하는 데 사용되며, Linkerd의 Gateway API 지원의 일부를 이뤄요.
참고
HTTPRoute 리소스는 Gateway API의 일부이며 Linkerd 전용이 아니에요. 표준 참조 문서는 Gateway API HTTPRoute 문서예요. 이 페이지는 그 문서에 대한 보충 문서로 의도된 것이며, 이 타입이 Linkerd에서 구체적으로 어떻게 사용되는지를 자세히 설명할 거예요.
본문
인바운드 vs 아웃바운드 HTTPRoute
Linkerd에서 HTTPRoute 사용은 두 가지 범주로 나뉘어요: 인바운드 동작 구성과 아웃바운드 동작 구성이에요.
인바운드 동작. Server를 부모 리소스로 하는 HTTPRoute는 해당 Server로 트래픽을 받는 파드로 향하는 인바운드 트래픽에 대한 정책을 구성해요. 인바운드 HTTPRoute는 세밀한 라우트별 인가(authorization) 및 인증(authentication) 정책을 구성하는 데 사용돼요.
아웃바운드 동작. Service를 부모 리소스로 하는 HTTPRoute는 해당 Service의 클라이언트인 파드에 있는 아웃바운드 프록시에 대한 정책을 구성해요. 아웃바운드 정책에는 동적 요청 라우팅, 요청 헤더 추가, 요청 경로 수정, 타임아웃 같은 신뢰성 기능이 포함돼요.
경고
아웃바운드 HTTPRoute와 ServiceProfile은 구성이 겹쳐요. 이전 버전 호환성 때문에 ServiceProfile이 같은 Service를 구성하는 HTTPRoute보다 우선해요. HTTPRoute의 부모 Service에 ServiceProfile이 정의되어 있다면, ServiceProfile이 존재하는 한 프록시는 HTTPRoute 구성 대신 ServiceProfile 구성을 사용해요.
실제 사용법 (Usage in practice)
이 타입들을 실제로 사용할 때는 타입 소유권과 호환 버전을 포함해 Gateway API 문서의 중요한 참고 사항을 확인하세요.
policy.linkerd.io 그룹
이전 Linkerd 버전에서는 Linkerd가 policy.linkerd.io 그룹에서 HTTPRoute 리소스의 변형을 제공했어요. 이 버전은 여전히 지원되지만 적극적으로 유지관리되지는 않아요. 표준 gateway.networking.kubernetes.io 리소스로 전환하는 것을 권장해요.
HTTPRoute 스펙 (HTTPRoute Spec)
HTTPRoute 스펙은 다음과 같은 최상위 필드를 포함할 수 있어요:
| field | value |
|---|---|
| field | value |
| parentRefs | A set of ParentReferences which indicate which [Server]s or Services this HTTPRoute attaches to. |
| hostnames | A set of hostnames that should match against the HTTP Host header. |
| rules | An array of HTTPRouteRules. |
parentReference
이 HTTPRoute가 속한 부모 리소스에 대한 참조예요.
HTTPRoute를 Server에 연결하면 해당 Server에서 제공되는 특정 라우트에 대한 인가 정책을 정의할 수 있어요.
HTTPRoute를 Service에 연결하면 경로, 헤더, 쿼리 파라미터, 그리고/또는 동사에 따라 요청을 라우팅할 수 있어요. 이후 요청을 다른 백엔드 서비스로 재라우팅할 수 있어요. 이것으로 동적 요청 라우팅을 수행할 수 있어요.
ParentReference는 네임스페이스로 범위가 지정되며, HTTPRoute와 같은 네임스페이스의 부모나 다른 네임스페이스의 부모를 참조할 수 있어요. GEP-1426에 설명된 대로, HTTPRoute와 같은 네임스페이스의 Service를 참조하는 parentRef가 있는 HTTPRoute를 producer route라 하고, 다른 네임스페이스의 Service를 참조하는 parentRef가 있는 HTTPRoute를 consumer route라 해요. producer route는 모든 네임스페이스의 클라이언트에서 시작된 요청에 적용돼요. 반면 consumer route는 HTTPRoute의 네임스페이스에서 시작된 트래픽에만 적용되도록 범위가 제한돼요. producer/consumer route에 대한 자세한 내용은 GEP-1426의 "Namespace boundaries" 섹션을 참고하세요.
| field | value |
|---|---|
| field | value |
| group | The group of the referent. This must either be "policy.linkerd.io" (for Server) or "core" (for Service). |
| kind | The kind of the referent. This must be either "Server" or "Service". |
| port | The targeted port number, when attaching to Services. |
| namespace | The namespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route. |
| name | The name of the referent. |
HTTPRouteRule
HTTPRouteRule은 조건(matches)을 기반으로 HTTP 요청을 매칭하고 필터(filters)로 처리하는 의미론을 정의해요.
| field | value |
|---|---|
| field | value |
| matches | A list of HTTPRouteMatch resources. Each match is independent, i.e. this rule will be matched if any one of the matches is satisfied. |
| filters | A list of HTTPRouteFilter resources which will be applied to each request which matches this rule. |
| backendRefs | An array of HTTPBackendRef resources to declare where the traffic should be routed to (only allowed with Service parentRefs). |
| timeouts | An optional HTTPRouteTimeouts object which configures timeouts for requests matching this rule. |
HTTPRouteMatch
HTTPRouteMatch는 요청을 주어진 동작에 매칭하는 데 사용되는 술어(predicate)를 정의해요. 여러 매치 타입은 AND로 결합돼요. 즉 모든 조건이 충족될 때만 매치가 true로 평가돼요.
| field | value |
|---|---|
| field | value |
| path | An HTTPPathMatch. If this field is not specified, a default prefix match on the "/" path is provided. |
| headers | A list of HTTPHeaderMatch resources. Multiple match values are ANDed together. |
| queryParams | A list of HTTPQueryParamMatch resources. Multiple match values are ANDed together. |
| method | When specified, this route will be matched only if the request has the specified method. |
HTTPPathMatch
HTTPPathMatch는 HTTP 요청 경로를 매칭해서 HTTP 라우트를 선택하는 방법을 설명해요.
| field | value |
|---|---|
| field | value |
| type | How to match against the path Value. One of: Exact, PathPrefix, RegularExpression. If this field is not specified, a default of "PathPrefix" is provided. |
| value | The HTTP path to match against. |
HTTPHeaderMatch
HTTPHeaderMatch는 HTTP 요청 헤더를 매칭해서 HTTP 라우트를 선택하는 방법을 설명해요.
| field | value |
|---|---|
| field | value |
| type | How to match against the value of the header. One of: Exact, RegularExpression. If this field is not specified, a default of "Exact" is provided. |
| name | The HTTP Header to be matched against. Name matching MUST be case insensitive. |
| value | Value of HTTP Header to be matched. |
HTTPQueryParamMatch
HTTPQueryParamMatch는 HTTP 쿼리 파라미터를 매칭해서 HTTP 라우트를 선택하는 방법을 설명해요.
| field | value |
|---|---|
| field | value |
| type | How to match against the value of the query parameter. One of: Exact, RegularExpression. If this field is not specified, a default of "Exact" is provided. |
| name | The HTTP query param to be matched. This must be an exact string match. |
| value | Value of HTTP query param to be matched. |
HTTPRouteFilter
HTTPRouteFilter는 요청 또는 응답 수명 주기 동안 완료되어야 하는 처리 단계를 정의해요.
| field | value |
|---|---|
| field | value |
| type | One of: RequestHeaderModifier, ResponseHeaderModifier, or RequestRedirect. |
| requestHeaderModifier | An HTTPHeaderFilter which modifies request headers. |
| responseHeaderModifier | An HTTPHeaderFilter which modifies response headers. |
| requestRedirect | An HTTPRequestRedirectFilter. |
HTTPHeaderFilter
HTTP 요청 또는 응답 헤더를 수정하는 필터예요.
| field | value |
|---|---|
| field | value |
| set | A list of HTTPHeader resources to overwrite on the request or response. |
| add | A list of HTTPHeader resources to add on to the request or response, appending to any existing value. |
| remove | A list of header names to remove from the request or response. |
HTTPHeader
HTTPHeader는 RFC 7230에서 정의된 HTTP 헤더 이름과 값을 나타내요.
| field | value |
|---|---|
| field | value |
| name | Name of the HTTP Header to be matched. Name matching MUST be case insensitive. |
| value | Value of HTTP Header to be matched. |
HTTPRequestRedirectFilter
HTTPRequestRedirect는 요청을 리다이렉트하는 필터를 정의해요.
| field | value |
|---|---|
| field | value |
| scheme | The scheme to be used in the value of the Location header in the response. When empty, the scheme of the request is used. |
| hostname | The hostname to be used in the value of the Location header in the response. When empty, the hostname of the request is used. |
| path | An HTTPPathModifier which modifies the path of the incoming request and uses the modified path in the Location header. |
| port | The port to be used in the value of the Location header in the response. When empty, port (if specified) of the request is used. |
| statusCode | The HTTP status code to be used in response. |
HTTPPathModifier
HTTPPathModifier는 경로 수정자(path modifier)에 대한 구성을 정의해요.
| field | value |
|---|---|
| field | value |
| type | One of: ReplaceFullPath, ReplacePrefixMatch. |
| replaceFullPath | The value with which to replace the full path of a request during a rewrite or redirect. |
| replacePrefixMatch | The value with which to replace the prefix match of a request during a rewrite or redirect. |
HTTPBackendRef
HTTPBackendRef는 매칭된 요청을 보내야 할 객체 목록을 정의해요. 라우트가 Service parentRef를 가질 때만 허용돼요.
| field | value |
|---|---|
| field | value |
| name | Name of service for this backend. |
| port | Destination port number for this backend. |
| namespace | Namespace of service for this backend. |
| weight | Proportion of requests sent to this backend. |
HTTPRouteTimeouts
HTTPRouteTimeouts는 HTTP 요청에 대해 구성할 수 있는 타임아웃을 정의해요.
Linkerd는 GEP-1742에서 설명한 대로 HTTPRoute 타임아웃을 구현해요. 타임아웃 기간은 GEP-2257이 지정한 Gateway API 기간 포맷(예: 1h/1m/1s/1ms)을 사용해 문자열로 지정되며, 최소 1ms여야 해요. 기간이 0인 타임아웃 필드는 해당 타임아웃을 비활성화해요.
| field | value |
|---|---|
| field | value |
| request | Specifies the duration for processing an HTTP client request after which the proxy will time out if unable to send a response. When this field is unspecified or 0, the proxy will not enforce request timeouts. |
| backendRequest | Specifies a timeout for an individual request from the proxy to a backend service. This covers the time from when the request first starts being sent from the proxy to when the response has been received from the backend. When this field is unspecified or 0, the proxy will not enforce a backend request timeout, but may still enforce the request timeout, if one is configured. |
재시도(retries)가 활성화되어 있으면 프록시가 받은 요청을 다른 백엔드로 보내 재시도할 수 있어요. 이 경우 각 재시도 요청마다 새 backendRequest 타임아웃이 시작되지만, 각 재시도 요청은 전체 request 타임아웃에 계산돼요.
HTTPRoute 예시 (HTTPRoute Examples)
/authors.json 또는 /authors/*에 대한 GET을 매칭하는, Server 리소스에 연결된 HTTPRoute:
`apiVersion: policy.linkerd.io/v1beta2
kind: HTTPRoute
metadata:
name: authors-get-route
namespace: booksapp
spec:
parentRefs:
- name: authors-server
kind: Server
group: policy.linkerd.io
rules:
- matches:
- path:
value: "/authors.json"
method: GET
- path:
value: "/authors/"
type: "PathPrefix"
method: GET
`
헤더 기반 라우팅을 수행하도록 Service에 연결된 HTTPRoute. 요청에 x-faces-user: testuser 헤더가 있으면 요청이 smiley2 백엔드 Service로 라우팅돼요. 그렇지 않으면 smiley 백엔드 Service로 라우팅돼요.
`apiVersion: policy.linkerd.io/v1beta2
kind: HTTPRoute
metadata:
name: smiley-a-b
namespace: faces
spec:
parentRefs:
- name: smiley
kind: Service
group: core
port: 80
rules:
- matches:
- headers:
- name: "x-faces-user"
value: "testuser"
backendRefs:
- name: smiley2
port: 80
- backendRefs:
- name: smiley
port: 80
`