최근 Gateway API 구성을 위한 공부를 시작했는데요.
Gateway API의 TLS 블록 관련해서 공식 페이지에 있는 내용을 살펴보면 아래와 같은 최소한의 예제만 나와 있어서요.
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
spec:
gatewayClassName: example-class
listeners:
- name: http
protocol: HTTP
port: 80
정작 도움이 필요한 TLS 블록에 대한 내용이 없어서 문의드립니다.
Gateway API를 막 보기 시작하면, 공식 문서의 예제가 오히려 더 헷갈릴 때가 많습니다. 말씀 주신 것처럼 TLS 이야기를 보고 들어갔는데, 정작 예제는 HTTP 80 포트 하나만 덜렁 나와 있으면 “그럼 TLS는 어디서 어떻게 붙이라는 거지?”라는 생각이 드는 게 정상입니다.
이건 문서가 불친절해서라기보다는, Gateway API가 의도적으로 최소 단위만 보여 주는 방식을 택하고 있기 때문입니다. 처음 나오는 예제는 “Gateway라는 리소스는 이런 모양이다”를 보여 주는 수준이고, TLS는 그 다음 단계로 넘어가야 등장합니다.
Gateway API에서 TLS는 Ingress처럼 annotation으로 대충 붙이는 개념이 아닙니다.
Listener 단위의 명시적인 설정으로 들어갑니다. 쉽게 말하면, “이 포트는 HTTPS이고, 이 인증서를 쓴다”를 Listener에 정확히 적어 주는 구조입니다.
그래서 TLS가 들어간 Gateway는 보통 이런 모양이 됩니다.
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
spec:
gatewayClassName: example-class
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- kind: Secret
name: example-tls
여기서 중요한 포인트를 몇 가지만 짚어보면 좋겠습니다.
먼저 protocol: HTTPS입니다.
Ingress에서는 TLS 여부가 설정에 숨어 있었지만, Gateway API에서는 프로토콜 자체가 HTTPS로 명시됩니다. 이 Listener는 처음부터 “암호화된 트래픽만 받는다”는 선언입니다.
그 다음 tls.mode: Terminate인데, 이건 “TLS를 어디서 끝낼 것인가”를 의미합니다.
Terminate는 Gateway(로드밸런서, 인그레스 컨트롤러 역할을 하는 지점)에서 TLS를 종료하겠다는 뜻입니다. 지금 단계에서는 이게 가장 흔한 선택입니다.
certificateRefs는 말 그대로 참조입니다.
Ingress처럼 secretName 하나 적는 게 아니라, 이 Listener가 어떤 인증서를 쓸지 명시적으로 참조합니다. 이 구조 덕분에 나중에는 Secret 말고도 다른 형태의 인증서 소스를 붙일 수 있게 설계되어 있습니다.
여기까지 보면 “결국 Ingress TLS랑 비슷한데 왜 이렇게 복잡해 보이지?”라는 느낌이 들 수 있습니다.
그런데 Gateway API의 의도는, TLS를 단순한 옵션이 아니라 트래픽 계약의 일부로 끌어올리는 데 있습니다.
Ingress에서는
“80으로도 받고, 443으로도 받고, TLS는 있으면 좋고…”
같은 설정이 한 리소스 안에 섞여 있었습니다.
Gateway API에서는
“이 포트는 HTTP다”
“이 포트는 HTTPS다”
“이 포트는 이 인증서를 쓴다”
가 전부 분리되어 있고, 읽는 사람 입장에서도 훨씬 명확합니다.
그래서 공식 문서의 첫 예제가 HTTP만 있는 것도 어느 정도 의도가 있습니다.
TLS까지 한 번에 보여 주면, Gateway API의 구조 자체가 잘 안 들어오기 때문입니다. 먼저 Listener 개념에 익숙해지고, 그 다음에 TLS 블록을 얹으라는 흐름입니다.
정리하면, 지금 보신 예제는 “TLS를 안 쓰는 Gateway”가 아니라
**“Gateway라는 리소스의 최소 형태”**라고 이해하시면 됩니다.
TLS는 Listener를 HTTPS로 선언하는 순간부터 자연스럽게 따라오는 다음 단계입니다.
Gateway API를 공부하실 때는
“TLS를 어디에 붙이지?”보다는
“이 Listener는 어떤 트래픽 계약을 가지는가?”라는 관점으로 보시면, 이후 mTLS나 SNI 같은 개념도 훨씬 덜 부담스럽게 이어질 겁니다.
조금 더 보다 보면, Ingress에서 왜 항상 TLS가 헷갈렸는지도 같이 보이기 시작하실 거예요.
완전 감사요!