Ingress-NGINX에서 NGINX Gateway Fabric으로 전환하는 전체 작업 절차

Kubernetes 환경에서 기존 Ingress-NGINX를 사용하고 있다면 Gateway API 기반의 NGINX Gateway Fabric으로 전환할 때 단순히 Controller만 교체하는 방식으로 접근해서는 안 된다.

기존 Ingress의 Host, Path, Service 연결, TLS, Annotation 등을 분석한 뒤 Gateway, HTTPRoute 및 NGINX Gateway Fabric Policy로 각각 변환하고, 신규 경로를 기존 환경과 병행 구축하여 검증한 후 실제 트래픽 진입점을 변경하는 방식으로 진행해야 한다.

핵심 전환 개념

기존 Service, Endpoint, Application Pod는 그대로 유지하고
앞단 트래픽 제어 계층만 Ingress-NGINX → Gateway API + NGINX Gateway Fabric으로 전환한다.

1. 전체 전환 구조 이해

기존 구조

Client
  │
  ▼
DNS / LB / VIP
  │
  ▼
Ingress-NGINX Controller
  │
  ▼
Ingress
  │
  ▼
Service
  │
  ▼
Endpoint
  │
  ▼
Application Pod

전환 후 구조

Client
  │
  ▼
DNS / LB / VIP
  │
  ▼
NGINX Gateway Fabric
  │
  ▼
Gateway
  │
  ├── HTTP :80
  │     │
  │     └── HTTPRoute
  │           └── HTTPS Redirect
  │
  └── HTTPS :443
        │
        ▼
     HTTPRoute
        │
        ├── ClientSettingsPolicy
        ├── ProxySettingsPolicy
        │
        ▼
     Service
        │
        ▼
     Endpoint
        │
        ▼
       Pod

따라서 Service와 Pod를 새 환경으로 이동시키는 마이그레이션이 아니다. 기존 Backend는 그대로 두고 앞단에서 요청을 받아 전달하는 경로를 교체하는 작업이다.

2. 기존 Ingress-NGINX 구성 현황 확인

전환 전에는 현재 운영 중인 Ingress 관련 리소스를 먼저 조사해야 한다.

kubectl get pods -A | grep -i ingress

kubectl get ingressclass

kubectl get ingress -A

kubectl get svc -A

kubectl get ingress -A -o yaml

특히 각 Ingress에서 다음 항목을 확인한다.

Hostname
Path
Backend Service
Service Port
HTTP / HTTPS 사용 여부
TLS Secret
Ingress Annotation

전환 대상이 여러 개라면 Ingress별로 설정을 정리한 뒤 하나씩 순차적으로 전환하는 것이 관리하기 쉽다.

3. 기존 Ingress 설정 백업

작업 전 기존 Ingress YAML을 백업한다.

kubectl get ingress web-ingress -n app-prod -o yaml \
> web-ingress-backup.yaml

전체 Ingress를 백업하려면 다음과 같이 확인할 수도 있다.

kubectl get ingress -A -o yaml > ingress-all-backup.yaml

전환 완료 직후 기존 환경을 바로 삭제하지 않고 일정 기간 유지하면 신규 Gateway 경로에 문제가 발생했을 때 기존 진입점으로 되돌릴 수 있는 Rollback 경로를 확보하기 쉽다.

4. NGINX Gateway Fabric 구축

신규 NGINX Gateway Fabric을 기존 Ingress-NGINX와 병행하여 구축한다. 이 단계에서는 아직 실제 사용자 트래픽을 신규 Gateway로 넘기지 않는다.

구축 후 주요 확인 대상은 다음과 같다.

kubectl get gatewayclass

kubectl get pods -n nginx-gateway

즉 이 시점에는 기존과 신규 경로가 동시에 존재할 수 있다.

             기존 운영 경로

Client → Ingress-NGINX → Service → Pod


             신규 구축 경로

          NGINX Gateway Fabric
                    │
                 Gateway
                    │
                HTTPRoute
                    │
                    ▼
                 Service → Pod

5. Gateway 리소스 생성

Ingress의 진입점 역할은 Gateway API에서 Gateway가 담당한다. HTTP 80과 HTTPS 443 Listener를 정의한다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web-gateway
  namespace: app-prod

spec:
  gatewayClassName: nginx

  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: web.example.com

  - name: https
    protocol: HTTPS
    port: 443
    hostname: web.example.com

    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: web-tls

기존 Ingress에서 사용하던 TLS Secret web-tls를 Gateway HTTPS Listener의 certificateRefs에서 참조하는 구조다.

6. 기존 Ingress를 HTTPRoute로 변환

Ingress에서 담당하던 Host, Path 및 Backend Service 연결은 Gateway API의 HTTPRoute로 이동한다.

