Gateway API 컨트롤러 배포

Gateway API는 Kubernetes에서 서비스 네트워킹을 관리하기 위한 차세대 API입니다. Gateway API 컨트롤러는 Gateway, HTTPRoute 등의 리소스에 정의된 규칙에 따라 클러스터 외부에서 내부 서비스로의 트래픽을 처리합니다. Gateway API에 대한 자세한 설명은 Kubernetes Gateway API 공식 문서를 참고하시기 바랍니다. 클러스터에 Gateway API 컨트롤러를 설정하고 배포하는 방법은 다음과 같습니다.

안내

본 가이드는 NGINX Gateway Fabric(v2.3.0 검증 기준)을 활용하여 Gateway API 컨트롤러를 배포하는 예시를 안내합니다.

Kubernetes Engine 서비스 자체는 Gateway API 컨트롤러를 지원하지 않으므로, 컨트롤러의 선택부터 배포 및 운영까지는 모두 사용자의 재량에 따릅니다. 또한, 명시된 버전과 다른 버전을 사용할 경우 배포 매니페스트와 Helm 차트 옵션이 상이할 수 있으므로 반드시 사용 중인 버전의 공식 문서를 함께 참고해 주시기 바랍니다.

Ingress와 Gateway API 비교

기존 인그레스(Ingress)는 하나의 리소스에 Host, Path, TLS, Backend를 모두 정의하는 단일 리소스 모델입니다. 반면 Gateway API는 역할에 따라 GatewayClass → Gateway → HTTPRoute 3계층으로 분리하여, 인프라 관리자와 애플리케이션 개발자가 각자의 관심사를 독립적으로 관리할 수 있습니다.

구분	Ingress	Gateway API
라우팅 정의	Ingress 리소스 1개	Gateway + HTTPRoute 분리
TLS 설정	`spec.tls`	Gateway `listeners[].tls`
경로 매칭	`spec.rules[].http.paths`	HTTPRoute `spec.rules[].matches`
호스트 매칭	`spec.rules[].host`	HTTPRoute `spec.hostnames`
백엔드 지정	`backend.service.name` / `port`	`backendRefs[].name` / `port`
컨트롤러 선택	`ingressClassName`	`gatewayClassName`
크로스 네임스페이스	미지원	ReferenceGrant로 지원
헤더 기반 라우팅	어노테이션(비표준)	`matches[].headers` (표준)
트래픽 분할	미지원	`backendRefs[].weight`

기존 인그레스에서 Gateway API로 마이그레이션하는 방법은 인그레스에서 Gateway API로 마이그레이션 문서를 참고해 주세요.

Step 1. 사전 작업

Gateway API 컨트롤러를 설정 및 배포하기 위해서는 다음의 사전작업이 필요합니다.

Gateway API 컨트롤러를 배포할 클러스터를 생성합니다.
생성한 클러스터에 Gateway API 컨트롤러 배포 명령을 보내기 위한 kubectl 제어 설정을 수행합니다.

Gateway API CRD(Custom Resource Definition)를 클러스터에 설치합니다.

Gateway API CRD 설치
kubectl --kubeconfig=$KUBE_CONFIG kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.3.0" | kubectl --kubeconfig=$KUBE_CONFIG apply -f -

설치 확인
kubectl --kubeconfig=$KUBE_CONFIG get crd | grep gateway

출력 결과
backendtlspolicies.gateway.networking.k8s.io     2026-03-19T02:59:09Z
gatewayclasses.gateway.networking.k8s.io         2026-03-19T02:59:09Z
gateways.gateway.networking.k8s.io               2026-03-19T02:59:10Z
grpcroutes.gateway.networking.k8s.io             2026-03-19T02:59:10Z
httproutes.gateway.networking.k8s.io             2026-03-19T02:59:10Z
referencegrants.gateway.networking.k8s.io        2026-03-19T02:59:10Z

Step 2. Gateway API 컨트롤러 배포

오픈소스 NGINX Gateway Fabric 기반의 Gateway API 컨트롤러를 배포합니다.

안내

현재 Kubernetes Engine 서비스에서는 Kubernetes Engine의 Admission Webhook을 지원하지 않습니다. Admission Webhook이 설정된 서비스를 배포하려면 hostNetwork: true 설정이 필요합니다.

YAML 파일로 Gateway API 컨트롤러 배포

