2026년 8월 Kubernetes SIG Network가 소개한 Gateway API v1.6은 이 공백을 줄였습니다. TCPRoute와 UDPRoute가 gateway.networking.k8s.io/v1의 Standard API로 승격됐고, 새로운 실험 리소스는 gateway.networking.x-k8s.io라는 별도 API group과 X 접두사로 분리됩니다. 공식 발표는 이 변경을 L4 routing과 experimental boundary를 명확히 하는 단계로 설명합니다. 다만 Standard라는 말은 “모든 Gateway controller에서 지금 즉시 같은 기능을 쓸 수 있다"는 뜻이 아닙니다. controller 구현·conformance·운영 정책을 확인하는 일이 여전히 남습니다.

참고한 공식 문서:

• Kubernetes: Gateway API v1.6 — TCPRoute·UDPRoute Standard 승격 — Standard/Experimental 경계와 L4 route의 배경
• Gateway API TCP routing guide — TCP listener와 TCPRoute attachment 구성
• Gateway API UDP routing guide — UDP listener와 UDPRoute의 기본 모델
• Gateway API v1.6 release notes — CRD와 릴리스 세부 변경점

이 글은 앞서 다룬 Gateway API와 Ambient Mesh의 수렴, Kubernetes Rollout 전략, Service Mesh/Istio 심화에서 한 단계 더 들어가, L4 route를 실제 서비스 계약으로 승격할 조건에 초점을 맞춥니다.

이 글에서 얻는 것

• Gateway API v1.6의 TCPRoute·UDPRoute Standard 승격과 controller 구현 지원을 구분할 수 있습니다.
• L4 route가 HTTPRoute와 다른 이유, 특히 listener·port·backend 경계의 운영 영향을 설명할 수 있습니다.
• gateway.networking.k8s.io와 gateway.networking.x-k8s.io의 분리가 왜 API 안정성의 신호인지 이해할 수 있습니다.
• 기존 Service/LB 또는 전용 CRD에서 안전하게 옮길 수 있는 inventory, canary, rollback 숫자를 얻습니다.

핵심 개념/이슈

1) Standard API는 이식성 계약의 시작점이지 자동 배포 승인이 아니다

v1.6에서 TCPRoute와 UDPRoute는 v1alpha2 Experimental channel에서 v1 Standard API로 올라갔습니다. Gateway의 listener가 각각 TCP 또는 UDP protocol을 열고 route attachment를 허용하면, route는 port와 protocol 기준으로 backend Service를 가리킵니다. 이 모델은 HTTP path·header를 이해하지 않는 raw L4 트래픽에도 Gateway API의 role-oriented ownership과 route attachment 모델을 적용하게 합니다.

그러나 팀이 확인해야 할 대상은 API 문서 하나가 아닙니다. 클러스터의 GatewayClass와 실제 controller가 해당 route kind·protocol·정책 조합을 지원하는지, 설치된 CRD가 v1.6인지, 운영 controller 버전이 release note의 conformance 범위와 맞는지를 함께 확인해야 합니다. 공식 발표도 v1.6 기준 conformance 구현 목록을 제공하지만, 이는 발표 시점의 목록이며 팀의 사용 중인 provider 설정과 optional feature까지 보장하지는 않습니다.

따라서 배포 전 질문은 “TCPRoute가 Standard인가?“보다 아래 순서가 낫습니다.

1. 우리 controller와 GatewayClass가 TCPRoute 또는 UDPRoute를 실제로 지원하는가?
2. 현재 listener·port·namespace attachment 정책에서 어느 팀이 route를 붙일 수 있는가?
3. L4 traffic의 연결 수, handshake 실패, p99, packet/error metric을 기존 Service 경로와 같은 수준으로 볼 수 있는가?
4. 문제가 생기면 route를 삭제하거나 weight를 되돌리는 것만으로 기존 LB/Service 경로로 복귀할 수 있는가?

이 네 질문 중 하나라도 불명확하면 Standard API여도 production migration이 아니라 isolated canary로 분류하는 것이 맞습니다. Kubernetes 점진 배포에서 말하는 “선택지의 존재"와 “운영 가능한 경로"의 차이가 네트워킹에도 그대로 적용됩니다.

2) L4 라우팅의 단위는 URL이 아니라 listener와 port다

