Envoy Gateway v1.7.2 / Proxy v1.37.2 오프라인 설치 가이드

폐쇄망 환경에서 Envoy Gateway를 Kubernetes(K8s) 위에 설치하는 절차를 안내합니다.

0. 오프라인 설치 자산 준비 (인터넷 환경)

폐쇄망에 반입할 Helm 차트와 컨테이너 이미지(.tar)가 charts/ 및 images/ 디렉토리에 없는 경우, 인터넷이 연결된 외부 PC(리눅스)에서 아래 스크립트를 실행하여 자산을 다운로드해야 합니다.

주의: 이 작업은 폐쇄망 내부가 아닌, 외부망에서 사전에 수행되어야 합니다. (Docker 또는 containerd(ctr), helm CLI 설치 필수)

# 컴포넌트 스크립트 디렉토리로 이동
cd scripts/

# 실행 권한 부여 및 다운로드 스크립트 실행
chmod +x ./scripts/download_assets_offline.sh
sudo ./scripts/download_assets_offline.sh

스크립트 실행이 완료되면 charts/ 디렉토리에 .tgz 차트 파일이, images/ 디렉토리에 .tar 이미지 파일들이 생성됩니다. 전체 프로젝트 폴더를 압축하여 폐쇄망 내부로 반입하십시오.

전제 조건

• Kubernetes 클러스터 구성 완료
• Helm v3.14.0 이상 설치 완료
• kubectl CLI 사용 가능
• Harbor 레지스트리 또는 로컬 이미지 로드 환경 (Containerd ctr 등)

아키텍처 개요

• Network: hostNetwork: false (Pod 격리 보호)
• 트래픽 진입점: LoadBalancer 또는 NodePort 서비스
• 구성 요소:
• Control Plane: Envoy Gateway v1.7.2
• Data Plane: Envoy Proxy v1.37.2 (Distroless)

배포 모드 비교 및 선택

항목	LoadBalancer + DaemonSet (권장)	NodePort + DaemonSet
권장 환경	클라우드 또는 MetalLB 환경	하드웨어 L4 / HAProxy 연동 환경
실IP 보존	가능 (externalTrafficPolicy: Local)	가능 (Proxy Protocol 필요 시 설정)
고가용성(HA)	모든 워커 노드에서 트래픽 수신	모든 워커 노드에서 트래픽 수신
운영 편의성	높음 (자동 IP 관리)	보통 (Port 관리 및 LB 연동 필요)

---

1단계: 이미지 확보 및 로드

Case A: 로컬 환경에 직접 로드 (Harbor 미사용 시)

인터넷이 되는 환경에서 이미지를 Pull 한 뒤 tar로 확보하여 워커 노드로 옮깁니다.

# 이미지 Pull 및 Export (인터넷 가능 환경)
ctr images pull docker.io/envoyproxy/gateway:v1.7.2
ctr images pull docker.io/envoyproxy/envoy:distroless-v1.37.2
ctr images export envoy-gateway.tar docker.io/envoyproxy/gateway:v1.7.2
ctr images export envoy-proxy.tar docker.io/envoyproxy/envoy:distroless-v1.37.2

# 폐쇄망 워커 노드에서 Import (Kubernetes 네임스페이스 지정)
sudo ctr -n k8s.io images import envoy-gateway.tar
sudo ctr -n k8s.io images import envoy-proxy.tar

(참고: K3s를 사용하는 경우 sudo k3s ctr -n k8s.io images import ... 명령어를 사용하십시오.)

Case B: Harbor 레지스트리 업로드

chmod +x images/upload_images_to_harbor_v3-lite.sh
./images/upload_images_to_harbor_v3-lite.sh

---

2단계: 설치 및 업그레이드

설치는 자동화 스크립트를 사용하거나, 수동으로 Helm 명령어를 직접 실행하여 진행할 수 있습니다.

방법 1. 자동화 스크립트 사용 (권장)

