Kubernetes 기초 (5편): Ingress 와 Gateway API

1. 개요

Service 만으로도 외부에 노출은 된다. 하지만 서비스마다 외부 IP 와 포트를 하나씩 차지하고, 호스트 이름이나 경로에 따라 나누는 일, TLS 인증서 처리는 Service 가 해 주지 않는다. 이 일은 HTTP 를 이해하는 프록시가 해야 한다. 프록시가 왜 필요한지는 인프라 기초 2 - 리버스 프록시는 왜 필요한가에 적었고, 이 글은 그것을 쿠버네티스 안에서 선언하는 방법이다.

---

2. 핵심 내용

2-1. 요청이 들어오는 길

flowchart LR
    C[클라이언트] --> LB[외부 진입점<br/>LoadBalancer]
    LB --> P[프록시 Pod<br/>Envoy, nginx 등]
    P -->|호스트·경로 규칙| S1[Service a]
    P --> S2[Service b]
    S1 --> A[Pod]
    S2 --> B[Pod]

실제로 트래픽을 받는 것은 프록시 Pod 다. 쿠버네티스가 하는 일은 “어떤 호스트와 경로를 어느 Service 로 보낼지” 라는 규칙을 리소스로 받아 그 프록시의 설정으로 바꿔 주는 것이다. 1편의 선언과 조정이 여기서도 그대로다.

2-2. Ingress 와 그 한계

Ingress 는 이 규칙을 담는 오래된 리소스다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
spec:
  tls:
    - hosts: [example.com]
      secretName: web-tls
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port: { number: 80 }

Ingress 자체는 규칙만 적을 뿐이고, 실제 동작은 별도로 설치한 Ingress 컨트롤러가 한다. 한계는 표현력이다. 표준 필드에는 호스트와 경로 매칭 정도만 있어서, 헤더 매칭이나 가중치 분산, 리다이렉트 같은 것은 구현체별 어노테이션으로 푼다. 그 어노테이션은 컨트롤러마다 달라서 이식이 안 된다. 그리고 한 리소스에 인프라 담당자의 관심사(진입점, 인증서)와 앱 담당자의 관심사(경로 규칙)가 섞여 있다.

2-3. Gateway API 의 역할 분리

Gateway API 는 이 문제를 리소스를 쪼개서 푼다.

리소스	누가	무엇을
GatewayClass	인프라 제공자	어떤 구현체(컨트롤러)를 쓰는가
Gateway	클러스터 운영자	어떤 포트·프로토콜로 받고 TLS 는 어떻게 하는가
HTTPRoute	앱 개발자	호스트·경로·헤더를 어느 Service 로 보낼까

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web
spec:
  parentRefs:
    - name: main-gateway      # 붙을 Gateway
  hostnames: [example.com]
  rules:
    - matches:
        - path: { type: PathPrefix, value: / }
      backendRefs:
        - name: web
          port: 80

앱 팀은 HTTPRoute 만 고치면 되고, 진입점과 인증서는 Gateway 에서 한 번 정한다. 헤더 매칭과 가중치 분산도 표준 필드로 있어서 어노테이션에 기대지 않는다. 이관 과정은 DoEatFit k3s 운영기 1 - 단일 서버에서 k3s로에서 Nginx Proxy Manager 를 Envoy Gateway 로 옮긴 부분에 나온다.

2-4. TLS 종료

TLS 종료는 프록시가 HTTPS 를 풀고 안쪽은 평문 HTTP 로 Service 에 넘기는 것이다. Gateway 의 리스너에 인증서가 든 Secret 을 지정하면 그 지점에서 종료된다. 앱은 인증서를 몰라도 되고, 갱신도 한곳에서 한다. 안쪽 구간 암호화가 필요하면 그때 따로 구성한다.

2-5. 어디서 실수하나

• 컨트롤러 없이 Ingress 만 만든다. 리소스는 생기지만 아무 일도 안 일어난다.
• HTTPRoute 가 Gateway 에 붙었는지(parentRefs, 허용 네임스페이스) 상태를 안 본다. 리소스 status 에 Accepted 여부가 나온다.
• 백엔드 Service 에 readiness 를 통과한 Pod 가 없어서 502/503 이 나는데 프록시를 의심한다. 4편의 EndpointSlice 부터 본다.

---

3. 마무리

요약

• 외부 HTTP 요청은 프록시 Pod 가 받고, 쿠버네티스 리소스는 그 프록시의 라우팅 규칙을 선언한다.
• Ingress 는 표준 표현력이 좁아 어노테이션에 의존하고, 관심사가 한 리소스에 섞인다.
• Gateway API 는 GatewayClass, Gateway, HTTPRoute 로 인프라 제공자, 운영자, 앱 개발자의 역할을 나눈다.
• TLS 는 Gateway 에서 종료하고, 앱은 평문 HTTP 만 받는다.

다음은 Kubernetes 기초 6 - ConfigMap, Secret, 볼륨이다.

---