[TIL] Ingress Nginx → Envoy Gateway, 왜 그리고 어떻게

Ingress Nginx가 지원 종료?

2026년 3월, Ingress Nginx가 공식 EOL(End of Life) 을 선언했다. Kubernetes 초창기부터 사실상 표준이었던 인그레스 컨트롤러가 더 이상 보안 패치조차 받지 못하게 된 것이다.

왜 이렇게 됐을까?

• Ingress API 자체의 한계: Ingress 리소스는 기본 HTTP 라우팅만 표준으로 정의하고, 나머지는 전부 어노테이션에 의존했다. 컨트롤러마다 어노테이션이 달라서 이식성이 없었다.
• Gateway API의 성숙: Kubernetes SIG-Network이 만든 Gateway API가 2023년 GA를 달성하면서, Ingress의 모든 기능 + 그 이상을 표준 리소스로 제공하게 됐다.
• 커뮤니티 이동: Istio, Envoy Gateway, Cilium 등 주요 프로젝트가 Gateway API를 기본으로 채택했다.

Ingress Nginx 프로젝트 자체가 "Gateway API로 마이그레이션하세요" 라고 공식 권고하고 있다.

[브라우저] → [리버스 프록시 (Ingress Controller)] → [Service A]

Gateway API, 개념부터 잡기

apiVersion: v1
kind: Pod           # ← 이 "kind"가 리소스의 종류
metadata:
  name: my-pod      # ← 리소스의 이름
  namespace: my-app # ← 어떤 네임스페이스에 속하는지
  annotations:      # ← 부가 메타데이터
    example: "hello"
spec:               # ← 리소스의 실제 설정 (스펙)
  ...

Gateway API를 이해하려면 먼저 왜 리소스를 3개로 쪼갰는지를 이해해야 한다.

기존 Ingress 리소스는 하나의 YAML에 도메인 → 서비스 매핑을 다 적었다. 단순할 땐 편했는데, TLS 설정이나 rate limit, 헤더 조작, 카나리 배포 같은 걸 하려면 annotations에 nginx 전용 설정을 잔뜩 넣어야 했다. 다른 컨트롤러(Traefik, HAProxy 등)로 바꾸면 어노테이션을 전부 다시 써야 했고.

Gateway API는 이걸 관심사 분리로 풀었다. 누가 뭘 담당하느냐에 따라 리소스를 쪼갠 거다.

GatewayClass - 게이트웨이 구현체 선택

StorageClass가 스토리지 백엔드를 정해주듯, GatewayClass는 어떤 게이트웨이 구현체를 쓸지 정한다.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg                # 이 이름을 아래 Gateway에서 참조
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

보통 클러스터에 한 번만 만들고 거의 건드리지 않는다. 클라우드 환경이라면 AWS ALB, GCP GLB 같은 제공자의 GatewayClass가 이미 있을 수도 있다.

Gateway - 트래픽이 들어오는 문

클러스터 외부 트래픽의 입구다. 어떤 포트에서 어떤 프로토콜을 받을지, TLS를 어떻게 처리할지를 여기서 잡는다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: infra        # 보통 인프라 네임스페이스에 위치
spec:
  gatewayClassName: eg    # 위에서 만든 GatewayClass 참조
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-tls
    - name: http
      protocol: HTTP
      port: 80

호텔로 치면 로비다. 손님(트래픽)이 들어오는 곳이고, 보안 검색(TLS)도 여기서 한다. 대신 몇 호실로 가라는 안내는 안 한다 - 그건 HTTPRoute가 할 일이다.

HTTPRoute - 요청을 어디로 보낼지

실제 라우팅 규칙이다. 이 도메인의 이 경로로 들어온 요청을 어떤 Service로 보낼지 정한다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app-route
  namespace: my-app       # 앱 네임스페이스에 위치!
spec:
  parentRefs:
    - name: my-gateway
      namespace: infra    # 어떤 Gateway에 붙을지 참조
  hostnames:
    - my-app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-svc
          port: 80