Ingress	Gateway API
IngressClass	GatewayClass
Ingress	Gateway + HTTPRoute
Host	HTTPRoute hostnames
Path	HTTPRoute matches
Backend Service	HTTPRoute backendRefs
TLS	Gateway HTTPS Listener

중요한 점은 backendRefs가 기존 Service를 그대로 바라본다는 것이다. Service와 Pod 자체를 새로 만드는 작업은 아니다.

7. 기존 Ingress Annotation 변환

예를 들어 기존 Ingress에서 다음 Annotation을 사용하고 있다고 가정한다.

annotations:
  nginx.ingress.kubernetes.io/ssl-redirect: "true"
  nginx.ingress.kubernetes.io/proxy-body-size: "100m"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "60"

전환 관계는 다음과 같다.

기존 Annotation	전환 대상
ssl-redirect	HTTPRoute RequestRedirect
proxy-body-size	ClientSettingsPolicy
proxy-read-timeout	ProxySettingsPolicy

즉 기존 Annotation 세 개를 HTTPRoute 한 곳에 그대로 옮기는 것이 아니라, 각 기능에 맞는 Gateway API 또는 NGINX Gateway Fabric 리소스로 분리한다.

8. HTTP → HTTPS Redirect 구성

기존 ssl-redirect: true 역할은 HTTP Listener에 연결되는 Redirect 전용 HTTPRoute로 구성할 수 있다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-http-redirect
  namespace: app-prod

spec:
  parentRefs:
  - name: web-gateway
    sectionName: http

  hostnames:
  - web.example.com

  rules:
  - filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        port: 443
        statusCode: 301

HTTP :80
   │
   ▼
web-http-redirect
   │
   ▼
RequestRedirect
   │
   ▼
HTTPS :443

9. proxy-body-size 변환

기존 proxy-body-size: 100m 설정은 ClientSettingsPolicy를 생성하여 HTTPRoute에 연결하는 구조로 정리할 수 있다.

apiVersion: gateway.nginx.org/v1alpha1
kind: ClientSettingsPolicy
metadata:
  name: web-client-settings
  namespace: app-prod

spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: web-route

  body:
    maxSize: "100m"

ClientSettingsPolicy
   │
   │ body.maxSize: 100m
   │
   ▼
HTTPRoute: web-route

10. proxy-read-timeout 변환

기존 proxy-read-timeout: 60은 ProxySettingsPolicy를 HTTPRoute에 연결하는 형태로 구성한다.

apiVersion: gateway.nginx.org/v1alpha1
kind: ProxySettingsPolicy
metadata:
  name: web-proxy-settings
  namespace: app-prod

spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: web-route

  timeout:
    read: "60s"

ProxySettingsPolicy
   │
   │ timeout.read: 60s
   │
   ▼
HTTPRoute: web-route

11. Gateway API 리소스 상태 확인

kubectl get gateway,httproute -n app-prod

kubectl describe gateway web-gateway -n app-prod

kubectl describe httproute web-route -n app-prod

HTTPRoute에서는 특히 다음 상태를 확인한다.

Accepted=True
ResolvedRefs=True

ResolvedRefs=False라면 Service 이름, Service Port, Reference 관계 등을 확인해야 한다.

12. Service → Endpoint → Pod 연결 확인

Gateway가 정상이어도 실제 Backend가 정상이라는 의미는 아니다.

kubectl get svc -n app-prod

kubectl get endpoints web-service -n app-prod

kubectl get pods -n app-prod -o wide

예를 들어 Pod 상태는 다음과 같이 확인할 수 있다.

NAME                          READY   STATUS    RESTARTS   IP           NODE
web-7d9c6f8b7b-2k5px         1/1     Running   0          10.42.1.21   worker-01
web-7d9c6f8b7b-8jxmq         1/1     Running   0          10.42.2.15   worker-02

최종적으로 다음 연결이 모두 정상인지 확인한다.

Gateway
   │
   ▼
HTTPRoute
   │
   ▼
Service
   │
   ▼
Endpoint
   │
   ▼
Pod

13. DNS 변경 전 신규 Gateway 직접 테스트

실제 DNS나 LB를 변경하기 전에 신규 Gateway IP로 서비스를 직접 테스트한다.

예를 들어 신규 Gateway IP가 10.10.10.110이라면:

curl -kv \
  --resolve web.example.com:443:10.10.10.110 \
  https://web.example.com/

HTTP Redirect도 확인한다.

curl -v \
  --resolve web.example.com:80:10.10.10.110 \
  http://web.example.com/

Redirect가 정상이라면 HTTP 요청에 대해 HTTPS Location 응답을 확인할 수 있다.

14. 기존 Annotation 기능 검증

페이지 접속 여부만 확인해서는 부족하다.

