Gateway API v1.5: 주요 기능의 안정화 버전(Stable) 전환

Kubernetes SIG Network 커뮤니티에서 Gateway API v1.5 출시 소식을 전해드립니다! 2026년 2월 27일에 출시된 버전 1.5는 역대 최대 규모의 업데이트로, 기존의 실험적(Experimental) 기능들을 표준(Standard, Stable) 채널로 전환하는 데 집중했습니다.

현재 Gateway API v1.5.1 패치 버전도 이미 사용 가능합니다.

Gateway API v1.5는 널리 요청되었던 다음 6가지 기능을 표준 채널(Gateway API의 GA 릴리스 채널)로 승격시켰습니다.

• ListenerSet
• TLSRoute
• HTTPRoute CORS 필터
• 클라이언트 인증서 검증(Client Certificate Validation)
• Gateway TLS 오리진(Origination)을 위한 인증서 선택
• ReferenceGrant

이번 릴리스를 위해 노력해주신 Gateway API 기여자분들께 특별한 감사를 표합니다.

새로운 릴리스 프로세스

Gateway API v1.5부터 프로젝트는 '릴리스 트레인(release train)' 모델로 전환되었습니다. 이 모델에서는 기능 동결(feature freeze) 날짜를 기준으로 준비가 완료된 모든 기능이 릴리스에 포함됩니다.

이 방식은 실험적(Experimental) 기능과 표준(Standard) 기능 모두에 적용되며, 문서화 작업에도 동일하게 적용됩니다. 즉, 문서가 준비되지 않았다면 해당 기능도 출시되지 않습니다.

우리는 Kubernetes 자체의 SIG Release가 수행하는 훌륭한 작업을 벤치마킹하여 더욱 신뢰할 수 있는 릴리스 주기를 만드는 것을 목표로 하고 있습니다. 이러한 변화의 일환으로 릴리스 팀에 릴리스 매니저(Release Manager)와 릴리스 섀도우(Release Shadow) 역할을 도입했습니다. 릴리스 프로세스의 거친 부분을 다듬고 조율하는 데 큰 힘을 써준 Flynn(Buoyant)과 Beka Modebadze(Google)에게 감사를 전합니다. 두 분은 다음 릴리스에서도 이 역할을 계속 수행할 예정입니다.

새로운 표준 기능

ListenerSet

담당자: Dave Protasowski, David Jumani

GEP-1713

ListenerSet이 필요한 이유

ListenerSet이 도입되기 전에는 모든 리스너를 Gateway 객체에 직접 지정해야 했습니다. 간단한 사용 사례에서는 잘 작동했지만, 더 복잡하거나 멀티 테넌트 환경에서는 다음과 같은 어려움이 있었습니다.

• 플랫폼 팀과 애플리케이션 팀이 동일한 Gateway에 대한 변경 사항을 조율해야 하는 경우가 빈번함
• 개별 리스너의 소유권을 안전하게 위임하기 어려움
• 기존 Gateway를 확장하려면 원본 리소스를 직접 수정해야 함

ListenerSet은 리스너를 독립적으로 정의한 후 대상 Gateway에 병합할 수 있도록 하여 이러한 제한 사항을 해결합니다.

또한 ListenerSet을 사용하면 하나의 공유 Gateway에 64개 이상의 리스너를 연결할 수 있습니다. 이는 대규모 배포 환경이나 리스너당 여러 호스트네임을 사용하는 시나리오에서 매우 중요합니다.

ListenerSet 기능이 확장성을 크게 향상시키더라도, Gateway 리소스의 listener 필드는 여전히 필수 사항이며 Gateway에는 최소한 하나 이상의 유효한 리스너가 있어야 합니다.

작동 방식

ListenerSet은 Gateway에 연결되어 하나 이상의 리스너를 제공합니다. Gateway 컨트롤러는 Gateway 리소스 자체의 리스너와 연결된 모든 ListenerSet 리소스의 리스너를 병합하는 책임을 집니다.

다음 예시에서는 중앙 인프라 팀이 기본 HTTP 리스너가 포함된 Gateway를 정의하고, 두 개의 서로 다른 애플리케이션 팀이 별도의 네임스페이스에서 자신들의 ListenerSet 리소스를 정의합니다. 두 ListenerSet은 동일한 Gateway에 연결되어 추가적인 HTTPS 리스너를 제공합니다.

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: example-gateway
 namespace: infra
spec:
 gatewayClassName: example-gateway-class
 allowedListeners:
  namespaces:
   from: All # 셀렉터를 사용하여 이를 세밀하게 조정할 수 있습니다.
 listeners:
 - name: http
   protocol: HTTP
   port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
 name: team-a-listeners
 namespace: team-a