중요한 건 HTTPRoute를 앱 네임스페이스에 만든다는 점이다. 앱 개발자는 자기 서비스 라우팅만 신경 쓰면 된다. TLS 설정이나 게이트웨이 구현체가 뭔지 알 필요 없다. parentRefs로 어떤 Gateway에 붙을지만 지정하면 끝이다.

역할 분리가 실제로 어떻게 동작하는지

역할 분리가 왜 중요한지, 기존 Ingress랑 비교하면 바로 느낌이 온다.

Ingress 시절의 문제

# 앱 개발자가 이걸 다 알아야 했다
metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"       # TLS? 내가 왜...
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"      # nginx 설정을...
    nginx.ingress.kubernetes.io/limit-rps: "10"             # 어노테이션으로...
    nginx.ingress.kubernetes.io/canary: "true"              # 이렇게 많이...
    nginx.ingress.kubernetes.io/canary-weight: "20"         # 알아야 하지?
    cert-manager.io/cluster-issuer: "letsencrypt-prod"      # 인증서까지?

앱 개발자가 nginx 내부 동작 방식, TLS 인증서 관리, rate limit 설정까지 전부 알아야 했다. 그냥 /api 경로를 서비스에 연결하고 싶을 뿐인데 알아야 할 게 너무 많았다.

Gateway API에서의 분리

RBAC으로 자연스럽게 매핑된다:

# 앱팀에게 HTTPRoute 권한만 부여
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: my-app
rules:
  - apiGroups: ["gateway.networking.k8s.io"]
    resources: ["httproutes"]
    verbs: ["get", "list", "create", "update", "patch"]
  # Gateway, GatewayClass는 권한 없음 → 건드릴 수 없음

앱 개발자는 HTTPRoute만 알면 된다. TLS 인증서가 어떻게 관리되는지, rate limit이 어디서 걸리는지 몰라도 된다. 플랫폼팀이 Gateway에서 한 번만 설정하면 모든 HTTPRoute에 자동 적용된다.

설정 비교 - 실전 YAML

실제 YAML을 나란히 비교해 보자. 각 탭을 눌러서 시나리오별 차이를 확인할 수 있다.

• Basic Routing: 단순 경로 기반 라우팅. Gateway API 쪽이 어노테이션 없이 더 명시적이다.
• TLS: Ingress는 어노테이션 + tls 블록이 섞이지만, Gateway API는 Gateway 리소스에서 TLS를 한 번에 관리한다. HTTPRoute는 TLS를 몰라도 된다.
• Canary: 가장 차이가 극적이다. Ingress는 리소스 2개 + canary 어노테이션이 필요하지만, Gateway API는 backendRefs에 weight만 추가하면 끝이다.
• Rate Limit: Ingress는 nginx 전용 어노테이션, Gateway API는 Envoy Gateway의 BackendTrafficPolicy CRD로 더 세밀한 제어가 가능하다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-svc
                port:
                  number: 80

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-svc
          port: 80

카나리 배포가 이렇게 쉬워진다

카나리 배포란?

새 버전(v2)을 배포할 때, 한 번에 다 바꾸지 않고 일부 사용자에게만 먼저 보내서 문제 없는지 확인하는 전략이다. 이름은 탄광의 카나리아에서 왔다 - 위험 징후를 먼저 감지하는 역할.

예를 들어 100명의 사용자가 app.example.com에 접속한다고 하면:

• weight: 80 / weight: 20 설정 → 약 80명은 기존 v1으로, 약 20명은 새 v2로 보내진다
• v2에서 에러가 터지면? 영향 범위가 20%로 제한된다
• 문제 없으면? weight를 50 → 80 → 100으로 점진적으로 올려서 완전히 전환한다

Ingress에서는 왜 번거로웠나

Ingress Nginx에서 카나리를 하려면 Ingress 리소스를 2개 만들어야 했다:

