NGINX Gateway Fabric Data plane 설정

이 문서는 NGINX Gateway Fabric Data plane 설정을 동적으로 업데이트 하는 방법에 관해 설명합니다.

목차

1. NGINX Gateway Fabric Data plane 개요
2. 설정 조회 및 업데이트
3. 수동으로 설정 생성
4. NGINX Gateway Fabric Data plane log level 설정
5. PROXY 프로토콜과 RewriteClientIP 설정

1. NGINX Gateway Fabric Data plane 개요

NGINX Gateway Fabric은 재시작 없이 동적으로 전역 Data plane 설정을 업데이트 할 수 있습니다.
NGINX Gateway Fabric Data plane 설정은 표준 Gateway API 리소스를 사용하여 구성할 수 없는 NGINX의 전역 설정 옵션입니다. 이러한 설정은 OpenTelemetry collector 설정, http2 비활성화, IP family 변경, NGINX error log level 설정을 포함하고 있습니다.

Data plane 설정은 nginx GatewayClass와 연결된 cluster scope 리소스인 NginxProxy 커스텀 리소스에 저장됩니다.

기본적으로 NginxProxy 리소스는 NGINX Gateway Fabric 설치 시에 생성되지 않습니다. 하지만 Helm을 통해 설치하는 경우 nginx.config Helm values의 설정을 통해 NGINX Gateway Fabric 설치 시 NginxProxy 리소스를 생성하고 연결할 수 있습니다. NGINX Gateway Fabric이 이미 설치된 경우 직접 생성하고 연결할 수 있습니다.

Helm 차트를 통해 설치된 경우, NginxProxy 리소스의 이름은 <release-name>-proxy-config 형식으로 구성됩니다.

구성 가능한 전체 옵션의 경우 API reference의 NginxProxy spec을 확인하세요.

2. 설정 조회 및 업데이트

NginxProxy 리소스가 이미 존재하는 경우, 조회하고 수정할 수 있습니다.

아래 예제의 ngf-proxy-config 이름은 설치 시 구성된 실제 리소스 이름으로 변경하세요.

명령어를 사용하여 현재 설정을 조회합니다.

$ kubectl describe nginxproxies ngf-proxy-config

명령어를 사용하여 설정을 업데이트 합니다.

$ kubectl edit nginxproxies ngf-proxy-config

명령어를 사용하면 설정이 기본 에디터에서 열립니다. 설정을 변경하고 저장하면, 자동으로 data plane에 적용됩니다.

설정의 상태를 확인하려면 연결된 GatewayClass를 확인합니다.

$ kubectl describe gatewayclasses nginx

...
Status:
  Conditions:
     ...
    Message:               parametersRef resource is resolved
    Observed Generation:   1
    Reason:                ResolvedRefs
    Status:                True
    Type:                  ResolvedRefs

모든 설정이 유효하면, ResolvedRefs 상태는 True가 되어야 합니다. 유효하지 않은 경우 status가 InvalidParameters로 표시됩니다.

3. 수동으로 설정 생성

NginxProxy 리소스가 존재하지 않는 경우, 수동으로 생성하여 GatewayClass와 연결할 수 있습니다.

다음 명령어는 기본 NginxProxy 설정을 생성하고, IP family를 기본 값인 dual이 아닌 ipv4로 설정합니다.

kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha1
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  ipFamily: ipv4
EOF

생성을 했다면 GatewayClass에 연결합니다.

$ kubectl edit gatewayclass nginx

명령어를 사용하면 설정이 기본 에디터에서 열립니다. spec: 하위에 아래 값을 추가합니다.

parametersRef:
    group: gateway.nginx.org
    kind: NginxProxy
    name: ngf-proxy-config

수정이 완료되면 GatewayClass의 상태를 확인하여 설정이 유효한지 확인할 수 있습니다.

$ kubectl describe gatewayclasses nginx

...
Status:
  Conditions:
     ...
    Message:               parametersRef resource is resolved
    Observed Generation:   1
    Reason:                ResolvedRefs
    Status:                True
    Type:                  ResolvedRefs

모든 설정이 유효하면, ResolvedRefs 상태는 True가 되어야 합니다. 유효하지 않은 경우 status가 InvalidParameters로 표시됩니다.

4. NGINX Gateway Fabric Data plane log level 설정