spec:
 parentRef:
  name: example-gateway
  namespace: infra
 listeners:
 - name: https-a
   protocol: HTTPS
   port: 443
   hostname: a.example.com
   tls:
    certificateRefs:
    - name: a-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
 name: team-b-listeners
 namespace: team-b
spec:
 parentRef:
  name: example-gateway
  namespace: infra
 listeners:
 - name: https-b
   protocol: HTTPS
   port: 443
   hostname: b.example.com
   tls:
    certificateRefs:
    - name: b-cert

TLSRoute

담당자: Rostislav Bobrovsky, Ricardo Pchevuzinske Katz

GEP-2643

TLSRoute 리소스를 사용하면 TLS 핸드셰이크 중에 클라이언트가 제시한 SNI(Server Name Indication)를 매칭하여 요청을 라우팅하고, 해당 스트림을 적절한 Kubernetes 백엔드로 전달할 수 있습니다.

TLSRoute를 사용할 때 Gateway의 TLS 리스너는 Passthrough(통과) 또는 Terminate(종료)의 두 가지 모드 중 하나로 구성될 수 있습니다.

만약 v1.4 또는 그 이전의 실험적(Experimental) 버전을 사용하다가 Gateway API v1.5 표준(Standard) 버전을 설치하는 경우, 기존의 실험적 TLSRoute를 사용할 수 없게 됩니다. 이는 기존 리소스가 v1.5 표준 YAML에 포함되지 않은 v1alpha2 또는 v1alpha3 버전으로 저장되어 있기 때문입니다. 이 경우 v1.5.1 이상의 실험적 버전을 계속 사용하거나, TLSRoute를 표준 YAML에 포함된 v1 버전으로 다운로드하여 마이그레이션해야 합니다.

Passthrough(통과) 모드

Passthrough 모드는 엄격한 보안 요구 사항을 위해 설계되었습니다. 트래픽이 대상 백엔드에 도달할 때까지 종단 간(End-to-End) 암호화 상태를 유지해야 하거나, 외부 클라이언트와 백엔드가 직접 서로를 인증해야 하는 경우, 또는 Gateway에 인증서를 저장할 수 없는 시나리오에 적합합니다. 또한 표준 HTTP 트래픽 대신 암호화된 TCP 스트림이 필요한 경우에도 적용됩니다.

이 모드에서 암호화된 바이트 스트림은 대상 백엔드로 직접 프록시됩니다. Gateway는 개인 키나 복호화된 데이터에 전혀 접근할 수 없습니다.

다음 TLSRoute는 Passthrough 모드로 구성된 리스너에 연결됩니다. foo.example.com SNI 호스트네임을 가진 TLS 핸드셰이크만 매칭하여 암호화된 TCP 스트림을 구성된 백엔드로 전달합니다.

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: example-gateway
spec:
 gatewayClassName: example-gateway-class
 listeners:
 - name: tls-passthrough
   protocol: TLS
   port: 8443
   tls:
    mode: Passthrough
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
 name: foo-route
spec:
 parentRefs:
 - name: example-gateway
   sectionName: tls-passthrough
 hostnames:
 - "foo.example.com"
 rules:
 - backendRefs:
   - name: foo-svc
     port: 8443

Terminate(종료) 모드

Terminate 모드는 Gateway에서 직접 TLS 인증서를 중앙 집중식으로 관리할 수 있는 편의성을 제공합니다.

이 모드에서는 TLS 세션이 Gateway에서 완전히 종료되며, Gateway는 복호화된 페이로드를 일반 텍스트 TCP 스트림으로 대상 백엔드에 라우팅합니다.

다음 TLSRoute는 Terminate 모드로 구성된 리스너에 연결됩니다. bar.example.com SNI 호스트네임을 가진 TLS 핸드셰이크만 매칭하여 복호화된 TCP 스트림을 구성된 백엔드로 전달합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: example-gateway
spec:
 gatewayClassName: example-gateway-class
 listeners:
 - name: tls-terminate
   protocol: TLS
   port: 443
   tls:
    mode: Terminate
    certificateRefs:
    - name: tls-terminate-certificate
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
 name: bar-route
spec:
 parentRefs:
 - name: example-gateway
   sectionName: tls-terminate
 hostnames:
 - "bar.example.com"
 rules:
 - backendRefs:
   - name: bar-svc
     port: 8080

HTTPRoute CORS 필터

담당자: Damian Sawicki, Ricardo Pchevuzinske Katz, Norwin Schnyder, Huabing (Robin) Zhao, LiangLliu

GEP-1767