1. 기본 Ingress → v1 서비스 연결
2. 카나리 Ingress → v2 서비스 연결 + canary: "true" + canary-weight: "20" 어노테이션

리소스가 2개이니 관리 포인트도 2배다. 가중치를 바꾸려면 카나리 Ingress의 어노테이션을 수정해야 한다.

Gateway API에서는?

HTTPRoute 하나에서 backendRefs의 weight 필드만 바꾸면 된다:

rules:
  - backendRefs:
      - name: app-v1
        port: 80
        weight: 80    # stable: 80%
      - name: app-v2
        port: 80
        weight: 20    # canary: 20%

가중치를 바꾸고 싶으면? 이 숫자만 수정하면 끝이다. 리소스 1개, 필드 1개.

아래 데모에서 슬라이더를 움직이면 v2의 가중치(weight)가 바뀔 때 트래픽이 어떻게 분배되는지 시각화로 볼 수 있다. 각 원이 하나의 요청이라고 생각하면 된다 - 가중치 비율에 따라 v1(검정) 또는 v2(초록)으로 갈라진다.

App of Apps 패턴에서 Gateway API 적용하기

ArgoCD의 App of Apps 패턴을 쓰고 있다면, Gateway API 리소스를 어디에 넣어야 할지 고민이 된다. 결론부터 말하면, Gateway API의 역할 분리가 App of Apps 계층 구조랑 잘 맞아떨어진다.

구조

root-app/                          # Root Application
├── infra-app/                     # 인프라 레벨
│   ├── envoy-gateway/             # Envoy Gateway Helm chart
│   │   └── (GatewayClass 자동 생성)
│   ├── cert-manager/
│   └── ...
├── platform-app/                  # 플랫폼 레벨
│   ├── gateway.yaml               # Gateway 리소스
│   ├── backend-traffic-policy.yaml # 공통 rate limit 등
│   └── ...
├── app-a/                         # 앱 레벨
│   ├── deployment.yaml
│   ├── service.yaml
│   └── httproute.yaml             # ← 여기!
├── app-b/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── httproute.yaml             # ← 여기!
└── ...

각 레이어가 관리하는 것

infra-app - Envoy Gateway 설치

# infra-app의 Application
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: envoy-gateway
  namespace: argocd
spec:
  destination:
    namespace: envoy-gateway-system
  source:
    repoURL: oci://docker.io/envoyproxy/gateway-helm
    chart: gateway-helm
    targetRevision: v1.3.0

Envoy Gateway Helm chart를 설치하면 GatewayClass가 자동으로 생성된다. 인프라팀 외에는 건드릴 일이 없다.

platform-app - Gateway 리소스

# platform-app이 관리하는 Gateway
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
  namespace: infra
spec:
  gatewayClassName: eg
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-tls
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "true"    # 이 라벨이 있는 NS만 연결 허용

allowedRoutes로 어떤 네임스페이스의 HTTPRoute가 이 Gateway에 붙을 수 있는지 제어한다. 아무 앱이나 함부로 못 붙게 하는 장치다.

각 앱 - HTTPRoute만 관리

# app-a의 Helm chart 또는 kustomize에 포함
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-a-route
  namespace: app-a              # 앱 자기 네임스페이스
spec:
  parentRefs:
    - name: main-gateway
      namespace: infra          # 플랫폼팀이 만든 Gateway 참조
  hostnames:
    - app-a.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: app-a-svc
          port: 80

앱 개발자는 자기 Helm chart에 httproute.yaml만 추가하면 된다. TLS, 인증서, 게이트웨이 구현체가 뭔지 전혀 몰라도 된다.

ArgoCD sync 순서

App of Apps에서 주의할 점은 리소스 생성 순서다:

1. GatewayClass (Envoy Gateway 설치 시 자동 생성)
2. Gateway (GatewayClass가 있어야 생성 가능)
3. HTTPRoute (Gateway가 있어야 parentRefs 참조 가능)