HTTPRoute는 hostname, path, header처럼 사람이 읽기 쉬운 요청 속성을 기준으로 세분화할 수 있습니다. TCPRoute와 UDPRoute는 raw protocol을 L7까지 해석하지 않고, listener의 protocol·port와 backend ref를 중심으로 붙습니다. 이것이 장점인 이유는 HTTP가 아닌 프로토콜도 이식 가능한 API에 들어오기 때문이지만, 동시에 route 하나의 blast radius가 더 넓어질 수 있음을 뜻합니다.

공식 예시에서 TCP listener는 protocol: TCP, port: 12345로 열리고 allowedRoutes.kinds에 TCPRoute를 명시합니다. TCPRoute가 parentRefs.sectionName으로 해당 listener를 지정하면 backend Service의 endpoint와 port로 전달됩니다. 반대로 sectionName과 port를 생략하면 compatible TCP listener 모두에 attach될 수 있습니다. 실무에서는 편리한 생략이 아니라 예상 밖 listener에 붙을 수 있는 위험 신호로 봐야 합니다.

특히 장시간 연결이나 상태를 가진 TCP 서비스는 단순 health check가 통과했다고 전환 성공으로 볼 수 없습니다. 10분 이상 유지되는 connection이 재배포·endpoint 교체·controller reload 중에도 어떻게 끊기고 재연결되는지, client retry가 중복 effect를 만드는지, connection drain이 기존 노드와 새 노드에서 일관되는지를 확인해야 합니다. 관련 원칙은 Long-lived connection draining과 end-to-end deadline·cancellation에서 그대로 가져올 수 있습니다.

3) API group 분리는 “실험 기능을 알아보기 쉽게 하라"는 운영 장치다

이전에는 Experimental 리소스가 Standard 리소스와 같은 gateway.networking.k8s.io group을 쓰고 v1alpha2 같은 version 표기로만 구분됐습니다. v1.6부터 새 Experimental 리소스는 gateway.networking.x-k8s.io group에 XBackend, XMesh처럼 X 접두사로 들어갑니다. Standard로 승격될 때는 standard group으로 이동하고 이름에서 X가 빠지는 방식입니다.

