Envoy Gateway v1.7.2 / Proxy v1.37.2 온라인 설치 가이드
인터넷이 가능한 환경에서 Envoy Gateway 를 Kubernetes 클러스터에 설치하는 절차입니다. 폐쇄망 절차는 Envoy Gateway v1.37.2 오프라인 설치 가이드를 참고하세요.
전제 조건
- Kubernetes 클러스터 구성 완료 (v1.30+ 권장)
- Helm v3.14.0 이상 설치 완료
kubectlCLI 사용 가능- 외부 저장소 접근 가능 (
docker.io,gateway.envoyproxy.ioHelm 저장소) - Cilium 사용 시
gatewayAPI.enabled=false로 설치되어 있어야 함 (GatewayClass 충돌 방지)
아키텍처 개요
- Network:
hostNetwork: false - 트래픽 진입점:
LoadBalancer(MetalLB / 클라우드 LB) 또는NodePort - 구성 요소:
- Control Plane: Envoy Gateway v1.7.2 (
envoy-gateway-system네임스페이스) - Data Plane: Envoy Proxy v1.37.2 (Distroless)
| 모드 | 권장 환경 | 비고 |
|---|---|---|
| LoadBalancer + DaemonSet | 클라우드 / MetalLB | externalTrafficPolicy: Local 로 실 IP 보존 |
| NodePort + DaemonSet | L4 스위치 / HAProxy 연동 | 30080 / 30443 고정 |
1단계: Gateway API CRD 설치
Envoy Gateway 는 Gateway API CRD 가 클러스터에 존재해야 동작합니다. (Cilium 등 다른 구현체가 이미 설치한 상태라면 이 단계 생략 가능)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml
# 확인
kubectl get crd | grep gateway.networking.k8s.io
2단계: Envoy Gateway Helm 차트 등록
Envoy Gateway 는 OCI 레지스트리(docker.io/envoyproxy/gateway-helm)에서 제공됩니다.
# Helm 차트 풀 (선택 — values 검토용)
helm pull oci://docker.io/envoyproxy/gateway-helm \
--version v1.7.2 \
--untar --untardir /tmp/eg
ls /tmp/eg/gateway-helm/ # values.yaml 등 확인
본 레포의
charts/gateway-1.7.2와 동일 버전입니다. 값 커스터마이징이 필요하면 위 풀받은 디렉터리의values.yaml을 복사해서 수정하세요.
3단계: 컨트롤 플레인 설치 (Envoy Gateway)
# 네임스페이스 생성
kubectl create ns envoy-gateway-system --dry-run=client -o yaml | kubectl apply -f -
# OCI 차트 직접 설치 (기본값으로)
helm upgrade --install eg-gateway oci://docker.io/envoyproxy/gateway-helm \
--version v1.7.2 \
-n envoy-gateway-system
# 또는 본 레포의 values.yaml 활용
helm upgrade --install eg-gateway oci://docker.io/envoyproxy/gateway-helm \
--version v1.7.2 \
-n envoy-gateway-system \
-f ./values.yaml
설치 확인:
kubectl -n envoy-gateway-system get pods
kubectl -n envoy-gateway-system get gatewayclass
# eg (Accepted=True) 출력 확인
4단계: 데이터 플레인 (Gateway 인스턴스) 배포
본 레포는 charts/gateway-infra 라는 별도 차트로 Gateway 리소스 + 라우팅 + 정책을 묶어 배포합니다.
helm upgrade --install gateway-infra ./charts/gateway-infra \
-n envoy-gateway-system \
-f ./values-infra.yaml
# 전역 정책 (선택)
kubectl apply -f manifests/policy-global-config.yaml
Envoy Gateway 만 띄우고 본인이 직접
Gateway/HTTPRoute를 작성할 거면 이 단계는 건너뛰고 5단계로 바로 가도 됩니다.
5단계: 배포 후 네트워크 구성
LoadBalancer — 자동 할당 (MetalLB / 클라우드)
LoadBalancer — MetalLB 연동 (권장: 온프레미스 VIP 구성)
온프레미스(Bare-metal) 환경에서는 외부 트래픽을 수신하고 장애 전환(ARP Failover) 및 실 IP 보존을 보장하기 위해 MetalLB(L2 모드)를 구축하여 로드밸런서 IP를 광고하는 것을 강력히 권장합니다.
1) MetalLB 설치 및 IP 풀 설정
- 본 레포의 MetalLB 설치 가이드를 참고하여 설치하고, 노드 대역의 유휴 IP(예:
10.10.10.81-10.10.10.81)를IPAddressPool로 등록합니다. values-infra.yaml의 서비스 타입이LoadBalancer상태로 배포되면, MetalLB가 생성된 Envoy Proxy 서비스에 IP풀의 VIP(10.10.10.81)를EXTERNAL-IP로 자동 할당하게 됩니다.
2) 게이트웨이(Gateway) 리소스 주소 바인딩
서비스에 IP가 할당된 후 Gateway 리소스의 주소를 바인딩하여 상태를 동기화(Programmed: True)합니다.
# 할당된 VIP(예: 10.10.10.81)를 Gateway 리소스에 바인딩
kubectl patch gateway cluster-gateway -n envoy-gateway-system --type='merge' \
-p '{"spec":{"addresses":[{"type":"IPAddress","value":"10.10.10.81"}]}}'
⚠️ [참고] externalIPs 수동 할당 (비권장 - 임시 검증용)
MetalLB 같은 로드밸런서 컨트롤러가 없는 경우에 임시로 노드 IP를 통해 외부 트래픽을 받기 위한 우회 방법입니다. (ARP 광고 및 고가용성이 보장되지 않으며, 실 IP 보존이 불가능합니다.)
서비스(Service) 외부 IP 등록:
# 서비스 이름 확인
SVC_NAME=$(kubectl get svc -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-name=cluster-gateway -o jsonpath='{.items[0].metadata.name}')
# 전체 워커 노드 IP를 externalIPs에 일괄 등록
kubectl patch svc -n envoy-gateway-system $SVC_NAME --type merge \
-p '{"spec":{"externalIPs":["<WORKER1_IP>","<WORKER2_IP>"]}}'
게이트웨이(Gateway) 주소 바인딩:
# 위에서 등록한 노드 IP들을 Gateway 리소스에도 바인딩
kubectl patch gateway cluster-gateway -n envoy-gateway-system --type='merge' \
-p '{"spec":{"addresses":[
{"type":"IPAddress","value":"<WORKER1_IP>"},
{"type":"IPAddress","value":"<WORKER2_IP>"}
]}}'
NodePort
L4 스위치 또는 HAProxy 의 Real Server 로 워커 IP:30080 / :30443 등록.
TLS 인증서 및 HTTPS 구성
Envoy Gateway에서 HTTPS(TLS) 서비스를 노출하려면 사전에 인증서 Secret을 생성해 두어야 합니다.
TLS Secret 생성 (설치 전 또는 완료 후):
gateway-infra 설정(values-infra.yaml)에 정의된 Secret 이름(기본값: gateway-tls)과 매칭되도록 생성합니다.
# 인증서 파일이 위치한 디렉토리에서 실행
kubectl create secret tls gateway-tls \
--cert=cert.pem --key=key.pem \
-n envoy-gateway-system
[!NOTE] 만약 다른 이름(예:
wildcard-tls-secret)으로 Secret을 생성할 경우,values-infra.yaml의gateway.tls.name항목을 해당 Secret 이름으로 수정한 뒤 설치 스크립트(install.sh)를 실행해야 합니다.
자동 바인딩 원리:
values-infra.yaml에서 gateway.tls.enabled: true 상태이면 gateway-infra 템플릿이 Gateway 리소스에 HTTPS 443 리스너와 Secret 참조 관계를 자동으로 구성합니다.
spec:
listeners:
- name: https
port: 443
protocol: HTTPS
tls:
mode: Terminate
certificateRefs:
- name: gateway-tls # values-infra.yaml의 gateway.tls.name 값을 동적으로 반영
kind: Secret
6단계: 서비스 노출 (HTTPRoute)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-service
namespace: default
spec:
parentRefs:
- name: cluster-gateway
namespace: envoy-gateway-system
hostnames:
- "app.devops.internal"
rules:
- matches:
- path: { type: PathPrefix, value: / }
backendRefs:
- name: app-svc
port: 80
검증:
kubectl get httproute -A
kubectl describe httproute example-service
# Conditions.Accepted=True / ResolvedRefs=True 확인
7단계: 운영 — 로그 확인
# Data Plane (Envoy Proxy) 로그
kubectl logs -n envoy-gateway-system -f \
-l gateway.envoyproxy.io/owning-gateway-name=cluster-gateway
# Control Plane (Envoy Gateway) 로그
kubectl logs -n envoy-gateway-system -f \
-l app.kubernetes.io/name=envoy-gateway
CVE 패치 / Minor 업그레이드
Envoy Gateway 차트 업그레이드만으로 patch 가 적용됩니다 (rolling).
# 차트 버전 확인
helm search repo oci://docker.io/envoyproxy/gateway-helm --versions | head -10
# 동일 라인 patch 업그레이드
helm upgrade eg-gateway oci://docker.io/envoyproxy/gateway-helm \
--version v1.7.2 -n envoy-gateway-system \
--reuse-values
Major / minor 업그레이드(예: 1.6 → 1.7)는 CRD 변경이 동반되므로 Envoy Gateway Release Notes 를 먼저 확인하세요.