Gateway API 컨트롤러 배포 시, 네임스페이스가 존재하지 않아 배포가 실패하는 현상이 있습니다. 따라서 다음 명령어로 먼저 네임스페이스를 생성해 주세요.

네임스페이스 생성
kubectl --kubeconfig=$KUBE_CONFIG create namespace nginx-gateway

다음 명령어를 터미널에 입력하여 NGINX Gateway Fabric의 CRD와 컨트롤러를 클러스터에 배포합니다. Gateway API 컨트롤러에 필요한 서비스, GatewayClass 등 리소스들이 한 번에 배포됩니다.

NGINX Gateway Fabric CRD 배포
kubectl --kubeconfig=$KUBE_CONFIG apply --server-side -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v2.3.0/deploy/crds.yaml

NGINX Gateway Fabric 컨트롤러 배포
kubectl --kubeconfig=$KUBE_CONFIG apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v2.3.0/deploy/default/deploy.yaml

Helm을 사용하여 Gateway API 컨트롤러 배포

쿠버네티스 패키지 관리 도구인 Helm을 사용하여 Gateway API 컨트롤러를 배포합니다.

Gateway API 컨트롤러를 설치하기 전, Helm client를 설치합니다. 운영체제별 Helm 설치에 대한 자세한 설명은 Helm 공식 문서 > 헬름 설치하기를 참고하시기 바랍니다.

다음의 명령어를 터미널에 입력하여 NGINX Gateway Fabric을 클러스터에 배포합니다. NGINX Gateway Fabric은 OCI 레지스트리를 통해 Helm chart를 제공하므로, 별도의 helm repo add 없이 바로 설치할 수 있습니다.

NGINX Gateway Fabric 배포
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
    --version 2.3.0 \
    --namespace nginx-gateway --create-namespace

출력 결과
Pulled: ghcr.io/nginx/charts/nginx-gateway-fabric:2.3.0
Digest: sha256:96910ca9172f8e29c7fbfff9915403eff899653c8d2c9b2703f6e2976744591f
NAME: ngf
LAST DEPLOYED: Thu Mar 19 13:17:49 2026
NAMESPACE: nginx-gateway
STATUS: deployed
REVISION: 1
TEST SUITE: None

기존 NGINX Gateway Fabric Helm이 배포되어 있는 경우
helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
    --version 2.3.0 \
    --namespace nginx-gateway

Step 3. Gateway API 컨트롤러 배포 확인

Gateway API 컨트롤러가 정상적으로 배포되었는지 확인하기 위해 다음의 명령어를 터미널에 입력하고 파드의 상태를 관찰합니다. 이때 nginx-gateway 파드가 정상적으로 실행되는지 확인합니다.
- nginx-gateway 파드가 running 상태로 실행되고 있다면 Ctrl+C 키를 눌러서 명령을 취소합니다.
  파드 정상 실행 확인
```
kubectl --kubeconfig=$KUBE_CONFIG get pods -n nginx-gateway --watch
```
  실행 결과
```
NAME                                 READY   STATUS      RESTARTS   AGE
nginx-gateway-cd9c6c4f5-jhbbx        1/1     Running     0          41s
nginx-gateway-cert-generator-rgp26   0/1     Completed   0          41s
```

GatewayClass 리소스가 정상적으로 생성되었는지 확인합니다.

GatewayClass 확인
kubectl --kubeconfig=$KUBE_CONFIG get gatewayclass

실행 결과
NAME    CONTROLLER                                  ACCEPTED   AGE
nginx   gateway.nginx.org/nginx-gateway-controller   True       60s

Step 4. Gateway 리소스 생성

Gateway API 컨트롤러가 배포되면, Gateway 리소스를 생성하여 리스너를 구성합니다. Gateway 리소스를 생성하면 로드 밸런서가 함께 프로비저닝됩니다.

다음의 YAML 파일을 사용하여 Gateway 리소스를 생성합니다.

gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nginx-gateway
  namespace: nginx-gateway
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - name: nginx-tls-secret
    allowedRoutes:
      namespaces:
        from: All

Gateway 리소스 생성
kubectl --kubeconfig=$KUBE_CONFIG apply -f gateway.yaml

Gateway 리소스가 정상적으로 생성되었는지 확인합니다.

Gateway 리소스 확인
kubectl --kubeconfig=$KUBE_CONFIG get gateway -n nginx-gateway

