Gateway 리소스 구성 참조

Gateway 리소스 구성 참조 (Gateway Resource Configuration Reference)

이 주제는 Gateway 리소스에 대한 전체 세부 정보를 제공해요.

출처: 문서

본문

소개 (Introduction)

Gateway는 서비스 트래픽을 처리하는 방법을 결정하는 네트워크 인프라 인스턴스예요. Gateway에는 IP 주소 집합에 바인딩되는 하나 이상의 listeners가 포함돼요. 그런 다음 HTTPRoute 또는 TCPRoute는 게이트웨이 리스너에 연결되어 게이트웨이에서 서비스로 트래픽을 전달할 수 있어요.

Gateway 인스턴스는 개별 Gateway 배포의 템플릿 역할을 하는 GatewayClass 리소스에서 구성을 파생해요. 추가 정보는 GatewayClass를 참고해요.

Gateway를 선언하려면 다음 매개변수를 지정해요:

매개변수	설명	필수
kind	구성 객체의 유형을 지정해요. 값은 항상 Gateway여야 해요.	필수
description	Gateway의 목적을 설명하는 사람이 읽을 수 있는 문자열.	선택
version	Kubernetes API 버전을 지정해요. 값은 gateway.networking.k8s.io/v1 또는 consul.hashicorp.com/v1beta1이어야 해요.	필수
scope	Gateway의 유효 범위를 지정해요. 값은 항상 namespaced여야 해요.	필수
fields	Gateway에 대한 구성을 지정해요. 필드는 구성 모델에 나열되어 있어요. 각 필드에 대한 세부 정보는 사양에 설명되어 있어요.	필수

구성 모델 (Configuration model)

다음 개요는 Gateway 객체의 구성 형식을 지정하는 방법을 보여줘요. 속성 이름을 클릭해 구성에 대한 세부 정보를 확인할 수 있어요.

• gatewayClassName: string | 필수
• listeners: objects 배열 | 필수
  • allowedRoutes: object | 필수
    • namespaces: object | 필수
      • from: string | 필수
      • selector: object | from이 selector로 구성된 경우 필수
        • matchExpressions: objects 배열 | matchLabels가 구성되지 않은 경우 필수
          • key: string | matchExpressions가 선언된 경우 필수
          • operator: string | matchExpressions가 선언된 경우 필수
          • values: strings 배열 | matchExpressions가 선언된 경우 필수
        • matchLabels: strings map | matchExpressions가 구성되지 않은 경우 필수
  • hostname: string | 필수
  • name: string | 필수
  • port: integer | 필수
  • protocol: string | 필수
  • tls: object | protocol이 HTTPS로 설정된 경우 필수
    • certificateRefs: objects 배열 | tls가 선언된 경우 필수
      • name: string | certificateRefs가 선언된 경우 필수
      • namespace: string | certificateRefs가 선언된 경우 필수
    • mode: string | certificateRefs가 선언된 경우 필수
    • options: strings map | 선택

사양 (Specification)

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

gatewayClassName

Gateway 인스턴스에 사용되는 GatewayClass 리소스의 이름을 지정해요. 사용자 지정 GatewayClass를 사용하지 않는 한 이 값은 consul로 설정해야 해요.

• 유형: string
• 필수: 필수

listeners

Gateway와 연결된 listeners를 지정해요. 최소한 하나의 listener를 지정해야 해요. Gateway 내의 각 listener는 고유한 hostname, port, protocol 조합을 가져야 해요.

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

listeners.allowedRoutes

리스너에 연결될 수 있는 경로 유형을 정의하는 namespace 객체를 지정해요.

• 유형: object
• 필수: 필수

listeners.allowedRoutes.namespaces

listener에 연결할 수 있는 경로를 결정해요. 기본적으로 Gateway와 동일한 네임스페이스의 경로만 연결될 수 있어요.

• 유형: string
• 필수: 선택
• 기본값: 상위 Gateway와 동일한 네임스페이스

listeners.allowedRoutes.namespaces.from

Gateway에 경로를 연결할 수 있는 네임스페이스를 결정해요. 다음 문자열 중 하나를 지정할 수 있어요:

• All: 모든 네임스페이스의 경로가 Gateway에 연결될 수 있어요.
• Same (default): Gateway와 동일한 네임스페이스의 경로만 연결될 수 있어요.
• Selector: selector와 일치하는 네임스페이스의 경로만 연결될 수 있어요.

이 매개변수는 필수예요.

listeners.allowedRoutes.namespaces.selector

리스너에 연결할 수 있는 경로를 선택하는 방법을 지정해요. Gateway는 정규식 또는 레이블과 일치하는 네트워크의 네임스페이스를 확인해요. 일치하는 네임스페이스의 경로는 리스너에 연결할 수 있어요.

다음 객체 중 하나를 구성할 수 있어요:

• matchExpressions
• matchLabels

이 필드는 from이 Selector로 구성된 경우 필수예요.

listeners.allowedRoutes.namespaces.selector.matchExpressions

네임스페이스 일치를 위한 요구 사항 배열을 지정해요. 일치 항목이 발견되면 일치하는 네임스페이스의 경로가 Gateway에 연결될 수 있어요. 다음 표는 matchExpressions 배열의 멤버를 설명해요:

