NGINX Gateway Fabric 리소스 검증

이 문서는 NGINX Gateway Fabric의 Gateway API, NGINX Gateway Fabric Kubernetes 리소스 검증 방법에 관해 설명합니다.

목차

1. Gateway API 리소스 검증
 1-1. 1단계: Kubernetes API Server의 OpenAPI 스키마 검증
 1-2. 2단계: Kubernetes API Server의 CEL 검증
 1-3. 3단계: NGINX Gateway Fabric의 리소스 검증
 1-4. Gateway API 리소스 검증 확인
2. NGINX Gateway Fabric 리소스 검증
 2-1. 1단계: Kubernetes API Server의 OpenAPI 스키마 검증
 2-2. 2단계: NGINX Gateway Fabric의 리소스 검증
 2-3. NGINX Gateway Fabric 리소스 검증 확인

1. Gateway API 리소스 검증

NGINX Gateway Fabric은 다양한 이유로 Gateway API 리소스를 검증합니다.

  • 견고성 : 유효하지 않은 리소스를 graceful 하게 처리
  • 보안 : 공격성 입력이 NGINX 설정으로 전파되는 것을 방지
  • 정확성 : 유효하지 않은 리소스를 처리하기 위해 Gateway API 사양 준수

이 프로세스는 이 문서에서 자세히 설명된 네 가지 단계를 포함하며, 유효하지 않은 Gateway API 리소스가 생성되더라도 NGINX가 트래픽을 계속 처리할 수 있도록 하는 것을 목표로 합니다.

1-1. 1단계: Kubernetes API Server의 OpenAPI 스키마 검증

Kubernetes API 서버는 Gateway API CRDs에 포함된 OpenAPI 스키마를 기반으로 Gateway API 리소스를 검증합니다. 예를 들어, “cafe.!@#$%example.com”와 같이 유효하지 않은 호스트 이름을 포함하는 HTTPRoute를 생성한 경우, API 서버는 다음 에러와 함께 거절합니다.

$ kubectl apply -f coffee-route.yaml

The HTTPRoute "coffee" is invalid: spec.hostnames[0]: Invalid value: "cafe.!@#$%example.com": spec.hostnames[0] in body should match '^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'

Note:

가능성이 작지만, Gateway API CRDs가 검증을 제거하도록 수정된 경우 이 유효성 검사 단계를 우회할 수 있습니다. 이 경우 4단계는 NGINX 관점에서 유효하지 않은 값을 거부합니다.
1-2. 2단계: Kubernetes API Server의 CEL 검증

Kubernetes API 서버는 Gateway API CRDs에 포함된 CEL 검증을 기반으로 Gateway API 리소스를 검증합니다. OpenAPI 스키마 검증에서 사용할 수 없는 고급 규칙을 사용하여 Gateway API 리소스를 검증합니다. 예를 들어, 호스트 이름을 설정하는 TCP listener가 포함된 Gateway 리소스를 생성하는 경우, CEL 검증에서 다음 에러와 함께 거절합니다.

$ kubectl apply -f some-gateway.yaml

The Gateway "some-gateway" is invalid: spec.listeners: Invalid value: "array": hostname must not be specified for protocols ['TCP', 'UDP']

Kubernetes의 CEL 에 대한 더 많은 정보는 여기에서 확인하실 수 있습니다.

1-3. 3단계: NGINX Gateway Fabric 의 리소스 검증

이 단계는 다음과 같은 유효하지 않은 값을 포착합니다.

  • Gateway API 기준으로 유효하지만, NGINX Gateway Fabric에서 아직 지원하지 않는 값인 경우. 예를 들어, HTTPRoute의 라우팅 규칙 기능. 지원되는 기능 목록은 Gateway API 호환성 문서를 참고하세요.
  • Gateway API 기준으로 유효하지만, NGINX에서 유효하지 않은 경우. NGINX는 특정 필드에 대해 더 엄격한 검증 요구 사항을 가지고 있습니다. 이러한 값들은 NGINX가 reload에 실패하거나 동작하지 않도록 합니다.
  • 1단계가 생략되어 Gateway API, NGINX 기준 모두 유효하지 않은 값인 경우. 이러한 값들은 NGINX가 reload에 실패하거나 동작하지 않도록 합니다.
  • NGINX 설정에 제한 없는 NGINX 설정값을 주입하는 악의적인 값들(SQL 인젝션 공격과 유사).

