인그레스 게이트웨이 커스터마이징하기
GatewayAPI 리소스로 Calico 인그레스 게이트웨이의 핵심 구성 요소를 지정하는 방법을 다뤄요. 게이트웨이 컨트롤러가 어디에 스케줄링될지 정하는 node selector부터 여러 GatewayClass 운영, 파드 메타데이터, 로드 밸런서 서비스 옵션까지 살펴봐요. 더 세밀한 제어가 필요하면 Envoy Gateway 자체 구성 파일을 직접 제공하는 방법도 함께 소개해요.
출처: 문서
본문
인그레스 게이트웨이의 핵심 구성 요소는 GatewayAPI 리소스에 구성을 지정해서 정할 수 있어요. 또는 Envoy Gateway가 제공하는 커스터마이징 옵션 전체를 쓰고 싶다면 직접 만든 Envoy Gateway 구성을 제공할 수도 있어요.
GatewayAPI 리소스로 인그레스 게이트웨이 커스터마이징하기
GatewayAPI 리소스에는 다양한 커스터마이징 옵션이 있어요. 이 리소스의 필드를 사용하면 Gateway 배포의 여러 측면을 바꿀 수 있어요. 예를 들면 다음과 같아요.
-
spec.gatewayControllerDeployment.spec.template.spec.nodeSelector는 게이트웨이 컨트롤러가 어디에 스케줄링될지 제어할 수 있어요. -
spec.gatewayClasses는 Tigera Operator가 기본으로 프로비저닝하는 단일tigera-gateway-class게이트웨이 클래스 대신, 각자 고유한 커스터마이징을 갖는 여러GatewayClass리소스를 프로비저닝할 수 있게 해 줘요. 가능한GatewayClass커스터마이징은 다음과 같아요.gatewayDeployment.spec.template.metadata는 해당 클래스 안의 각 Gateway를 구현하기 위해 생성되는 파드에 임의의 레이블이나 어노테이션을 추가할 수 있게 해 줘요.gatewayDeployment.spec.template.spec.nodeSelector는 게이트웨이 구현 파드가 어디에 스케줄링될지 제어할 수 있게 해 줘요.gatewayDeployment.spec.template.spec.containers는 게이트웨이 구현 파드가 사용할 수 있는 메모리와 CPU를 제어할 수 있게 해 줘요.gatewayService.metadata.annotations는 각 Gateway용으로 프로비저닝되는 서비스에 붙일 어노테이션을 제어할 수 있게 해 줘요. 예를 들어 이를 사용해 연관된 외부 로드 밸런서의 클라우드별 타입과 속성을 구성할 수 있어요.gatewayService.spec.*loadBalancer*는 각 게이트웨이용으로 프로비저닝되는 서비스의 대응되는*loadBalancer*필드를 제어할 수 있게 해 줘요. 일부 클라우드에서는 이를 통해 연관된 외부 로드 밸런서의 타입과 속성을 구성할 수도 있어요.
자세한 내용은 GatewayAPI 참조 문서를 참고하세요.
참고: 머지드 게이트웨이(merged gateways)는 지원하지 않아요. 커스텀
EnvoyProxy가mergeGateways: true로 설정되어 있어도 operator는 이 설정을 무시하고false를 사용해요. 그래서 각Gateway는 자체 프록시와 로드 밸런서를 갖게 돼요.
이 커스터마이징 필드를 사용하려면 kubectl edit gatewayapi default로 GatewayAPI 리소스의 YAML을 편집하고, 필요한 커스터마이징 필드를 추가하거나 수정해요.
커스터마이징 예시
이 섹션에서는 자주 쓰는 커스터마이징 예시를 소개해요.
게이트웨이 파드를 여러 개 두고 파드별 메모리를 넉넉히 잡아 높은 트래픽 처리하기
kubectl apply -f - <<EOF
apiVersion: operator.tigera.io/v1
kind: GatewayAPI
metadata:
name: default
spec:
gatewayClasses:
- name: high-traffic-class
gatewayDeployment:
spec:
replicas: 3
template:
spec:
containers:
- name: envoy
resources:
requests:
memory: "5GiB"
EOF
클라우드별 기능으로 외부 로드 밸런서 구성하기
kubectl apply -f - <<EOF
apiVersion: operator.tigera.io/v1
kind: GatewayAPI
metadata:
name: default
spec:
gatewayClasses:
- name: class-with-aws-load-balancer
gatewayService:
metadata:
annotations:
service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
EOF
여러 게이트웨이 클래스 구성하기
예를 들어 앞의 두 커스텀 클래스를 동시에 프로비저닝하려면 다음과 같이 해요.
kubectl apply -f - <<EOF
apiVersion: operator.tigera.io/v1
kind: GatewayAPI
metadata:
name: default
spec:
gatewayClasses:
- name: high-traffic-class
gatewayDeployment:
spec:
replicas: 3
template:
spec:
containers:
- name: envoy
resources:
requests:
memory: "5GiB"
- name: class-with-aws-load-balancer
gatewayService:
metadata:
annotations:
service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
EOF
커스텀 Envoy 구성으로 인그레스 게이트웨이 커스터마이징하기
인그레스 게이트웨이 배포를 더 세밀하게 제어하려면 Envoy Gateway 1.9.1이 지원하는 어떤 구성이든 사용해 커스텀 Envoy 구성 파일을 만들 수 있어요. 이런 변경은 Tigera Operator가 검증해 주지 않으므로, Envoy Gateway 사용에 대한 높은 숙련도가 필요해요.
인그레스 게이트웨이의 Envoy 구성 커스터마이징하기
커스텀 Envoy 구성을 사용하려면 기본 Envoy 구성의 사본을 수정해서 적용하면 돼요.
-
기본 Envoy 구성 파일의 사본을 저장해요.
kubectl get configmap envoy-gateway-config -n calico-system -o yaml > <custom-envoy-configuration>.yaml<custom-envoy-configuration>은 여러분의 커스텀 구성 이름으로 바꿔요.기본 Envoy 구성 예시
apiVersion: v1 data: envoy-gateway.yaml: | apiVersion: gateway.envoyproxy.io/v1alpha1 extensionApis: enableBackend: true enableEnvoyPatchPolicy: true gateway: controllerName: gateway.envoyproxy.io/gatewayclass-controller kind: EnvoyGateway logging: level: default: info provider: kubernetes: rateLimitDeployment: container: image: quay.io/calico/envoy-ratelimit:v3.31.1 patch: type: StrategicMerge value: spec: template: spec: containers: - imagePullPolicy: IfNotPresent name: envoy-ratelimit pod: {} shutdownManager: image: quay.io/calico/envoy-gateway:v3.31.1 type: Kubernetes kind: ConfigMap metadata: creationTimestamp: "2025-11-18T12:34:04Z" labels: app.kubernetes.io/instance: tigera-gateway-api app.kubernetes.io/managed-by: Helm app.kubernetes.io/name: gateway-helm app.kubernetes.io/version: v1.5.0 helm.sh/chart: gateway-helm-v1.5.0 name: envoy-gateway-config namespace: calico-system ownerReferences: - apiVersion: operator.tigera.io/v1 blockOwnerDeletion: true controller: true kind: GatewayAPI name: default uid: ace36d13-3afc-4c52-b894-dc2b322bc36e resourceVersion: "1978" uid: 8135e15d-cc91-4e02-ab97-2910cff56008 -
클러스터가 생성한 다음 메타데이터 필드는 제거해요.
creationTimestampownerReferencesresourceVersionuid
-
metadata.name을 기본값인envoy-gateway-config에서 다른 이름으로 바꿔요. -
data.envoy-gateway.yaml섹션에 커스터마이징을 추가해요.Jaeger 연동이 추가된 커스텀 Envoy 구성 파일 예시
apiVersion: v1 data: envoy-gateway.yaml: | apiVersion: gateway.envoyproxy.io/v1alpha1 extensionApis: enableBackend: true enableEnvoyPatchPolicy: true gateway: controllerName: gateway.envoyproxy.io/gatewayclass-controller kind: EnvoyGateway logging: level: default: info provider: kubernetes: rateLimitDeployment: container: image: quay.io/calico/envoy-ratelimit:v3.31.1 patch: type: StrategicMerge value: spec: template: spec: containers: - imagePullPolicy: IfNotPresent name: envoy-ratelimit pod: {} shutdownManager: image: quay.io/calico/envoy-gateway:v3.31.1 type: Kubernetes tracing: enabled: true provider: type: Jaeger jaeger: host: jaeger-collector.observability.svc.cluster.local port: 14268 kind: ConfigMap metadata: labels: app.kubernetes.io/instance: tigera-gateway-api app.kubernetes.io/managed-by: Helm app.kubernetes.io/name: gateway-helm app.kubernetes.io/version: v1.5.0 helm.sh/chart: gateway-helm-v1.5.0 name: custom-envoy-config namespace: calico-system -
커스터마이징한 Envoy 구성을 적용해요.
kubectl apply -f custom-envoy-config.yaml -
커스텀 Envoy 구성의 경로가 포함되도록
GatewayAPI리소스를 패치해요.kubectl patch gatewayapi default --type='json' -p='[{"op": "replace", "path": "/spec/envoyGatewayConfigRef", "value": {"name": "custom-envoy-config", "namespace": "calico-system"}}]'
추가 리소스
- Tigera Operator API 참조의
GatewayAPI스펙 - Envoy Gateway 문서
더 알아보기 (Learn more)
GatewayAPI 리소스 필드만으로 대부분의 게이트웨이 커스터마이징을 해결할 수 있어요. Envoy 구성을 직접 고칠 때는 operator가 검증해 주지 않는다는 점을 항상 기억하고, 변경 전에 기본 구성 사본을 꼭 백업해 두세요.