기존 기능	검증 항목
ssl-redirect	HTTP 요청이 HTTPS로 Redirect되는지 확인
proxy-body-size 100m	설정된 요청 Body 제한이 의도대로 동작하는지 확인
proxy-read-timeout 60	Backend 응답 지연 시 Timeout 정책 동작 확인

중요: Ingress → Gateway API 전환은 단순 HTTP 200 응답 확인으로 끝내면 안 된다. 기존 Ingress에서 제공하던 TLS, Redirect, Body Size, Timeout 등의 기능까지 동일하게 검증해야 한다.

15. 병행 운영 상태

신규 Gateway 검증 단계에서는 기존 Ingress와 신규 Gateway가 동일한 Backend Service를 동시에 바라볼 수 있다.

               ┌──── 기존 경로 ────┐

Client ──────► Ingress-NGINX
                    │
                    │
                    ▼
                web-service
                    │
                    ▼
                   Pod
                    ▲
                    │
                    │
Client ──────► Gateway Fabric
               └──── 신규 경로 ────┘

이 상태에서도 기존 DNS 또는 VIP가 Ingress-NGINX를 가리키고 있다면 실제 사용자 트래픽은 계속 기존 경로를 이용한다.

16. 실제 트래픽 Cutover

Gateway Fabric을 설치했다고 트래픽이 자동으로 넘어가는 것은 아니다. 실제 전환 시점에는 DNS, Load Balancer 또는 VIP의 대상을 신규 Gateway 쪽으로 변경해야 한다.

전환 전

web.example.com
      │
      ▼
10.10.10.100
      │
      ▼
Ingress-NGINX

전환 후

web.example.com
      │
      ▼
10.10.10.110
      │
      ▼
NGINX Gateway Fabric
      │
      ▼
Gateway
      │
      ▼
HTTPRoute
      │
      ▼
기존 Service
      │
      ▼
기존 Pod

즉 실제 Cutover는 Backend를 이동하는 것이 아니라 트래픽 진입점을 변경하는 작업이다.

17. N개 Ingress 순차 전환

운영 환경에서 여러 Ingress가 존재한다면 전체를 한 번에 전환하기보다 서비스 단위로 검증과 Cutover를 반복하는 방식으로 진행할 수 있다.

Ingress #1
   ↓
Gateway/HTTPRoute #1
   ↓
검증
   ↓
Cutover
   ↓
안정화

Ingress #2
   ↓
Gateway/HTTPRoute #2
   ↓
검증
   ↓
Cutover
   ↓
안정화

          ...

Ingress #N
   ↓
Gateway/HTTPRoute #N
   ↓
검증
   ↓
Cutover
   ↓
안정화

18. 전환 후 서비스 검증

nslookup web.example.com

curl -vk https://web.example.com/

kubectl get gateway -A

kubectl get httproute -A

kubectl get pods -n nginx-gateway

kubectl get pods -n app-prod

Gateway Fabric 로그도 함께 확인한다.

kubectl logs -n nginx-gateway <nginx-gateway-fabric-pod>

다음 항목을 종합적으로 확인한다.

실제 사용자 접속
HTTP/HTTPS
TLS 인증서
Redirect
Gateway 상태
HTTPRoute 상태
Application Pod 상태
Gateway Fabric 로그
서비스 주요 기능

19. 안정화 및 기존 Ingress 제거

Cutover 직후 기존 Ingress를 즉시 삭제하지 않고 일정 기간 신규 경로의 안정성을 확인한다.

안정화가 완료된 서비스부터 기존 Ingress를 순차적으로 제거한다.

kubectl get ingress -A

kubectl delete ingress web-ingress -n app-prod

N개의 Ingress가 모두 Gateway API로 전환된 것을 확인한 이후 최종적으로 기존 Ingress-NGINX Controller 제거를 진행한다.

20. 기존 영역과 신규 영역 비교

기존 Ingress-NGINX	NGINX Gateway Fabric
Ingress-NGINX Controller	NGINX Gateway Fabric
IngressClass	GatewayClass
Ingress	Gateway + HTTPRoute
ssl-redirect Annotation	RequestRedirect
proxy-body-size	ClientSettingsPolicy
proxy-read-timeout	ProxySettingsPolicy
Ingress TLS	Gateway HTTPS Listener + certificateRefs

반대로 Backend의 Service, Endpoint, Application Pod 등은 기존 구성을 그대로 사용하는 것이 이번 전환 구조의 핵심이다.

21. 전체 작업 흐름도

[기존 환경 조사]
        │
        ▼
[Ingress YAML 백업]
        │
        ▼
[NGINX Gateway Fabric 병행 구축]
        │
        ▼
[Gateway / Listener 생성]
        │
        ▼
