ingress2gateway를 통한 Ingress to Gateway API 마이그레이션

Kubernetes 환경에서 트래픽을 라우팅하는 표준 방식이었던 Ingress API를 대체할 차세대 표준으로 Gateway API가 부상하고 있습니다. Gateway API는 기존 Ingress의 한계를 극복하고, 역할 기반의 명확한 리소스 분리와 더 풍부하고 세밀한 트래픽 제어 기능을 제공합니다.

하지만 이미 운영 중인 수많은 Ingress 리소스들을 새로운 Gateway API 규격으로 일일이 전환하는 것은 결코 쉽지 않은 작업입니다. 이러한 마이그레이션의 부담을 크게 덜어주기 위해 등장한 오픈소스 도구가 바로 ingress2gateway입니다.

이번 포스트에서는 ingress2gateway의 기본 개념과 설치 방법을 알아보고, 이를 활용해 기존 Ingress NGINX 환경을 NGINX Gateway Fabric으로 변환하는 마이그레이션 과정을 직접 테스트하며 주의사항을 살펴보겠습니다.

목차

1. ingress2gateway란?
2. ingress2gateway 설치 및 사용법
3. 환경 구성
4. 마이그레이션 테스트
5. 결론

1. ingress2gateway란?

ingress2gateway는 기존 Kubernetes에서 사용하던 Ingress 리소스와 일부 Ingress Controller의 전용 설정과 CRD를 Gateway API 리소스로 변환해주는 마이그레이션 도구입니다.

ingress에서 Gateway API로 변환할 수 있는 Provider는 아래와 같습니다.

apisix, cilium, ingress-nginx, istio, gce, kong, nginx, openapi

현재 ingress2gateway v1.0 기준으로 Gateway API v1.5.0 버전을 지원하고 있습니다.

해당 포스트에서는 ingress2gateway를 통해 Ingress NGINX -> NGINX Gateway Fabric 마이그레이션을 다룹니다.

2. ingress2gateway 설치 및 사용법

ingress2gateway는 go를 통한 설치, Homebrew를 통한 설치, 소스코드 빌드가 있습니다.

Homebrew를 통해서 설치를 진행하였습니다.

brew install ingress2gateway

ingress2gateway는 아래 명령어를 통해 사용할 수 있습니다.

ingress2gateway print --providers=[ingress] --input-file=<your-ingress-file> -n [namespace] > gateway-api-resources.yaml

해당 명령어를 사용하면 완벽하게 Gateway API로 변경되는 것이 아니기 때문에 수동으로 검토 및 테스트를 필수적으로 진행해야 하며 구성을 변경해야할 수도 있습니다.

3. 환경 구성

• kubernetes v1.34.4
• Ingress NGINX v1.15.1
• NGINX Gateway Fabric 2.5.0
• ingress2gateway 1.0.0 (Go version go1.26.1)

Ingress NGINX와 NGINX Gateway Fabric이 배포되어있는 상태에서 진행해야합니다.

4. 마이그레이션 테스트

※ 현재 버전으로 완벽하게 마이그레이션이 되지 않습니다.

테스트용 ingress를 생성합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-nginx
  namespace: ingress-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-nginx
  template:
    metadata:
      labels:
        app: demo-nginx
    spec:
      containers:
      - name: demo-nginx
        image: nginxdemos/nginx-hello:plain-text
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: demo-nginx
  namespace: ingress-demo
spec:
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: demo-nginx
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-demo
  namespace: ingress-demo
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/configuration-snippet: |
      add_header X-Test-Header "ingress-demo" always;
      add_header X-Test-Env "dev" always;
      add_header X-Test-Version "v1" always;
spec:
  ingressClassName: nginx
  rules:
    - host: demo.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: demo-nginx
                port:
                  number: 80

위 yaml를 배포합니다.

해당 서비스로 demo.local 호스트로 요청시 아래와 같이 demo-nginx로 라우팅 되는 것을 확인할 수 있습니다.

이후 ingress2gateway를 통해 ingress 리소스를 gateway api로 마이그레이션합니다.

$ ingress2gateway print --providers=nginx --input-file=okr-ingress-demo.yaml > gateway-api-resources.yaml

마이그레이션 하면서 자동변환 되지 않는 항목, 주의사항, 정보성 알림을 보여줍니다.

• NGINX Ingress에서 하던 일부 동작을 Gateway API 표준만으로는 완전히 똑같이 못 옮길 수 있다는 경고입니다.

마이그레이션 된 리소스 파일은 아래와 같이 나오게 됩니다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-1.0.0
  name: nginx
  namespace: ingress-demo
spec:
  gatewayClassName: nginx
  listeners:
  - hostname: demo.local
    name: demo-local-http
    port: 80
    protocol: HTTP
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-1.0.0
  name: ingress-demo-demo-local
  namespace: ingress-demo
spec:
  hostnames:
  - demo.local
  parentRefs:
  - name: nginx
  rules:
  - backendRefs:
    - name: demo-nginx
      port: 80
    matches:
    - path:
        type: PathPrefix
        value: /
    name: rule-0
status:
  parents: []

경고로 나왔었던 configuration-snippet, URLRewrite를 제외한 나머지가 마이그레이션 된 것을 확인할 수 있습니다.

해당 마이그레이션 도구는 마이그레이션 전 간단히 Gateway API의 yaml를 받아 볼 수 있는 도구로 실제 프로덕션에서 사용하려면 많은 수정을 거쳐야합니다.

해당 리소스를 배포합니다.

배포 시 NGINX Gateway Fabric의 Data Plane이 배포되는 것을 확인할 수 있습니다.

요청까지 정상적으로 처리되는 것을 확인할 수 있지만 Annotation으로 추가된 Header들은 추가가 안된 것을 확인할 수 있습니다.

해당 구성을 아래와 같이 누락된 header 구성을 추가한 후 apply 합니다.

(rules 하위 부분만 변경합니다.)

# 마이그레이션 httproute
...
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      # 추가 된 내용
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            add:     # 헤더를 추가합니다.
              - name: X-Test-Header
                value: ingress-demo
              - name: X-Test-Env
                value: dev
              - name: X-Test-Version
                value: v1
...

정상적으로 나오는 것을 확인할 수 있습니다.

5. 결론

ingress2gateway는 기존 Ingress 리소스를 Gateway API로 빠르게 변환해 주어 마이그레이션의 초기 뼈대를 잡아주는 유용한 도구입니다.

하지만 복잡한 커스텀 Annotation이나 특수한 라우팅 규칙은 완벽히 자동 변환되지 않습니다. 따라서 도구가 생성한 결과물은 마이그레이션 초안으로만 활용해야 하며, 실제 프로덕션 적용 전에는 반드시 관리자가 리소스를 직접 검토하고 수동으로 재조정하는 테스트 과정이 필수적입니다.

Gateway API 도입 및 NGINX Gateway Fabric 구성에 어려움을 겪고 계시거나 추가적인 기술 지원이 필요하시다면, NGINX STORE를 통해 문의하세요.