아래는 NGINX Gateway Fabric이 유효하지 않은 값을 거부하는 예입니다. 검증 에러는 다음과 같은 상태로 보고됩니다.

$ kubectl describe httproutes.gateway.networking.k8s.io coffee

. . .
Status:
  Parents:
    Conditions:
      Last Transition Time:  2023-03-30T22:37:53Z
      Message:               All rules are invalid: spec.rules[0].matches[0].method: Unsupported value: "CONNECT": supported values: "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"
      Observed Generation:   1
      Reason:                UnsupportedValue
      Status:                False
      Type:                  Accepted
    Controller Name:         gateway.nginx.org/nginx-gateway-controller
    Parent Ref:
      Group:         gateway.networking.k8s.io
      Kind:          Gateway
      Name:          prod-gateway
      Namespace:     default
      Section Name:  http

Note:

이 검증 단계는 항상 실행되며 우회할 수 없습니다.
1-4. Gateway API 리소스 검증 확인

리소스가 유효하고 NGINX Gateway Fabric에 의해 허용되는지 확인하려면, 리소스 상태의 Accepted 조건에서 Status 필드가 True로 설정되어 있는지 확인하세요. 예를 들어, HTTPRoute가 유효한 상태에서 NGINX Gateway Fabric가 parentRef를 허용하면 parentRef의 상태는 다음과 같습니다.

Status:
  Parents:
    Conditions:
      Last Transition Time:  2023-03-30T23:18:00Z
      Message:               The route is accepted
      Observed Generation:   2
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
    Controller Name:         gateway.nginx.org/nginx-gateway-controller
    Parent Ref:
      Group:         gateway.networking.k8s.io
      Kind:          Gateway
      Name:          gateway
      Namespace:     default
      Section Name:  http

Note:

보고된 observed generation 값이 resource generation 값과 동일한지 확인하세요.

2. NGINX Gateway Fabric 리소스 검증

2-1. 1단계: Kubernetes API Server의 OpenAPI 스키마 검증

Kubernetes API 서버는 NGINX Gateway Fabric CRDs에 포함된 OpenAPI 스키마를 기반으로 NGINX Gateway Fabric 리소스를 검증합니다. 예를 들어, “some-level”과 같이 유효하지 않은 로깅 레벨을 포함하는 NginxGateway를 생성하는 경우, API 서버는 다음 에러와 함께 거절합니다.

$ kubectl apply -f nginx-gateway-config.yaml

The NginxGateway "nginx-gateway-config" is invalid: spec.logging.level: Unsupported value: "some-level": supported values: "info", "debug", "error"

Note:

가능성이 작지만, NGINX Gateway Fabric CRDs가 검증을 제거하도록 수정된 경우 이 유효성 검사 단계를 우회할 수 있습니다. 이 경우 2단계에서 리소스의 상태에 오류가 보고됩니다.
2-2. 2단계: NGINX Gateway Fabric의 리소스 검증

이 단계는 NGINX Gateway Fabric CRDs의 상태를 검증하고 유효하지 않은 리소스를 거부합니다. 검증 에러는 상태와 이벤트를 통해 보고됩니다. 예를 들어:

$ kubectl describe nginxgateways.gateway.nginx.org nginx-gateway-config

상태:

...
Status:
  Conditions:
    Last Transition Time:  2023-12-15T21:02:30Z
    Message:               Failed to update control plane configuration: logging.level: Unsupported value: "some-level": supported values: "info", "debug", "error"
    Observed Generation:   1
    Reason:                Invalid
    Status:                False
    Type:                  Valid

이벤트:

Warning  UpdateFailed  1s (x2 over 1s)  nginx-gateway-fabric-nginx  Failed to update control plane configuration: logging.level: Unsupported value: "some-level": supported values: "info", "debug", "error"
2-3. NGINX Gateway Fabric 리소스 검증 확인

리소스가 유효하고 NGINX Gateway Fabric에 의해 허용되었는지 확인하려면, 리소스 상태의 Valid 조건에서 Status 필드가 True로 설정되어 있는지 확인하세요. 예를 들어, 유효한 NginxGateway의 상태는 다음과 같이 나타납니다:

Status:
  Conditions:
    Last Transition Time:  2023-12-15T21:04:49Z
    Message:               NginxGateway is valid
    Observed Generation:   1
    Reason:                Valid
    Status:                True
    Type:                  Valid

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required