교차 출처 리소스 공유(CORS)는 웹 페이지가 해당 페이지를 제공한 도메인과 다른 출처(Origin)의 서버 리소스에 접근할 수 있도록 허용(또는 거부)하는 HTTP 헤더 기반 보안 메커니즘입니다. 자세한 내용은 문서 페이지를 참조하세요. HTTPRoute 리소스를 사용하여 CORS를 구성할 수 있습니다. 다음 HTTPRoute는 https://app.example로부터의 요청을 허용합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: cors
spec:
 parentRefs:
 - name: same-namespace
 rules:
 - matches:
   - path:
      type: PathPrefix
      value: /cors-behavior-creds-false
   backendRefs:
   - name: infra-backend-v1
     port: 8080
   filters:
   - cors:
      allowOrigins:
      - https://app.example
     type: CORS

특정 출처 목록을 지정하는 대신 와일드카드("*")를 지정하여 모든 출처를 허용할 수도 있습니다. 또한 호스트네임 시작 부분이나 스킴 뒤에 와일드카드를 사용하는 부분 지정 방식(예: https://*.bar.com)도 허용됩니다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: cors
spec:
 parentRefs:
 - name: same-namespace
 rules:
 - matches:
   - path:
      type: PathPrefix
      value: /cors-behavior-creds-false
   backendRefs:
   - name: infra-backend-v1
     port: 8080
   filters:
   - cors:
      allowOrigins:
      - https://www.baz.com
      - https://*.bar.com
      - https://*.foo.com
     type: CORS

HTTPRoute 필터는 다음과 같은 CORS 설정 옵션을 지원합니다.

allowCredentials : 브라우저가 CORS 요청에 자격 증명(쿠키, HTTP 인증 등)을 포함할 수 있는지 여부를 지정합니다.

allowMethods : CORS 요청에 허용되는 HTTP 메서드입니다.

allowHeaders : CORS 요청에 허용되는 HTTP 헤더입니다.

exposeHeaders : 클라이언트에 노출되는 HTTP 헤더입니다.

maxAge : 브라우저가 프리플라이트(preflight) 응답을 캐시해야 하는 최대 시간(초)입니다.

포괄적인 설정 예시는 다음과 같습니다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: cors-allow-credentials
spec:
 parentRefs:
 - name: same-namespace
 rules:
 - matches:
   - path:
      type: PathPrefix
      value: /cors-behavior-creds-true
   backendRefs:
   - name: infra-backend-v1
     port: 8080
   filters:
   - cors:
      allowOrigins:
      - "https://www.foo.example.com"
      - "https://*.bar.example.com"
      allowMethods:
      - GET
      - OPTIONS
      allowHeaders:
      - "*"
      exposeHeaders:
      - "x-header-3"
      - "x-header-4"
      allowCredentials: true
      maxAge: 3600
     type: CORS

Gateway 클라이언트 인증서 검증

담당자: Arko Dasgupta, Katarzyna Łach, Norwin Schnyder

GEP-91

상호 TLS(mTLS)라고도 하는 클라이언트 인증서 검증은 클라이언트가 자신의 신원을 증명하기 위해 서버에 인증서를 제공하는 보안 메커니즘입니다. 이는 서버만 클라이언트에 인증서를 제시하는 표준 TLS와 대조됩니다. Gateway API의 맥락에서 프론트엔드 mTLS는 Gateway가 백엔드 서비스로의 연결을 허용하기 전에 클라이언트의 인증서를 검증함을 의미합니다. 이 검증은 Gateway에 구성된 신뢰할 수 있는 인증 기관(CA) 세트와 클라이언트 인증서를 대조하여 수행됩니다. 이 API는 연결 재사용과 관련된 중대한 보안 취약점을 해결하는 동시에 어느 정도의 유연성을 제공하도록 설계되었습니다.

구성 개요

클라이언트 검증은 Gateway가 클라이언트의 신원을 확인하는 방법을 지정하는 frontendValidation 구조체를 사용하여 정의됩니다.

• caCertificateRefs: 클라이언트 인증서를 검증하는 데 신뢰 앵커(trust anchor)로 사용되는 PEM 인코딩된 CA 인증서 번들이 포함된 Kubernetes 객체(일반적으로 ConfigMap)에 대한 참조 목록입니다.
• mode: 검증 동작을 정의합니다.
  • AllowValidOnly (기본값): 클라이언트가 지정된 CA 번들을 통해 검증을 통과한 유효한 인증서를 제시하는 경우에만 연결을 수락합니다.
  • AllowInsecureFallback: 클라이언트 인증서가 없거나 검증에 실패하더라도 연결을 수락합니다. 이 모드는 일반적으로 권한 부여를 백엔드에 위임하며 주의해서 사용해야 합니다.

검증은 Gateway에 전역적으로 적용하거나 특정 포트에 대해 재정의할 수 있습니다.

1. 기본 구성: 포트별 재정의가 정의되지 않은 경우 Gateway의 모든 HTTPS 리스너에 적용됩니다.
2. 포트별 구성: 특정 포트에서 트래픽을 처리하는 모든 리스너에 대해 기본 구성을 재정의하여 세밀한 제어가 가능합니다.

예시:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: client-validation-basic
spec:
 gatewayClassName: acme-lb
 tls:
  frontend:
   default:
    validation:
     caCertificateRefs:
     - kind: ConfigMap
       group: ""
       name: foo-example-com-ca-cert
   perPort:
   - port: 8443
     tls:
      validation:
       caCertificateRefs:
       - kind: ConfigMap
         group: ""
         name: foo-example-com-ca-cert
       mode: "AllowInsecureFallback"
 listeners:
 - name: foo-https
   protocol: HTTPS
   port: 443
   hostname: foo.example.com
   tls:
    certificateRefs:
    - kind: Secret
      group: ""
      name: foo-example-com-cert
 - name: bar-https
   protocol: HTTPS
   port: 8443
   hostname: bar.example.com
   tls:
    certificateRefs:
    - kind: Secret
      group: ""
      name: bar-example-com-cert

Gateway TLS 오리진(Origination)을 위한 인증서 선택

담당자: Marcin Kosieradzki, Rob Scott, Norwin Schnyder, Lior Lieberman, Katarzyna Lach

GEP-3155

업스트림 연결을 위한 상호 TLS(mTLS)는 Gateway가 백엔드의 인증서를 검증하는 것 외에도 백엔드에 클라이언트 인증서를 제시해야 합니다. 이를 통해 백엔드는 승인된 Gateway의 연결만 수락하도록 보장할 수 있습니다.

Gateway의 클라이언트 인증서 구성

Gateway가 백엔드에 연결할 때 사용하는 클라이언트 인증서를 구성하려면 Gateway 리소스의 tls.backend.clientCertificateRef 필드를 사용합니다. 이 구성은 해당 Gateway가 관리하는 모든 업스트림 연결에 대해 클라이언트로서의 Gateway에 적용됩니다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: backend-tls
spec:
 gatewayClassName: acme-lb
 tls:
  backend:
   clientCertificateRef:
    kind: Secret
    group: "" # 빈 문자열은 코어 API 그룹을 의미합니다.
    name: foo-example-cert
 listeners:
 - name: foo-http
   protocol: HTTP
   port: 80
   hostname: foo.example.com

ReferenceGrant의 v1 승격

ReferenceGrant 리소스는 1년 넘게 변경되지 않았으며 앞으로도 변경될 것으로 예상되지 않습니다. 따라서 버전이 v1으로 상향 조정되었으며, 이제 공식적으로 표준 채널에 포함되어 GA API 계약(즉, 하위 호환성을 깨는 변경 없음)을 따릅니다.

시도해 보기

다른 Kubernetes API와 달리, 최신 버전의 Gateway API를 사용하기 위해 Kubernetes를 최신 버전으로 업그레이드할 필요는 없습니다. Kubernetes 1.30 이상을 실행 중이라면 이 버전의 Gateway API를 바로 사용할 수 있습니다.

API를 사용해 보려면 시작 가이드를 따르세요.

이 글을 쓰는 시점을 기준으로 7개의 구현체가 이미 Gateway API v1.5를 완벽하게 준수하고 있습니다(알파벳순).

• Agentgateway
• Airlock Microgateway
• GKE Gateway
• HAProxy Ingress
• kgateway
• NGINX Gateway Fabric
• Traefik Proxy

참여하기

특정 기능이 언제 추가될지 궁금하신가요? 인그레스(Ingress)와 서비스 메시(Service Mesh)를 위한 Kubernetes 라우팅 API의 미래를 정의하고 참여할 기회는 많습니다.

• 사용자 가이드를 확인하여 어떤 사용 사례를 해결할 수 있는지 알아보세요.
• 기존 Gateway 컨트롤러 중 하나를 사용해 보세요.
• 또는 커뮤니티에 가입하여 함께 Gateway API의 미래를 만들어가요!

메인테이너들은 리포지토리에 대한 커밋, 토론, 아이디어 제시 또는 일반적인 지원을 통해 Gateway API에 기여해 주신 모든 분께 감사를 표하고 싶습니다. 이 전념적이고 활발한 커뮤니티의 지원 없이는 이러한 진전을 이룰 수 없었을 것입니다.

이 기사는 Gateway API 1.5.0의 출시일을 수정하기 위해 2026년 4월에 편집되었습니다.