ArgoCD의 Sync Wave로 순서를 보장할 수 있다:

# Gateway에 sync wave 설정
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"    # infra-app(wave 0) 이후에 sync
 
# HTTPRoute는 별도 설정 불필요 - 앱 Application이 나중에 sync 됨

마이그레이션 가이드

병렬 운영 전략

한 번에 전환하는 건 위험하다. Ingress Nginx와 Envoy Gateway를 동시에 운영하면서 점진적으로 옮기는 걸 추천한다.

1. Envoy Gateway 설치 + GatewayClass, Gateway 생성 (기존 Ingress에 영향 없음)
2. 트래픽이 적은 서비스부터 HTTPRoute 생성 + DNS를 새 Gateway로 변경
3. 문제 없으면 다음 서비스로. 문제 있으면 DNS만 돌리면 즉시 롤백

# 기존: Ingress Nginx의 LB IP를 가리킴
app.example.com → 10.0.1.100 (Ingress Nginx)
 
# 전환: Envoy Gateway의 LB IP로 변경
app.example.com → 10.0.2.200 (Envoy Gateway)
 
# 롤백: 다시 원래 IP로 변경하면 끝
app.example.com → 10.0.1.100 (Ingress Nginx)

4. 모든 서비스 전환 완료 후 Ingress Nginx 제거

App of Apps 패턴이면 더 쉽다 - 각 앱의 차트에서 ingress.yaml → httproute.yaml로 바꾸고, 앱별로 하나씩 sync하면 된다.

ingress2gateway 도구

Kubernetes SIG-Network에서 공식 제공하는 ingress2gateway CLI로 기존 Ingress 리소스를 Gateway API 리소스로 자동 변환할 수 있다.

# 설치
go install github.com/kubernetes-sigs/ingress2gateway@latest
 
# 변환 (현재 클러스터의 Ingress 읽어서 변환)
ingress2gateway print
 
# 특정 네임스페이스만
ingress2gateway print --namespace my-app

주의사항 / Gotchas

• 어노테이션 매핑이 1:1이 아니다: nginx 전용 기능은 Envoy Gateway의 SecurityPolicy, BackendTrafficPolicy 등 별도 CRD로 옮겨야 한다.
• IngressClass vs GatewayClass: 기존 ingressClassName: nginx → gatewayClassName: eg (Envoy Gateway 기본값). 이름이 달라서 놓치기 쉽다.
• 기본 경로 매칭 방식이 다르다: Ingress는 기본이 Prefix, Gateway API는 type: PathPrefix를 명시해야 한다.
• Health check 설정 위치 변경: Ingress에서 어노테이션으로 하던 health check가 BackendTrafficPolicy로 이동한다. Health check는 게이트웨이가 주기적으로 백엔드 Pod에 살아있는지 확인하고, 응답 없으면 트래픽을 안 보내는 메커니즘이다.
• CRD 버전 확인: Gateway API CRD v1.2+ 인지 확인. 구 버전에서는 일부 필드(backendRefs.weight 등)가 없을 수 있다.
• cross-namespace 참조: HTTPRoute가 다른 네임스페이스의 Gateway를 참조하려면, Gateway의 allowedRoutes에서 해당 네임스페이스를 허용해야 한다. 빠뜨리면 HTTPRoute가 Accepted: false로 남는다.

요약

Ingress Nginx EOL은 쿠버네티스 네트워킹의 세대 교체다. Gateway API는 Ingress를 그냥 갈아끼우는 게 아니라, 근본적으로 더 나은 구조를 제공한다고 한다.

• 역할 기반 리소스 분리 → 인프라/플랫폼/앱 팀이 각자 영역만 관리
• 표준 API → 구현체(Envoy, Istio, Cilium)를 바꿔도 HTTPRoute는 그대로
• 카나리, 트래픽 미러링 같은 고급 기능이 네이티브
• App of Apps랑 계층 구조가 딱 맞음