인그레스 게이트웨이 만들기

원문 보기 위키 갱신 2026.10.11

Kubernetes Gateway API로 ingress 트래픽을 관리하는 인그레스 게이트웨이를 만드는 절차를 다뤄요. GatewayAPI 리소스로 기능을 켜고, tigera-gateway-class를 참조하는 Gateway 리소스를 만드는 흐름이에요. 기본 거부 정책 환경에서 필요한 허용 정책 예시까지 포함돼요.

출처: 문서

본문

Kubernetes Gateway API로 ingress 트래픽을 관리하는 인그레스 게이트웨이를 만들어요.

Calico Ingress Gateway로 인그레스 게이트웨이 만들기

Calico Ingress Gateway는 Gateway API의 오픈소스 구현체인 Envoy Gateway에 기반해요. Calico는 이 구현체를 배포하고 관리하는 간단하고 편리한 방법을 제공해요.

Calico Ingress Gateway로 인그레스 게이트웨이를 만드는 일은 몇 단계만 거치면 돼요. 다음을 하면 돼요.

GatewayAPI 리소스를 만들어 Calico Ingress Gateway를 활성화해요.
Tigera Operator가 만든 GatewayClass 리소스의 이름인 tigera-gateway-class를 참조하는 Gateway 리소스를 만들어요.
게이트웨이 라우팅 리소스를 만들 때 이 Gateway 리소스를 참조해요.

제한 사항

Calico Ingress Gateway는 Windows 노드에서 지원되지 않아요.

사전 준비 사항

Kubernetes Gateway API를 이해하고 있고, 자신의 시스템에 어떻게 구성할지 알고 있어야 해요.
클러스터에 Calico가 Tigera Operator로 설치되어 있어야 해요.
클러스터가 LoadBalancer 타입의 서비스를 지원하도록 준비되어 있어야 해요.

인그레스 게이트웨이 만들기

Gateway API 지원을 활성화하려면 default라는 이름의 GatewayAPI 리소스를 만들어요.
```
kubectl apply -f - <<EOF
apiVersion: operator.tigera.io/v1
kind: GatewayAPI
metadata:
  name: default
EOF
```
Tigera Operator가 강화된(hardened) Envoy Gateway 이미지를 가져와서 세팅해요. 이렇게 하면 게이트웨이를 만들 때 필요한 GatewayClass 리소스를 포함한 Gateway API 리소스 묶음이 생겨요.

확인하려면 GatewayClass 리소스가 준비되었는지 조회해 보세요.
```
kubectl get gatewayclass
```
기대 출력
```
NAME                   CONTROLLER                                      ACCEPTED   AGE
tigera-gateway-class   gateway.envoyproxy.io/gatewayclass-controller   True       4m
```
SUCCESS: tigera-gateway-class는 Gateway API 지원을 활성화할 때 만들어지는 단일 기본 GatewayClass 리소스의 이름이에요. GatewayAPI 리소스에서 추가 게이트웨이 클래스와 다른 커스터마이징을 정의할 수도 있어요.
tigera-gateway-class에 연결되는 Gateway 리소스를, 프록시가 동작하기를 원하는 네임스페이스에 만들어요.

기본 gatewayClassName을 쓰는 Gateway 리소스 예시 스니펫이에요.
```
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: <gateway-name>
  namespace: <gateway-namespace>
spec:
  gatewayClassName: tigera-gateway-class
  ...
```
<gateway-name>을 자신의 게이트웨이 이름으로, <gateway-namespace>를 게이트웨이가 동작하기를 원하는 네임스페이스로 바꾸세요. 게이트웨이를 사용하려는 모든 서비스에서 이 게이트웨이 이름을 참조하게 돼요.

프록시와 그 Service, 그리고 로드 밸런서는 이 Gateway와 같은 네임스페이스에 만들어져요. 프록시가 동작 중인지 확인하려면 해당 네임스페이스의 파드를 조회해요.
```
kubectl get pods -n <gateway-namespace>
```

클러스터가 글로벌 기본 거부 정책을 강제한다면, Gateway 네임스페이스에 프록시 파드가 게이트웨이 컨트롤러와 DNS에 도달할 수 있게 해 주는 네트워크 정책을 적용하세요. 이 정책이 없으면 프록시가 시작되지 못해요.

apiVersion: projectcalico.org/v3
kind: NetworkPolicy
metadata:
  name: allow-tigera-gateway-proxy
  namespace: <gateway-namespace>
spec:
  selector: 'app.kubernetes.io/name == "envoy"'
  types: [Ingress, Egress]
  ingress:
    - action: Allow
  egress:
    - action: Allow # DNS
      protocol: UDP
      destination:
        namespaceSelector: 'projectcalico.org/name == "kube-system"'
        selector: 'k8s-app == "kube-dns"'
        ports: [53]
    - action: Allow # 게이트웨이 컨트롤러에서 오는 구성
      protocol: TCP
      destination:
        namespaceSelector: 'projectcalico.org/name == "calico-system"'
        selector: 'app.kubernetes.io/name == "gateway-helm"'
        ports: [18000]

<gateway-namespace>를 Gateway를 만든 네임스페이스로 바꾸세요. 자신의 백엔드에 필요한 egress 규칙은 상황에 맞게 추가하세요.

자신의 Gateway 리소스를 .spec.parentRefs로 참조하는 게이트웨이 라우팅 리소스를 만들어요.

HTTPRoute 리소스 예시 스니펫이에요.
```
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-httproute
spec:
  parentRefs:
    - name: <gateway-name>
  ...
```
<gateway-name>을 자신의 Gateway 리소스 이름으로 바꾸세요.

추가 리소스

더 알아보기 (Learn more)

순서를 정리하면 GatewayAPI → Gateway → HTTPRoute 참조의 세 단계예요. 기본 거부 환경에서는 envoy 파드의 DNS(UDP 53)와 컨트롤러(TCP 18000) 허용 정책이 필수라는 점을 잊지 마세요. 커스텀 게이트웨이 클래스가 필요하면 customize 문서로 이어져요.