NginxProxy 리소스를 통해 Data Plane Log Level를 동적으로 설정할 수 있습니다.

다음 명령어는 기본 NginxProxy 설정을 생성하고, log level을 기본 값인 info가 아닌 warn으로 설정합니다.

kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha1
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  logging:
    errorLevel: warn
EOF

NginxProxy를 GatewayClass와 연결하면, data plane의 log level이 warn으로 업데이트 됩니다.

지원되는 전체 log level 목록은 API reference의 NginxProxy spec 항목을 확인하세요.

debug 로깅을 사용하려면, NGINX가 --with-debug 설정으로 빌드되거나 debug 모드여야 합니다. NGINX Gateway Fabric은 몇가지 인수를 추가하여 간단하게 NGINX를 디버그 모드로 시작할 수 있습니다.

NGINX Gateway Fabric을 디버그 모드 NGINX로 실행

NGINX Gateway Fabric을 디버그 모드 NGINX로 실행하려면, 설치 방식에 따라 다음 과정을 추가하세요.

• Helm 설치: nginx.debug 값을 true로 설정
• Manifest 설치: Deployment manifest의 nginx 컨테이너 하위에 -c 를 추가하고 rm -rf /var/run/nginx/*.sock && nginx-debug -g 'daemon off;'를 인수로, /bin/sh를 커맨드로 추가합니다. Deployment manifest는 다음과 같이 구성되어야 합니다.

...
- args:
  - -c
  - rm -rf /var/run/nginx/*.sock && nginx-debug -g 'daemon off;'
  command:
  - /bin/sh
...

5. PROXY 프로토콜과 RewriteClientIP 설정

요청이 여러 프록시와 로드 밸런서를 거치면, 클라이언트 IP는 가장 마지막으로 요청을 처리한 서버의 IP로 설정됩니다. 원본 클라이언트의 IP를 보존하려면, NginxProxy 리소스의 RewriteClientIP 설정을 구성해야 합니다. RewriteClientIP 설정에는 mode, trustedAddresses, setIPRecursively 필드가 있습니다.

Mode는 원본 클라이언트 IP가 어떻게 여러 프록시와 로드 밸런서를 거치고 수신하도록 설정되어있는지 정의합니다. 다음 두가지 값을 가질 수 있습니다:

• ProxyProtocol은 연결을 요청한 소스에서 연결이 요청된 대상까지 연결 정보를 전달하는 프로토콜입니다.
• XForwardedFor은 프록시 서버가 요청을 전달한 호스트의 IP 주소 추가에 사용하는 다중 값 HTTP 헤더입니다.

Mode의 선택은 NGINX Gateway Fabric 앞단에 위치한 load balancer와 프록시 서버의 설정에 따라 달라집니다.

TrustedAddresses는 요청을 전달하는 신뢰할 수 있는 프록시 서버의 주소를 정의합니다. 이 값들은 CIDR, IP, hostname이 될 수 있습니다. 예를 들어, 로드 밸런서가 NGINX Gateway Fabric으로 요청을 전달하는 경우, trustedAddresses 리스트에 로드 밸런서의 IP를 정의하여 NGINX가 전달받은 요청이 신뢰할 수 있는 서버로부터 왔다는 것을 알릴 수 있습니다.

SetIPRecursively는 다중 값 헤더에서 클라이언트의 IP 주소를 선택할 때 재귀 검색을 활성화 하는 boolean 필드입니다. 클라이언트 IP를 포함하는 다중 값 헤더가 존재하는 경우, 즉 XForwardedFor 모드를 사용할 때 사용할 수 있습니다.

다음 명령어는 ProxyProtocol 모드로 설정되어 클라이언트 IP를 찾기 위해 신뢰할 수 있는 주소를 CIDR로 설정한 RewriteClientIP 구성이 적용된 NginxProxy 리소스를 생성합니다.

kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha1
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  config:
    rewriteClientIP:
      mode: ProxyProtocol
      trustedAddresses:
      - type: CIDR
        value "76.89.90.11/24"
EOF

전체 설정 API의 경우 API reference의 NginxProxy spec을 참고하세요.

프록시 정보를 예상하는 서버로 curl 요청을 전송할 경우 --haproxy-protocol 플래그를 사용하여 broken 헤더 에러를 방지하세요.