이 변화는 YAML의 경로가 하나 늘어난 정도가 아닙니다. cluster policy, admission rule, GitOps allowlist, RBAC, CRD lifecycle에서 실험 기능을 명시적으로 격리할 수 있게 합니다. 예를 들어 platform team은 gateway.networking.k8s.io/v1만 production namespace에 허용하고, gateway.networking.x-k8s.io/*는 sandbox namespace와 별도 review label에서만 허용할 수 있습니다. 사용자가 experimental resource를 standard처럼 복사하는 실수를 policy layer에서 줄일 수 있습니다.

공식 발표에 나온 XBackend의 ExternalHostname destination 사례는 이 원칙이 특히 중요한 이유를 보여 줍니다. 외부 hostname backend는 egress와 AI provider 호출 같은 use case에 유용할 수 있지만, 잘못 열면 workload가 예상 밖 destination으로 나가는 confused-deputy 위험을 키울 수 있습니다. 발표도 XBackend를 Experimental이며 production 준비 상태로 가정하지 말라고 명시합니다. 이 기능을 실제로 검토한다면 SSRF와 egress control의 hostname allowlist, DNS 재확인, private IP 차단, audit 원칙을 먼저 적용해야 합니다.

4) “기존 Service를 전부 바꾸기"보다 protocol별 파일럿이 낫다

L4 Gateway API migration의 첫 목표는 네트워크 리소스 통일이 아니라, controller가 제공하는 route contract가 실제 client protocol과 맞는지 증명하는 것입니다. 따라서 파일럿은 가장 단순한 내부 TCP 또는 UDP 서비스 하나로 제한합니다. 외부 고객이 바로 접속하는 primary DB, DNS authoritative path, 결제 partner socket을 첫 대상으로 잡지 않습니다.

아래와 같은 4단계가 현실적입니다.

1단계: inventory(1주)

• Service type=LoadBalancer, NodePort, 전용 controller CRD, ExternalName 사용처를 protocol·port·owner별로 나눕니다.
• HTTP가 아닌 TCP/UDP traffic에서 client 수, 평균/최대 session 길이, connection error, packet drop, backend endpoint 수를 baseline으로 만듭니다.
• TCPRoute/UDPRoute 지원 여부를 controller release와 GatewayClass configuration에서 확인하고, 지원하지 않는 optional feature는 표에 “미지원"으로 남깁니다.

2단계: isolated route(1주)

• 별도 Gateway와 새 port를 사용해 내부 테스트 client만 연결합니다.
• allowedRoutes와 namespace selector를 닫고, parentRefs.sectionName을 반드시 지정합니다.
• 정상이 아닌 입력, 연결 중 backend restart, DNS/endpoint 변경, timeout, client reconnect를 함께 시험합니다.

3단계: 제한된 canary(1~2주)

• 트래픽을 분할할 수 있는 protocol이면 1% 이하의 client cohort 또는 테스트 tenant로 시작합니다. 분할이 어려운 raw TCP라면 별도 port/hostname이나 read-only 업무 경로를 사용합니다.
• 15분 창에서 connection error가 baseline보다 +0.1%p 이상, p99가 +20% 이상, reconnect storm이 baseline의 2배 이상이면 자동 승격을 멈추고 원래 경로로 복귀합니다.

4단계: 승격 또는 보류

• 7일 동안 protocol 오류·connection churn·backend saturation·온콜 알람 품질을 비교합니다.
• 목표가 “리소스 수 감소” 하나뿐이면 확대하지 않습니다. portability, policy ownership, rollback, observability 중 최소 두 축에서 개선 근거가 있을 때만 다음 서비스로 넓힙니다.

실무 적용

1) 플랫폼·제품·보안의 소유권을 리소스에 맞춰 나눈다

Gateway API는 route를 application team이 작성할 수 있게 하면서도 Gateway와 listener를 platform team이 운영하도록 역할을 나누는 모델입니다. L4에서는 포트 하나가 더 넓은 영향 범위를 갖기 때문에 이 구분을 더 엄격하게 두는 편이 좋습니다.

이 표에서 가장 중요한 것은 제품 팀이 parentRefs만 작성한다고 해서 포트의 영향 범위가 자동으로 작아지지 않는다는 점입니다. platform team은 allowedRoutes로 attachment 권한을 제한하고, 동일 port에 누가 route를 붙일 수 있는지 review에서 확인해야 합니다. Admission control과 concurrency limit이 backend의 폭주를 막는다면, listener attachment policy는 네트워크 제어면의 폭주를 막는 장치입니다.

2) 관측과 rollback을 manifest보다 먼저 준비한다

L4 migration은 YAML apply 성공 여부가 아니라 client-level success로 판정합니다. 최소 대시보드에는 listener별 active connection, new connection rate, connection error/timeout, bytes in/out, backend ready endpoint, gateway CPU·memory, client-side p95/p99가 있어야 합니다. HTTP status code가 없는 프로토콜이라면 handshake success나 application-level response를 별도 synthetic probe로 정의해야 합니다.

rollback은 “route YAML을 되돌린다"보다 구체적이어야 합니다. DNS TTL, client connection pool, long-lived socket, connection drain 때문에 control plane 변경 직후에도 client가 이전 또는 새 경로를 계속 쓸 수 있습니다. rollback runbook에는 다음을 기록합니다.

• 어떤 manifest/Helm release를 되돌리는가
• 새 connection을 어느 경로로 끊고, 기존 connection을 몇 분까지 drain할 것인가
• DNS, client config, firewall/LB rule 중 함께 복귀할 의존성이 있는가
• 5분, 15분, 60분 후 어떤 metric으로 “복귀 완료"를 확인하는가

처음 파일럿에서 권장할 만한 gate는 connection_error +0.1%p, p99 +20%, backend saturation +15%p 중 하나가 15분 지속하면 즉시 확대를 멈추는 것입니다. 사업상 중요도가 높은 socket에는 더 보수적인 기준을 써야 합니다. 반대로 정상 목표도 수치로 둡니다. 예를 들어 7일간 p99가 baseline 대비 +5% 이내이고, 재연결 오류가 +0.05%p 미만이며, route 변경 리드타임이 20% 이상 줄어야 다음 cohort로 승격합니다.

3) 실험 API는 별도 lifecycle으로 다룬다

gateway.networking.x-k8s.io resource를 발견했다고 standard API의 미래 버전으로 선도 도입할 이유는 없습니다. 실험 API는 schema·동작·지원 범위가 변할 수 있다는 계약입니다. 아래 조건을 모두 만족하지 않으면 production application namespace에 넣지 않는 것을 기본으로 둡니다.

1. workload와 namespace가 sandbox 또는 isolated environment다.
2. manifest에 explicit allowlist와 owner가 있고, 자동 확장·자동 promotion 경로가 없다.
3. egress나 external hostname을 쓰면 destination host, DNS resolution, TLS, redirect/재시도 정책이 별도 audit 대상이다.
4. 실험 API가 변경·제거됐을 때 원래 Service 또는 Standard Gateway API로 복귀할 설계가 있다.
5. controller upgrade 전후 conformance test와 negative test를 재실행한다.

이 규칙은 신기능을 막기 위한 것이 아니라, Standard API로 승격된 TCPRoute/UDPRoute의 이점을 실험 resource의 변동성에 섞지 않기 위한 경계입니다. 운영 시스템에서 “API group만 다르다"는 차이는 RBAC, GitOps policy, cluster upgrade, 복구 비용에서 큰 차이가 됩니다.

트레이드오프/주의점

첫째, TCPRoute와 UDPRoute가 Standard가 됐다고 L7 기능이 L4에 자동으로 생기지는 않습니다. path/header 기반 분기, HTTP status 중심 알람, 애플리케이션 의미의 retry는 raw protocol의 제어면 밖에 있을 수 있습니다. 기존 controller 전용 기능을 옮길 때는 YAML 모양이 비슷한지보다 client protocol의 실패 semantics가 유지되는지를 먼저 비교해야 합니다.

둘째, portability와 운영 단순화는 보통 controller별 세부 기능을 일부 포기하는 대가를 갖습니다. 특정 vendor의 advanced LB integration, proxy protocol, health check, session affinity가 필요하다면 Standard core와 implementation-specific extension을 의도적으로 분리해 문서화해야 합니다. 숨은 annotation 하나에 의존하면 다음 controller 교체 때 다시 종속됩니다.

셋째, UDP는 connection 개념이 약하고 application-level ack가 없는 경우도 많습니다. TCP용 active connection과 handshake 지표를 그대로 가져오면 정상/장애를 오판할 수 있습니다. DNS, telemetry, 게임처럼 프로토콜마다 성공 신호와 손실 허용치를 따로 정의해야 하며, UDP는 packet drop·응답률·재시도·backend queue를 함께 봐야 합니다.

넷째, external backend와 egress는 특히 조심해야 합니다. Experimental XBackend가 외부 hostname을 가리킬 수 있다는 사실은 기능 편의가 아니라 새로운 outbound 권한 경계입니다. hostname allowlist, DNS rebinding 방어, private address 차단, TLS hostname verification, audit 없이 “Gateway가 관리하니 안전하다"고 가정하면 안 됩니다.

체크리스트 또는 연습

체크리스트

• 사용 중인 controller·GatewayClass·CRD 버전이 TCPRoute/UDPRoute 지원과 맞는지 확인했다.
• 모든 L4 route에 parentRefs.sectionName과 명시적 backend port를 넣었다.
• allowedRoutes와 namespace 정책으로 누가 listener에 attach할 수 있는지 제한했다.
• 서비스별로 protocol, port, client 수, 장기 connection 비율, baseline p99와 error rate를 기록했다.
• canary의 중단 조건과 기존 Service/LB 경로 복귀 절차가 15분 단위 검증까지 포함한다.
• HTTP 지표가 없는 프로토콜에 application-level synthetic probe 또는 성공 신호를 정의했다.
• gateway.networking.x-k8s.io resource는 sandbox·owner·allowlist·exit plan 없이 production에 들어가지 않는다.

연습 과제

1. 현재 클러스터의 non-HTTP Service 5개를 골라 protocol, port, exposure, controller 전용 CRD 의존성, rollback 난이도를 한 표에 적어 보세요. 첫 파일럿 후보는 external customer impact가 가장 낮고 client test가 있는 서비스로 고릅니다.
2. TCP listener 하나에 대해 allowedRoutes, sectionName, namespace selector를 명시한 Gateway와 TCPRoute manifest를 작성해 보세요. sectionName을 생략한 변형도 만들어 어떤 listener에 붙는지 test cluster에서 비교합니다.
3. 15분 canary 대시보드에 connection error, p99, reconnect rate, backend saturation, synthetic success를 넣고, 세 지표 중 하나가 임계치를 넘을 때 실행할 rollback 명령과 검증 시각을 runbook으로 작성합니다.

Gateway API v1.6의 핵심은 TCP·UDP YAML을 새로 외우는 데 있지 않습니다. L4 traffic을 controller 전용 설정이 아니라 Standard API, 명시적 attachment, conformance, rollback으로 다룰 수 있는 운영 계약으로 올리는 것입니다. API 안정성의 경계가 더 분명해진 만큼, 팀도 Standard 도입과 Experimental 탐색을 같은 배포 규칙으로 섞지 않아야 합니다.

관련 글

• Gateway API와 Ambient Mesh 수렴
• Kubernetes 점진 배포 전략
• Istio/Service Mesh 심화
• Long-lived Connection Draining 플레이북
• SSRF와 Egress Control