NGINX Gatway Fabric Gateway 배포 – data plane 구성

이 문서는 NGINX Gatway Fabric 의 Gateway 를 NGINX data plane 배포를 위해 사용하는 방법과 NGINX custom resource를 사용하여 수정하는 방법을 설명합니다.

Gateway는 모든 인바운드 요청의 관리에 사용되며, Gateway API의 핵심 리소스입니다.

Gateway가 NGINX Gateway Fabric과 관련된 GatewayClass와 연결되면, NGINX deployment와 Service를 생성합니다. 이런 방식으로 NGINX data plane을 형성하여 요청을 처리합니다.

단일 GatewayClass는 여러 Gateway를 가질 수 있습니다. 각 Gateway는 별개의 Service와 NGINX deployment를 생성합니다.

사전 구성

목차

1. Gateway 생성
2. 프로비저닝된 NGINX 인스턴스 수정
 2-1. 프로비저닝된 리소스에 annotation과 레이블 설정

1. Gateway 생성

Gateway 배포를 위해 다음 명령어를 사용합니다.

$ kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cafe
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    port: 80
    protocol: HTTP
EOF

Gateway의 정상적인 배포를 확인하려면 kubectl describe 명령어를 사용하여 Gateway의 상태를 확인합니다.

$ kubectl describe gateway

다음과 같은 상태가 확인되어야 합니다.

Conditions:
      Last Transition Time:  2025-05-05T23:49:33Z
      Message:               Listener is accepted
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2025-05-05T23:49:33Z
      Message:               Listener is programmed
      Observed Generation:   1
      Reason:                Programmed
      Status:                True
      Type:                  Programmed
      Last Transition Time:  2025-05-05T23:49:33Z
      Message:               All references are resolved
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
      Last Transition Time:  2025-05-05T23:49:33Z
      Message:               No conflicts
      Observed Generation:   1
      Reason:                NoConflicts
      Status:                False
      Type:                  Conflicted

kubectl get 명령어를 사용하여 NGINX Deployment를 확인할 수 있습니다.

$ kubectl get deployments

NAME         READY   UP-TO-DATE   AVAILABLE   AGE
cafe-nginx   1/1     1            1           3m18s

Service도 확인할 수 있습니다.

$ kubectl get services

NAME         TYPE            CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
cafe-nginx   LoadBalancer    10.96.125.117   <pending>     80:30180/TCP   5m2s

Service 타입은 변경될 수 있습니다. 다음 섹션의 설명을 참고하세요.

2. 프로비저닝된 NGINX 인스턴스 수정

NginxProxy custom resource는 Gateway가 생성될 때 NGINX deployment와 Service의 프로비저닝을 수정할 수 있습니다.

Note: NginxProxy의 대부분의 Kubernetes 관련 필드를 업데이트하면 관련 리소스가 재시작됩니다.

NginxProxy 리소스는 기본적으로 NGINX Gateway Fabric 배포 이후에 생성됩니다. 이 NginxProxy 리소스는 GatewayClass(NGINX Gateway Fabric 설치에 생성됨)와 연결되어 모든 Gateway에 설정이 적용됩니다.

kubectl get과 kubectl describe를 사용하여 리소스에 대한 더 많은 정보를 얻으세요.

$ kubectl get nginxproxies -A

NAMESPACE       NAME                      AGE
nginx-gateway   ngf-proxy-config   19h
$ kubectl describe nginxproxy -n nginx-gateway ngf-proxy-config

Name:         ngf-proxy-config
Namespace:    nginx-gateway
Labels:       app.kubernetes.io/instance=ngf
              app.kubernetes.io/managed-by=Helm
              app.kubernetes.io/name=nginx-gateway-fabric
              app.kubernetes.io/version=edge
              helm.sh/chart=nginx-gateway-fabric-1.6.2
Annotations:  meta.helm.sh/release-name: ngf
              meta.helm.sh/release-namespace: nginx-gateway
API Version:  gateway.nginx.org/v1alpha2
Kind:         NginxProxy
Metadata:
  Creation Timestamp:  2025-05-05T23:01:28Z
  Generation:          1
  Resource Version:    2245
  UID:                 b545aa9e-74f8-45c0-b472-f14d3cab936f
Spec:
  Ip Family:  dual
  Kubernetes:
    Deployment:
      Container:
        Image:
          Pull Policy:  IfNotPresent
          Repository:   nginx-gateway-fabric/nginx
          Tag:          edge
      Replicas:         1
    Service:
      External Traffic Policy:  Local
      Type:                     LoadBalancer
Events:                         <none>

kubectl describe 명령어로 확인한 정보를 통해 프로비저닝된 NGINX Deployment와 Service의 기본 설정을 확인할 수 있습니다. Spec.Kubernetes에서 몇 가지 정보를 확인할 수 있습니다.

  • NGINX 컨테이너 이미지 설정
  • NGINX Deployment의 replicas 값
  • Service 타입과 external traffic policy

Note: 설치 설정에 따라 기본 NginxProxy 설정이 예시의 내용과 다를 수 있습니다. NginxProxy와 NginxProxy의 설정 가능한 필드에 대한 더 많은 정보는 API reference를 확인하세요.

NginxProxy 리소스를 수정하여 Service의 타입을 변경합니다.

kubectl edit 명령어를 사용하여 기본 NginxProxy를 수정하고 spec.kubernetes.service에 다음 값을 넣습니다.

type: NodePort

변경 내용을 저장한 후에, kubectl get 명령어로 Service를 확인하여 NodePort 타입으로 변경된 것을 확인합니다.

$ kubectl get service cafe-nginx

NAME         TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
cafe-nginx   NodePort       10.96.172.204   <none>        80:32615/TCP   3h5m

2-1. 프로비저닝된 리소스에 annotation과 레이블 설정

대부분의 설정은 NginxProxy 리소스에서 이루어지지만 모든 설정이 그렇지는 않습니다. annotation과 레이블을 NGINX Deployment 혹은 Service에 적용하려면, NGINX Deployment 혹은 Service를 프로비저닝한 Gateway에 annotation과 레이블을 적용해야 합니다.

Gateway에 kubectl edit 명령어를 사용하여 spec에 다음 설정을 추가할 수 있습니다.

infrastructure:
  annotations:
    annotationKey: annotationValue
  labels:
    labelKey: labelValue

변경된 설정을 적용하고 NGINX Deployment와 Service를 kubectl describe명령어를 사용하여 확인할 수 있습니다.

$ kubectl describe deployment cafe

Name:                   cafe-nginx
Namespace:              default
CreationTimestamp:      Mon, 05 May 2025 16:49:33 -0700
...
Pod Template:
  Labels:           app.kubernetes.io/instance=ngf
                    app.kubernetes.io/managed-by=ngf-nginx
                    app.kubernetes.io/name=cafe-nginx
                    gateway.networking.k8s.io/gateway-name=cafe
                    labelKey=labelValue
  Annotations:      annotationKey: annotationValue
                    prometheus.io/port: 9113
                    prometheus.io/scrape: true
...
$ kubectl describe service cafe-nginx

Name:                     cafe-nginx
Namespace:                default
Labels:                   app.kubernetes.io/instance=ngf
                          app.kubernetes.io/managed-by=ngf-nginx
                          app.kubernetes.io/name=cafe-nginx
                          gateway.networking.k8s.io/gateway-name=cafe
                          labelKey=labelValue
Annotations:              annotationKey: annotationValue