chmod +x scripts/install.sh
./scripts/install.sh

스크립트 동작 모드 설명:

1. 업그레이드: install.conf에 저장된 이전 설정을 유지하며 Helm Upgrade를 수행합니다. 기존 HTTPRoute 등 설정이 보존됩니다.
2. 재설치: 기존 Helm 리소스를 삭제한 후 새로 입력받은 설정으로 설치합니다.
3. 초기화: 모든 리소스와 install.conf를 삭제합니다.

방법 2. 수동 설치 및 업그레이드 (스크립트 사용 불가 시)

스크립트 환경에 문제가 있거나 세밀한 제어가 필요할 경우 아래 순서대로 직접 실행합니다.

1) CRD 수동 적용 (설치/업그레이드 공통)

Envoy Gateway는 Helm 배포 전에 CRD를 먼저 적용해야 합니다.

# 디렉토리 이동
cd envoy-1.37.2/

# CRD 적용 (어노테이션 크기 문제 방지를 위해 replace --force 권장)
kubectl replace --force -f charts/gateway-1.7.2/crds/gatewayapi-crds.yaml
kubectl replace --force -f charts/gateway-1.7.2/crds/generated/

2) 컨트롤 플레인 설치/업그레이드

values.yaml 파일을 환경(이미지 경로 등)에 맞게 수정한 뒤 실행합니다.

helm upgrade --install eg-gateway ./charts/gateway-1.7.2 \
  -n envoy-gateway-system --create-namespace \
  -f ./values.yaml

3) 데이터 플레인 (인프라) 설치/업그레이드

values-infra.yaml 파일을 환경에 맞게 수정한 뒤 실행합니다.

helm upgrade --install gateway-infra ./charts/gateway-infra \
  -n envoy-gateway-system \
  -f ./values-infra.yaml

4) 전역 정책 적용 (선택)

kubectl apply -f manifests/policy-global-config.yaml

---

3단계: 배포 후 네트워크 구성

1. LoadBalancer — MetalLB 연동 (권장: 온프레미스 VIP 구성)

온프레미스(Bare-metal) 환경에서는 외부 트래픽을 수신하고 장애 전환(ARP Failover) 및 실 IP 보존을 보장하기 위해 MetalLB(L2 모드)를 구축하여 로드밸런서 IP를 광고하는 것을 강력히 권장합니다.

1) MetalLB 설치 및 IP 풀 설정

• 본 레포의 metallb-0.16.1 컴포넌트를 참고하여 설치하고, 노드 대역의 유휴 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}"}
  ]}}'

2. NodePort — 포트 확인 및 HAProxy 연동

values-infra.yaml에서 NodePort로 설정한 경우 할당된 포트(기본 30080, 30443)를 확인합니다.

kubectl get svc -n envoy-gateway-system
# 출력 예: 80:30080/TCP, 443:30443/TCP

해당 포트를 앞단의 HAProxy 또는 L4 스위치의 Real Server 포트로 지정합니다.

3. TLS 인증서 및 HTTPS 구성

Envoy Gateway에서 HTTPS(TLS) 서비스를 노출하려면 사전에 인증서 Secret을 생성해 두어야 합니다.

TLS Secret 생성 (설치 전 또는 완료 후):

gateway-infra 설정(values-infra.yaml)에 정의된 Secret 이름(기본값: gateway-tls)과 매칭되도록 생성합니다.

# 인증서 파일(cert.pem, key.pem)이 위치한 디렉토리에서 실행
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

---

4단계: 서비스 노출 (HTTPRoute)

신규 서비스를 Envoy를 통해 노출하려면 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

---

삭제 및 초기화

자동화 스크립트를 사용하거나 수동으로 리소스를 제거합니다.

# 스크립트 사용
./scripts/uninstall.sh

# 수동 삭제
helm uninstall gateway-infra -n envoy-gateway-system
helm uninstall eg-gateway -n envoy-gateway-system
kubectl delete ns envoy-gateway-system