Envoy Gateway 빠른 시작: 10분 안에 첫 요청 통과시키기

이 글의 목표는 단순합니다. 철학은 건너뛰고, Envoy Gateway를 그냥 띄워봅시다. 예제 서비스에 성공적으로 요청을 보냈다면, 아직도 문서 첫 화면에서 헤매는 사람들보다 이미 한발 앞선 겁니다.

사전 준비

최소 한 개 이상의 동작하는 Kubernetes 클러스터가 필요합니다. 예를 들면:

• 로컬: kind, minikube, k3d
• 클라우드: EKS, GKE, AKS
• 홈랩: K3s + MetalLB 조합도 가능

추가로 필요한 것:

• kubectl
• helm
• LoadBalancer 주소를 프로비저닝할 수 있는 클러스터, 혹은 port-forward 사용을 감수할 수 있는 환경

⚠️ 클러스터가 LoadBalancer를 지원하지 않는다면 공식 문서는 MetalLB와 함께 쓰는 것을 권장합니다. 외부 주소가 없다고 끝장은 아닙니다. 대신 port-forward로 테스트하면 됩니다.

1단계: Envoy Gateway 설치

컨트롤 플레인을 설치합니다:

helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.7.0 \
  -n envoy-gateway-system \
  --create-namespace

준비될 때까지 기다립니다:

kubectl wait --timeout=5m -n envoy-gateway-system \
  deployment/envoy-gateway \
  --for=condition=Available

이 명령이 끝나면 Envoy Gateway 컨트롤러가 클러스터에서 실행 중인 상태입니다. 이제 Gateway API 리소스를 읽고, 이에 대응하는 Envoy 설정을 생성할 수 있습니다.

2단계: 공식 Quickstart 리소스 적용

공식 저장소는 다음이 모두 포함된 번들 예제를 제공합니다:

• GatewayClass
• Gateway
• HTTPRoute
• 샘플 백엔드 앱

바로 적용해 봅시다:

kubectl apply -f \
  https://github.com/envoyproxy/gateway/releases/download/v1.7.0/quickstart.yaml \
  -n default

이걸 공식 팀이 여러분을 위해 완성된 데모 장면을 통째로 깔아준다고 생각하면 됩니다. 먼저 돌려보고, 세부 구조는 나중에 분해해도 됩니다.

3단계: 트래픽이 실제로 흐르는지 확인

옵션 A: 클러스터에 LoadBalancer가 있는 경우

Gateway 주소를 가져옵니다:

export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}')

요청을 보냅니다:

curl --verbose \
  --header "Host: www.example.com" \
  http://$GATEWAY_HOST/get

HTTP 200이 반환되면 다음을 의미합니다:

• Gateway가 정상 동작하는 ingress 역할을 하고 있음
• HTTPRoute가 성공적으로 attach 되었음
• 백엔드 서비스로 올바르게 라우팅되고 있음

옵션 B: LoadBalancer 없음, port-forward 사용

Envoy 서비스를 찾습니다:

export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system \
  --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg \
  -o jsonpath='{.items[0].metadata.name}')

로컬 포트 8888을 Gateway 포트 80으로 포워딩합니다:

kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8888:80

다른 터미널에서:

curl --verbose \
  --header "Host: www.example.com" \
  http://localhost:8888/get

이건 로컬 테스트 경로입니다. 약간 뒷문으로 들어가는 느낌은 있지만, 라우팅만 검증되면 괜찮습니다. 엔지니어링이란 원래 "먼저 되게 만들고, 그다음 우아하게 만든다"에 가깝기도 하니까요.

문제가 생기면 어디를 볼까

가장 흔한 문제는 Envoy Gateway 자체가 고장 난 것이 아니라, 체인의 한 구간이 연결되지 않은 경우입니다:

유용한 명령어:

kubectl get pods -n envoy-gateway-system
kubectl get gatewayclass
kubectl get gateway -A
kubectl get httproute -A
kubectl get svc,pod -n default

Gateway 상태를 더 깊게 보려면:

kubectl get gateway/eg -o yaml

핵심 체크 포인트:

• status.addresses
• Listener condition
• Route가 accepted 되었는지 여부

방금 실제로 한 일

몇 개의 명령만 실행했지만, 사실 end-to-end 체인 전체를 완료한 겁니다:

1. Envoy Gateway 설치
2. 클러스터가 어떤 gateway controller를 쓸지 알려주는 GatewayClass 생성
3. ingress 포트와 프로토콜을 선언하는 Gateway 생성
4. 트래픽을 백엔드 서비스로 보내는 HTTPRoute 생성
5. Envoy Gateway가 이 선언들을 Envoy Proxy가 실행 가능한 설정으로 변환

바로 이 점 때문에 Gateway API를 쓸 가치가 있습니다. 여러분은 Kubernetes 리소스를 작성하지, proxy 설정 파일 더미를 손으로 유지하지 않습니다.

다음 단계

이제 첫 요청이 흐르기 시작했으니, 다음 글에서는 각 리소스가 실제로 어떤 일을 하는지 살펴보며 사고 모델을 세웁니다: 👉 핵심 개념