[Ingress → HTTPRoute 변환]
        │
        ▼
[Annotation → Route / Policy 변환]
        │
        ▼
[TLS → Gateway HTTPS Listener 이전]
        │
        ▼
[Gateway / HTTPRoute 상태 확인]
        │
        ▼
[Service / Endpoint / Pod 확인]
        │
        ▼
[신규 Gateway IP 사전 테스트]
        │
        ▼
[Redirect / TLS / Policy 기능 검증]
        │
        ▼
[N개 서비스 순차 검증]
        │
        ▼
[DNS / LB / VIP Cutover]
        │
        ▼
[실제 사용자 트래픽 검증]
        │
        ▼
[안정화 모니터링]
        │
        ▼
[기존 Ingress 순차 제거]
        │
        ▼
[전체 전환 완료 확인]
        │
        ▼
[Ingress-NGINX Controller 제거]
        │
        ▼
[Gateway API 전환 완료]

22. 전환 구조 핵심 정리

               [ 공통 Backend ]

                  Service
                     │
                  Endpoint
                     │
                    Pod
                   ▲   ▲
                  /     \
                 /       \
        기존 경로         신규 경로

   Ingress-NGINX      NGINX Gateway Fabric
        │                    │
     Ingress              Gateway
                             │
                          HTTPRoute


             ▲ 병행 구축 및 검증 ▲

                    │
              DNS / LB / VIP
                    │
                  Client


                 Cutover
                    │
                    ▼

              DNS / LB / VIP
                    │
                    ▼
          NGINX Gateway Fabric
                    │
                 Gateway
                    │
                HTTPRoute
                    │
                 Service
                    │
                 Endpoint
                    │
                   Pod

                    │
                    ▼
          기존 Ingress-NGINX 제거

한 문장 요약

기존 Service, Endpoint, Application Pod 등 Backend 영역은 유지하면서, 앞단 트래픽 제어 계층을 Ingress-NGINX에서 Gateway API 기반 NGINX Gateway Fabric으로 서비스별 검증 후 순차적으로 전환하는 작업이다.

특히 신규 Gateway Fabric 구축만으로 실제 트래픽이 자동 전환되는 것은 아니며, 최종 Cutover 단계에서 DNS, LB 또는 VIP의 실제 트래픽 대상을 신규 Gateway 쪽으로 변경해야 한다.

FAQ

Ingress-NGINX와 Gateway Fabric을 동시에 운영할 수 있나?

전환 과정에서는 기존 Ingress-NGINX 경로를 유지하면서 신규 Gateway Fabric 경로를 별도로 구축하고 검증하는 병행 구조를 사용할 수 있다. 두 경로가 동일한 Backend Service를 바라보도록 구성할 수 있다.

Gateway Fabric을 설치하면 기존 트래픽이 자동으로 넘어가나?

아니다. 실제 사용자가 기존 DNS, LB 또는 VIP를 통해 Ingress-NGINX로 접근하고 있다면 해당 진입점을 신규 Gateway 쪽으로 변경하는 Cutover 작업이 필요하다.

기존 Application Pod도 마이그레이션해야 하나?

이번 전환 구조에서는 기존 Service, Endpoint 및 Application Pod를 그대로 유지하고 앞단 라우팅 계층을 변경한다. 따라서 Application Pod 자체를 Gateway Fabric으로 옮기는 작업과는 구분해야 한다.

기존 Ingress는 언제 삭제해야 하나?

신규 Gateway 경로로 실제 트래픽을 전환한 뒤 서비스와 정책 동작을 충분히 검증하고 안정화 상태를 확인한 후 제거한다. 여러 Ingress가 존재한다면 전환이 완료된 Ingress부터 순차적으로 정리한다.

Ingress-NGINX Controller는 언제 제거해야 하나?

해당 Controller가 담당하던 모든 Ingress가 Gateway API 기반 구조로 전환되고 기존 Controller를 사용하는 서비스가 남아 있지 않은 것을 확인한 이후 최종 제거하는 흐름으로 진행한다.

저작자표시 변경금지 (새창열림)

'지식 공유 > Server' 카테고리의 다른 글

Rancher Single에서 RKE2 3-Node HA 구성 전환 및 장애 복구 대응 정리 (0)	2026.09.28
Kubernetes Rancher에서 Init:ImagePullBackOff 발생 원인과 확인 방법 (0)	2026.09.28
SUSE Linux Zypper 명령어 사용법: 패키지 설치, RPM 다운로드, 저장소 관리 (0)	2026.07.27
중첩 본딩의 위험과 MLAG를 이용한 2:2 단일 본딩 40G 구성 방법 (0)	2026.07.23
SUSE OS에서 PostgreSQL 기반 DBMS 대용량 처리 문제 정리 (0)	2026.06.24