요구 사항	설명	유형	필수
key	key가 적용되는 레이블을 지정해요.	string	matchExpressions가 선언된 경우 필수
operator	키와 값 집합의 관계를 지정해요. 다음 키워드를 사용할 수 있어요: \n\n * In: values 필드에 문자열을 포함하는 네임스페이스의 경로만 Gateway에 연결할 수 있어요. \n * NotIn: values 필드에 문자열을 포함하지 않는 네임스페이스의 경로가 Gateway에 연결될 수 있어요. \n * Exists: key 값을 포함하는 네임스페이스의 경로가 Gateway에 연결될 수 있어요. \n * DoesNotExist: key 값을 포함하지 않는 네임스페이스의 경로가 Gateway에 연결될 수 있어요. \n	string	matchExpressions가 선언된 경우 필수
values	문자열 값 배열을 지정해요. operator가 In 또는 NotIn으로 구성된 경우 values 배열은 값을 포함해야 해요. operator가 Exists 또는 DoesNotExist로 구성된 경우 values 배열은 비어 있어야 해요.	strings 배열	matchExpressions가 선언된 경우 필수

다음 예시에서 foo와 bar를 포함하는 네임스페이스의 경로는 Gateway에 경로를 연결할 수 있어요.

namespaceSelector:
  matchExpressions:
  - key: kubernetes.io/metadata.name
    operator: In
    values:
    - foo
    - bar

matchExpressions에 대한 추가 정보는 Kubernetes 문서의 Labels and Selectors를 참고해요.

listeners.allowedRoutes.namespaces.selector.matchLabels

레이블 및 레이블 값 배열을 지정해요. 일치 항목이 발견되면 일치하는 레이블이 있는 경로가 Gateway에 연결될 수 있어요. 이 선택기는 임의의 키/값 쌍을 포함할 수 있어요.

다음 예시에서 bar 레이블이 있는 네임스페이스의 경로는 Gateway에 연결할 수 있어요.

namespaceSelector:
    matchLabels:
      foo: bar

레이블에 대한 추가 정보는 Kubernetes 문서의 Labels and Selectors를 참고해요.

listeners.hostname

listener의 호스트네임을 지정해요.

• 유형: string
• 필수: 필수

listeners.name

listener의 이름을 지정해요.

• 유형: string
• 필수: 필수

listeners.port

listener가 연결되는 포트 번호를 지정해요.

• 유형: integer
• 필수: 필수

listeners.protocol

listener가 통신하는 프로토콜을 지정해요.

• 유형: string
• 필수: 필수

허용되는 값은 TCP, HTTP 또는 HTTPS예요.

listeners.tls

Gateway에 대한 tls 구성을 지정해요. tls 객체는 protocol이 HTTPS로 설정된 경우 필수예요. 객체에는 다음 필드가 포함돼요:

매개변수	설명	유형	필수
certificateRefs	TLS 인증서와 개인 키가 포함된 Kubernetes name 및 namespace 객체를 지정해요. \n 인증서는 연결된 listener의 hostname과 일치하는 요청에 대한 TLS 핸드셰이크를 설정해요. 각 참조는 Kubernetes Secret이어야 해요. Gateway의 네임스페이스가 아닌 다른 네임스페이스의 Secret을 사용하는 경우 각 참조에는 해당하는 ReferenceGrant도 있어야 해요.	Object 또는 배열	tls가 설정된 경우 필수
mode	TLS 모드를 지정해요. HTTPRoutes의 경우 항상 Terminate로 설정해야 해요.	string	certificateRefs가 설정된 경우 필수
options	추가 Consul API Gateway 옵션을 지정해요.	strings map	선택

options에 사용할 수 있는 키:

• api-gateway.consul.hashicorp.com/tls_min_version
• api-gateway.consul.hashicorp.com/tls_max_version
• api-gateway.consul.hashicorp.com/tls_cipher_suites

다음 예시에서 tls 설정은 Gateway와 동일한 네임스페이스의 consul-server-cert이라는 시크릿을 사용하도록 구성되고 최소 tls 버전은 TLSv1_2로 설정돼요.

tls:
  certificateRefs:
  - name: consul-server-cert
    group: ""
    kind: Secret
  mode: Terminate
  options:
    api-gateway.consul.hashicorp.com/tls_min_version: "TLSv1_2"

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

다음 예시는 gateway-namespace 네임스페이스에 example-gateway라는 Gateway를 만들어요(2-4열). 게이트웨이에는 secret-namespace 네임스페이스에 certificateRef가 있어요(16-18열). secret-namespace의 reference-grant라는 ReferenceGrant 구성(24-27열)이 gateway-namespace의 Gateways가 secret-namespace의 Secrets를 참조하도록 허용하므로(31-35열) 이 참조가 허용돼요.

gateway_with_referencegrant.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: gateway-namespace
spec:
  gatewayClassName: consul
  listeners:
  - protocol: HTTPS
    port: 443
    name: https
    allowedRoutes:
      namespaces:
        from: Same
    tls:
      certificateRefs:
        - name: cert
          namespace: secret-namespace
          group: ""
          kind: Secret
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: reference-grant
  namespace: secret-namespace
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: Gateway
    namespace: gateway-namespace
    to:
    - group: ""
      kind: Secret
      name: cert

더 알아보기 (Learn more)

• GatewayClass 리소스 구성 참조
• Kubernetes Gateway API ReferenceGrant
• Kubernetes Labels and Selectors