실행 결과
NAME            CLASS   ADDRESS                                                                 PROGRAMMED   AGE
nginx-gateway   nginx   k8s-nginxga-nginxga-xxxxxxxxxx-xxxxxx.ke.kr-central-2.kakaocloud.com   True         3m47s

실행 결과에서 Gateway의 ADDRESS를 확인합니다. ADDRESS는 로드 밸런서의 도메인 주소이며, 이후 HTTPRoute를 통해 오픈하는 서비스의 엔드포인트가 됩니다.

Step 5. HTTPRoute를 사용한 트래픽 라우팅

HTTPRoute 리소스를 사용하여 Gateway로 들어오는 트래픽을 백엔드 서비스로 라우팅합니다.

안내

아래 예시는 demo-apps 네임스페이스에 demo-app-v1, demo-app-v2 Service가 이미 배포되어 있다고 가정합니다.
다른 Service 이름이나 포트를 사용하는 경우 backendRefs 값을 실제 환경에 맞게 수정해 주세요.

다음의 YAML 파일을 사용하여 HTTPRoute 리소스를 생성합니다.

httproute.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: demo-route
  namespace: demo-apps
spec:
  parentRefs:
  - name: nginx-gateway
    namespace: nginx-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1
    backendRefs:
    - name: demo-app-v1
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /v2
    backendRefs:
    - name: demo-app-v2
      port: 80

HTTPRoute 리소스 생성
kubectl --kubeconfig=$KUBE_CONFIG apply -f httproute.yaml

HTTPRoute 리소스가 정상적으로 생성되었는지 확인합니다.

HTTPRoute 리소스 확인
kubectl --kubeconfig=$KUBE_CONFIG get httproute -n demo-apps

실행 결과
NAME         HOSTNAMES   AGE
demo-route               7s

Gateway로 생성된 로드 밸런서에 퍼블릭 IP 설정하기

Gateway 리소스를 배포하여 생성된 로드 밸런서의 외부 통신이 필요할 경우, 해당 로드 밸런서의 퍼블릭 IP 사용 여부를 설정할 수 있습니다.
- 다음의 명령어를 실행하여 Gateway를 배포해 생성된 로드 밸런서 유형 서비스를 확인합니다.
로드 밸런서 유형 서비스 확인
```
kubectl --kubeconfig=$KUBE_CONFIG get svc -n nginx-gateway
```
로드 밸런서 유형 Service 객체의 metadata.annotations 하위 service.beta.kubernetes.io/openstack-internal-load-balancer 값을 설정하여 로드 밸런서의 퍼블릭 IP 사용을 설정합니다.
- 프라이빗 IP를 갖는 로드 밸런서를 생성하려면 값을 true로 설정 (기본값)
- 퍼블릭 IP를 갖는 로드 밸런서를 생성하려면 값을 false로 설정

안내

로드 밸런서 상세 옵션에 대한 자세한 내용은 로드 밸런서 생성 및 삭제 > 부록. 로드 밸런서 상세 옵션 설정하기 문서를 참고하시기 바랍니다.

주의

service.beta.kubernetes.io/openstack-internal-load-balancer 설정값에 따라, 로드 밸런서의 퍼블릭 IP가 새로운 퍼블릭 IP를 생성하여 연결 또는 연결 해제됩니다. false로 설정하여 로드 밸런서에 사용한 퍼블릭 IP가 있었다면, 이후 true로 설정값을 변경하여도 퍼블릭 IP 연결 해제 상태가 되어 퍼블릭 IP 과금 대상에 포함되니 유의해 주세요.
Kubernetes Engine 로드 밸런서에 사용한 퍼블릭 IP 삭제는 카카오클라우드 콘솔 > VPC > 퍼블릭 IP 메뉴에서 가능합니다. 자세한 설명은 퍼블릭 IP 생성 및 관리를 참고하시기 바랍니다.

Ingress와 Gateway API 비교​

Step 1. 사전 작업​

Step 2. Gateway API 컨트롤러 배포​

YAML 파일로 Gateway API 컨트롤러 배포​

Helm을 사용하여 Gateway API 컨트롤러 배포​

Step 3. Gateway API 컨트롤러 배포 확인​

Step 4. Gateway 리소스 생성​

Step 5. HTTPRoute를 사용한 트래픽 라우팅​

Gateway로 생성된 로드 밸런서에 퍼블릭 IP 설정하기​