NGINX Gateway Fabric Data Plane 구성

NGINX Gateway Fabric의 글로벌 데이터 플레인 구성을 동적으로 업데이트하는 방법을 배우세요.

목차

1. 개요
2. 구성 보기 및 업데이트
3. 구성 수동 생성
4. Data Plane 로그 래벨 구성
5. PROXY 프로토콜 및 RewriteClientIP 설정 구성

1. 개요

NGINX Gateway Fabric은 재시작 없이 글로벌 데이터 플레인 구성을 동적으로 업데이트할 수 있습니다. 데이터 플레인 구성은 표준 Gateway API 리소스를 통해 설정할 수 없는 옵션들을 포함하는 글로벌 NGINX 구성입니다. 여기에는 OpenTelemetry 수집기 설정, HTTP/2 비활성화, IP 패밀리 변경, NGINX 오류 로그 레벨 조정 등이 포함됩니다.

이 구성은 클러스터 범위의 NginxProxy 사용자 지정 리소스(Custom Resource, CR)에 저장되며, 이는 nginx GatewayClass에 연결됩니다.

기본적으로 NGINX Gateway Fabric을 설치할 때 NginxProxy 리소스는 자동으로 생성되지 않습니다. 하지만 Helm 설치 시 nginx.config Helm 값을 설정하면 해당 리소스가 생성되고 자동으로 연결됩니다. 또한, NGINX Gateway Fabric을 이미 설치한 후에도 수동으로 NginxProxy 리소스를 생성하고 연결할 수 있습니다.

Helm 차트를 사용하여 설치할 경우, NginxProxy 리소스의 이름은 <release-name>-proxy-config 형식으로 지정됩니다.

설정할 수 있는 전체 구성 옵션 목록은 API 참조 문서의 NginxProxy spec에서 확인할 수 있습니다.

• 일부 글로벌 구성은 기능을 완전히 활성화하기 위해 관련 정책이 필요합니다. 예를 들어, 트레이싱과 같은 기능을 사용하려면 적절한 정책을 함께 설정해야 합니다.

2. 구성 보기 및 업데이트

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

다음 예제에서 사용된 ngf-proxy-config 이름은 설치 시 생성된 리소스의 실제 이름으로 변경해야 합니다.

현재 구성을 확인하려면 다음 명령을 실행하십시오.

kubectl describe nginxproxies ngf-proxy-config

구성을 업데이트 하려면 다음 명령을 실행하십시오.

kubectl edit nginxproxies 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로 표시됩니다. 그렇지 않은 경우, 상태에서 InvalidParameters 조건을 확인할 수 있습니다.

3. 구성 수동 생성

NginxProxy 리소스가 존재하지 않는 경우, 이를 생성하고 GatewayClass에 연결할 수 있습니다.

다음 명령은 기본 NginxProxy 구성을 생성하며, IP 패밀리를 기본값인 dual에서 ipv4로 변경합니다.

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

이제 NginxProxy 리소스를 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로 표시됩니다. 그렇지 않으면 상태에서 InvalidParameters 조건을 확인할 수 있습니다.

4. Data Plane 로그 레벨 구성

NginxProxy 리소스를 사용하여 데이터 플레인의 로그 레벨을 동적으로 구성할 수 있습니다.

다음 명령은 기본 NginxProxy 구성을 생성하며, 로그 레벨을 기본값인 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에 연결하면 데이터 플레인의 로그 레벨이 warn으로 업데이트됩니다.

지원되는 전체 로그 레벨 목록은 API 참조 문서의 NginxProxy 스펙에서 확인할 수 있습니다.

디버그 로깅을 활성화하려면 NGINX가 --with-debug 옵션으로 빌드되었거나 “디버그 모드”로 실행되어야 합니다. NGINX Gateway Fabric은 몇 가지 추가 인자를 설정하여 시작할 때 쉽게 디버그 모드로 실행할 수 있습니다.

• Run NGINX Gateway Fabric with NGINX in debug mode

NGINX Gateway Fabric을 디버그 모드로 실행하려면 설치 문서를 참고하면서 다음 추가 단계를 수행하십시오.

Helm을 사용할 경우, nginx.debug 값을 true로 설정하십시오.

Kubernetes 매니페스트를 사용할 경우, Deployment 매니페스트의 nginx 컨테이너에서 다음과 같이 수정하십시오.

• arguments에 -c 및 rm -rf /var/run/nginx/*.sock && nginx-debug -g 'daemon off;' 추가
• command를 /bin/sh로 설정

이제 Deployment 매니페스트는 다음과 같은 형태가 됩니다.

...
- 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가 여러 프록시를 통해 전달되는 방식과 로드 밸런서가 이를 수신하는 방법을 결정합니다. 두 가지 값이 가능합니다.

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

Mode의 선택은 NGINX Gateway Fabric 앞단의 로드 밸런서가 정보를 수신하는 방식에 따라 결정됩니다.

TrustedAddresses는 요청을 전달하는 신뢰할 수 있는 프록시의 IP 주소를 지정하는 데 사용됩니다. CIDR, IP 또는 호스트명 형태로 설정할 수 있습니다.
예를 들어, 로드 밸런서가 NGINX Gateway Fabric으로 요청을 전달하는 경우, 로드 밸런서의 IP 주소를 trustedAddresses 목록에 추가하여 NGINX가 해당 요청이 신뢰할 수 있는 소스로부터 온 것임을 알 수 있도록 해야 합니다.

SetIPRecursively는 다중 값 헤더에서 클라이언트 주소를 선택할 때 재귀 검색을 활성화하는 데 사용하는 불리언 필드입니다.
XForwardedFor 모드를 사용할 때처럼 다중 값 헤더에 여러 개의 클라이언트 IP가 포함된 경우에 적용됩니다.

다음 명령은 RewriteClientIP 설정을 포함하는 NginxProxy 리소스를 생성하며, mode를 ProxyProtocol로 설정하고 신뢰할 수 있는 주소 목록에 CIDR을 추가하여 원래 클라이언트 IP 주소를 찾도록 합니다.

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 참조 문서의 NginxProxy 스펙에서 확인할 수 있습니다.

프록시 정보를 기대하는 서버로 curl 요청을 보낼 때, --haproxy-protocol 플래그를 사용하여 헤더 오류를 방지하십시오.

NGINX Gateway Fabric에 관련한 더 많은 정보를 알고싶으시다면 NGINX STORE Kubernetes를 방문해주세요.