NGINX Ingress 대신 Gateway API: kind 클러스터 앱을 Windows localhost로 접속하기
Envoy Gateway를 설치하고, 로드밸런서 없는 kind에서 Windows 브라우저까지 연결한 과정
로컬 쿠버네티스 실습 시리즈 목차 · 글 15개
- 1편Windows에서 무료 쿠버네티스 실습 환경 만들기: WSL2 + Docker Engine + kind
- 2편Headlamp 설치와 사용법: 로컬 쿠버네티스를 화면으로 보고 파드 배포하기
- 3편NGINX Ingress 대신 Gateway API: kind 클러스터 앱을 Windows localhost로 접속하기
- 4편kube-prometheus-stack 설치와 Grafana 접속: kind 클러스터 모니터링과 target down 해결
- 5편Fluent Bit과 Loki로 쿠버네티스 로그 모으기: kind 실습과 Grafana 조회, AWS 확장 예시
- 6편cert-manager로 Gateway API HTTPS 붙이기: 사설 CA, 자동 갱신, 만료 알림까지 kind 실습
- 7편Keycloak 운영 모드로 Grafana SSO 만들기: Keycloak Operator, CloudNativePG, 이중화와 장애·백업 훈련
- 8편OpenTelemetry로 쿠버네티스 트레이스 모으기: Collector, Tempo, 샘플링과 장애 훈련까지 kind 실습
- 9편Argo CD로 쿠버네티스 GitOps 전환하기: Helm 설치 넘겨받기, Sealed Secrets, Keycloak SSO와 장애 훈련까지 kind 실습
- 부록Argo CD로 nginx 파드 하나 배포하기: GitHub에서 파일 두 개 커밋하고 replicas 바꿔 보기
- 10편Trivy Operator로 쿠버네티스 취약점 점검하기: 이미지·설정·비밀값 스캔, Grafana 경보, Argo CD로 고치기까지 kind 실습
- 번외편Trivy로 찾은 컨테이너 이미지 취약점 고치기: nginx apk upgrade, Go 의존성 올리기, Grafana처럼 직접 못 고치는 경우까지
- 11편Istio Ambient 모드로 서비스 메시 붙이기: 사이드카 없이 mTLS, 권한 정책, waypoint 트래픽 분할과 장애 훈련까지 kind 실습
- 12편Strimzi로 쿠버네티스에 Kafka 올리기: KRaft 브로커 3대, SCRAM·ACL, 소비 지연 경보와 장애·업그레이드 훈련까지 kind 실습
- 13편Airflow를 쿠버네티스에 올리기: KubernetesExecutor, git-sync DAG 배포, 재시도·catchup부터 스케줄러 장애와 3.4 업그레이드까지 kind 실습
kind 클러스터에서 Gateway API를 쓰려면 Gateway API 리소스 정의와 구현체가 필요한데, Envoy Gateway helm 차트 하나로 둘 다 설치됩니다. 남는 문제는 kind에 로드밸런서가 없다는 점입니다. 이 글에서는 Envoy 프록시를 8080 포트가 연결된 제어 플레인 노드에 띄우고 노드의 80번 포트를 직접 받게(hostPort) 설정해서, Windows 브라우저의 localhost:8080이 Gateway → HTTPRoute → web 파드로 이어지게 만들었습니다. 적용 후 약 20초 만에 Gateway가 준비됐고, 요청 6번이 파드 2개에 3건씩 나뉘어 들어가는 것까지 확인했습니다.
1편에서 만든 kind 클러스터(노드 3개, Windows 8080 → 제어 플레인 80 포트 연결)와 2편에서 만든 web Deployment(nginx 파드 2개)를 그대로 씁니다. Envoy Gateway v1.10.0, Kubernetes v1.37.0 기준이며 HTTPS와 여러 도메인 라우팅은 다루지 않습니다.
왜 Ingress가 아니라 Gateway API인가
쿠버네티스에서 외부 요청을 서비스로 보내는 방법은 오랫동안 Ingress였고, 그 구현체로 NGINX Ingress Controller가 가장 많이 쓰였습니다. GitHub에서 확인하면 kubernetes/ingress-nginx 저장소는 2026년 3월 이후 새 커밋이 없습니다. 새로 실습 환경을 만든다면 Ingress의 후속 표준인 Gateway API로 시작하는 편이 낫습니다. Gateway API 공식 문서
Gateway API는 역할을 리소스 세 단계로 나눕니다. 이 구분을 알면 아래 매니페스트가 왜 여러 개인지 이해하기 쉽습니다.
Gateway API의 주요 리소스
| 리소스 | 정하는 것 | 이 글에서 만든 것 |
|---|---|---|
| GatewayClass | 어떤 구현체(컨트롤러)를 쓸지 | eg (Envoy Gateway) |
| Gateway | 어느 포트·프로토콜로 요청을 받을지 | lab-gateway (HTTP 80) |
| HTTPRoute | 받은 요청을 어느 서비스로 보낼지 | web (/ → web 서비스 80) |
Envoy Gateway 설치: CRD까지 helm 한 번에
kind는 Gateway API 리소스를 기본으로 넣지 않습니다. 설치 전에 kubectl api-resources --api-group=gateway.networking.k8s.io를 실행하면 아무것도 나오지 않습니다. Envoy Gateway의 helm 차트가 리소스 정의(CRD)와 컨트롤러를 함께 설치합니다. Envoy Gateway 빠른 시작
helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.10.0 -n envoy-gateway-system --create-namespacekubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available컨트롤러가 준비되기까지 18초가 걸렸습니다. 설치 중에 인증서를 만드는 eg-gateway-helm-certgen 잡이 한 번 실행되고 Completed로 끝납니다. 설치된 리소스 종류는 GatewayClass, Gateway, HTTPRoute, GRPCRoute, TLSRoute 등 10가지였습니다.
확인해 볼 점: 함께 깔리는 Gateway API 버전
같은 날 Gateway API 최신 릴리스는 v1.7.0이었지만, Envoy Gateway v1.10.0 차트가 설치한 CRD에는 v1.6.1 experimental 채널이 적혀 있었습니다. 구현체가 지원하는 버전이 따로 있으므로, Gateway API CRD를 직접 최신으로 올리기 전에 구현체의 지원 버전을 먼저 확인합니다. 확인 명령: kubectl get crd gateways.gateway.networking.k8s.io -o jsonpath=‘{.metadata.annotations}’
로드밸런서 없는 kind에서 Windows까지 잇는 방법
Envoy Gateway는 Gateway를 만들면 Envoy 프록시 파드와 LoadBalancer 서비스를 만듭니다. 클라우드라면 이 서비스에 외부 주소가 붙지만 kind에는 로드밸런서가 없습니다. 선택지는 세 가지입니다.
kind에서 Gateway에 접속하는 방법
| 방법 | 장점 | 단점 |
|---|---|---|
| kubectl port-forward | 설정 없이 바로 확인 가능(공식 빠른 시작의 방법) | 명령을 켜 둔 동안만 접속, 매번 다시 실행 |
| MetalLB 같은 로드밸런서 구현 | 클라우드와 비슷하게 주소가 붙음 | 붙는 주소가 WSL 안 Docker 네트워크 대역이라 Windows 브라우저에서 바로 쓰려면 추가 설정이 필요할 수 있음 |
| 노드 포트 직접 받기(hostPort) | 1편의 8080 연결을 그대로 사용, 항상 접속 가능 | Envoy 파드를 특정 노드에 고정해야 함 |
이 글은 세 번째 방법을 썼습니다. 1편에서 Windows 8080을 제어 플레인 노드 컨테이너의 80번 포트에 연결해 두었으므로, Envoy가 그 노드의 80번 포트를 직접 받으면 됩니다. Envoy 프록시의 모양은 EnvoyProxy라는 Envoy Gateway 전용 리소스로 바꿉니다. EnvoyProxy 설정 안내
apiVersion: gateway.envoyproxy.io/v1alpha1kind: EnvoyProxymetadata: name: kind-hostport namespace: envoy-gateway-systemspec: provider: type: Kubernetes kubernetes: envoyService: type: ClusterIP envoyDeployment: replicas: 1 pod: nodeSelector: ingress-ready: "true" tolerations: - key: node-role.kubernetes.io/control-plane operator: Exists effect: NoSchedule patch: type: StrategicMerge value: spec: template: spec: containers: - name: envoy ports: - containerPort: 10080 hostPort: 80 protocol: TCP설정마다 이유가 있습니다. envoyService.type: ClusterIP는 붙지 않을 외부 주소를 기다리지 않게 합니다. nodeSelector의 ingress-ready: "true"는 1편에서 제어 플레인에 붙여 둔 라벨이고, 제어 플레인에는 일반 파드가 올라가지 못하게 막는 테인트가 있어서 tolerations로 허용합니다. 마지막 patch가 핵심인데, 노드의 80번 포트를 Envoy 컨테이너의 10080번 포트로 연결합니다.
80이 아니라 10080인 이유는 Envoy Gateway가 1024보다 작은 특권 포트를 컨테이너 안에서 높은 번호로 바꿔 열기 때문입니다. Gateway 리스너를 80으로 만들면 Envoy는 실제로 10080에서 기다립니다. 처음에는 이 점을 모르면 hostPort를 80 → 80으로 잡기 쉽습니다.
GatewayClass·Gateway·HTTPRoute 만들기
GatewayClass는 위의 EnvoyProxy를 parametersRef로 가리켜서, 이 클래스로 만드는 모든 Gateway가 그 설정을 따르게 합니다. web Deployment에는 아직 서비스가 없으므로 서비스도 함께 만듭니다.
apiVersion: gateway.networking.k8s.io/v1kind: GatewayClassmetadata: name: egspec: controllerName: gateway.envoyproxy.io/gatewayclass-controller parametersRef: group: gateway.envoyproxy.io kind: EnvoyProxy name: kind-hostport namespace: envoy-gateway-system---apiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata: name: lab-gatewayspec: gatewayClassName: eg listeners: - name: http protocol: HTTP port: 80---apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata: name: webspec: parentRefs: - name: lab-gateway rules: - matches: - path: type: PathPrefix value: / backendRefs: - name: web port: 80HTTPRoute의 parentRefs가 어느 Gateway에 붙을지, backendRefs가 요청을 받을 서비스를 정합니다. 서비스(web, 포트 80 → 파드 80)까지 하나의 파일에 넣어 kubectl apply -f로 적용했고, 상태가 준비될 때까지 기다렸습니다.
$ kubectl wait --for=condition=Programmed gateway/lab-gateway --timeout=180sgateway.gateway.networking.k8s.io/lab-gateway condition met$ kubectl get gatewayclass,gatewayNAME CONTROLLER ACCEPTEDeg gateway.envoyproxy.io/gatewayclass-controller TrueNAME CLASS PROGRAMMEDlab-gateway eg True적용부터 Programmed까지 약 20초가 걸렸습니다. HTTPRoute 상태에도 Accepted=True와 ResolvedRefs=True가 나와야 합니다. ResolvedRefs가 False라면 backendRefs의 서비스 이름이나 포트가 틀린 경우가 많습니다. Envoy 프록시 파드는 의도대로 lab-control-plane 노드에 떴고, envoy 컨테이너의 10080 포트에 hostPort 80이 붙어 있었습니다.
Windows 브라우저로 접속하고 부하 분산 확인
이제 Windows에서 접속합니다. 요청 경로는 Windows localhost:8080 → kind 제어 플레인 노드 80 → Envoy 10080 → web 서비스 → nginx 파드입니다.
PS> curl.exe -s -o NUL -w "HTTP %{http_code}" http://localhost:8080/HTTP 200PS> curl.exe -s http://localhost:8080/ | Select-String "<title>"<title>Welcome to nginx!</title>Windows 브라우저에서 http://localhost:8080을 열어도 nginx 환영 페이지가 나왔습니다. 마지막으로 요청이 파드 2개로 나뉘는지 봤습니다. Windows에서 /?n=1부터 /?n=6까지 6번 요청한 뒤 각 파드의 nginx 접근 로그를 세면 됩니다.
for p in $(kubectl get pods -l app=web -o name); do echo "$p $(kubectl logs "$p" --since=5m | grep -c 'GET /?n=')건"done결과는 web-…-5gdxz 3건, web-…-k5682 3건이었습니다. Gateway가 서비스 뒤의 파드들로 요청을 나눠 보낸다는 것을 로그로 확인할 수 있습니다.
PowerShell에서 bash 명령을 넘길 때
위 반복문을 PowerShell에서 wsl — bash -c ”…”로 한 줄에 넘기면 $(…) 부분을 PowerShell이 먼저 해석해서 bash 문법 오류가 납니다. 실습 중 실제로 겪은 문제로, 스크립트 파일로 저장한 뒤 wsl — bash 파일로 실행하면 해결됩니다.
자주 묻는 질문
hostPort 대신 port-forward만 써도 되나요?
확인만 할 때는 됩니다. Envoy Gateway 빠른 시작도 로드밸런서가 없으면 kubectl port-forward로 Envoy 서비스에 접속하는 방법을 안내합니다. 다만 명령을 켜 둔 동안에만 접속되므로, 다음 편부터 여러 앱을 계속 띄워 둘 실습 환경에는 hostPort 방식이 편합니다.
Gateway의 ADDRESS에 나오는 주소로 접속하면 되나요?
이 구성에서는 Envoy 서비스를 ClusterIP로 바꿨기 때문에 ADDRESS에는 클러스터 안에서만 쓰는 주소가 나옵니다. Windows에서는 그 주소가 아니라 localhost:8080으로 접속합니다.
작성 방식과 다음 편
이 글의 명령과 출력은 1편의 실습 PC에서 직접 실행한 결과이며, 설치와 설정은 Gateway API와 Envoy Gateway 공식 문서를 기준으로 했습니다. 실행 기록 정리와 글 작성에 AI 도구를 함께 사용했습니다. 다음 편에서는 kube-prometheus-stack으로 Prometheus와 Grafana를 설치하고, Grafana도 이 Gateway를 통해 Windows 브라우저에서 엽니다.