ingress2gateway

제공자(Provider)와 이미터(Emitter) 기반 변환

ingress2gateway는 두 가지 구성 요소로 동작합니다. 제공자는 Ingress와 제공자별 CRD를 읽어 공통 중간 표현(IR)으로 바꾸고, 이미터는 그 IR을 받아 최종 Gateway API 출력을 생성합니다. 기본 이미터인 standard>는 코어 Gateway API 리소스(Gateway>, HTTPRoute>)를 만들며, 다른 이미터는 특정 Gateway API 프로젝트에 맞춘 리소스를 추가로 출력할 수 있습니다.

지원되는 Ingress 제공자

• apisix, cilium, ingress-nginx, istio, gce, kong, nginx, openapi3, traefik

지원되는 이미터

• standard(기본), agentgateway, airlock-microgateway, envoy-gateway, gce, kgateway

Ingress 필드 → Gateway API 매핑

입력된 Ingress 리소스를 기준으로 Gateway>와 HTTPRoute>가 생성되며, 다음과 같은 매핑이 적용됩니다.

• ingressClassName> 또는 kubernetes.io/ingress.class> 어노테이션 → 생성된 Gateway의 gatewayClassName>
• defaultBackend> → 호스트명이 없는 Listener와 catch-all HTTPRoute 생성
• tls[].hosts> → 포트 443의 HTTPS Listener, tls.mode = Terminate>
• tls[].secretName> → 각 HTTPS Listener의 listeners[].tls.certificateRefs>
• rules[].host> → 호스트명별 HTTP/HTTPS Listener 및 단일 호스트명을 가진 HTTPRoute
• rules[].http.paths[].path> → HTTPRoute>의 rules[].matches[].path.value>
• rules[].http.paths[].pathType> → Exact>는 그대로, Prefix>는 PathPrefix>로 변환
• rules[].http.paths[].backend> → HTTPRoute>의 rules[].backendRefs[]>

winget으로 설치(Windows)

winget을 사용해 직접 설치할 수 있습니다.

• winget install --id Kubernetes.ingress2gateway --exact

Go 개발 환경에서 설치

로컬에 Go가 설치되어 있다면 go install github.com/kubernetes-sigs/[email protected]> 명령으로 바이너리를 빌드할 수 있으며, 결과물이 $(go env GOPATH)/bin> 경로에 생성됩니다. 또는 릴리스 페이지에서 플랫폼별 바이너리를 직접 내려받을 수도 있습니다.

Homebrew(macOS/Linux)

Homebrew가 설치된 시스템에서는 다음 명령으로 설치합니다.

• brew install ingress2gateway>

소스에서 빌드

1. Git과 Go 1.25.5 이상을 시스템에 설치합니다.
2. 저장소를 클론합니다: git clone https://github.com/kubernetes-sigs/ingress2gateway.git && cd ingress2gateway>
3. make build> 명령으로 빌드합니다.
4. go install .> 명령으로 바이너리를 시스템에 설치합니다.

Ingress에서 Gateway API로의 점진적 마이그레이션

ingress2gateway는 Ingress v1 사양이 정해진 충돌 해결 규칙을 제공하지 않는 점을 보완하기 위해, 생성 시각이 오래된 Ingress 리소스부터 우선 처리하는 결정적 순서를 사용합니다. 생성 시각이 동일하면 네임스페이스/이름 기준으로 정렬하며, 동일 경로에 서로 다른 백엔드가 지정된 경우에는 정렬 순서상 뒤쪽 리소스에 대해 오류를 보고합니다. 이 정책을 통해 Gateway API 충돌 해결 가이드라인과 유사한 방식으로 마이그레이션 결과를 예측 가능하게 유지할 수 있습니다.

입력 소스 선택

운영 중인 클러스터에서 바로 변환할 수 있을 뿐 아니라, --input-file>을 사용해 미리 저장된 yaml/json 매니패스트를 입력으로 지정하면 클러스터 연결 없이도 동일한 결과를 얻을 수 있습니다. 이 방식은 변경 사항을 사전에 검토하거나 CI 환경에서 변환 결과를 검증할 때 유용합니다.

이미터 선택을 통한 출력 맞춤화

기본 standard> 이미터 대신 envoy-gateway, kgateway, agentgateway, airlock-microgateway, gce 등 프로젝트별 이미터를 지정하면, 해당 프로젝트에서 사용하는 BackendTrafficPolicy>나 HealthCheckPolicy> 같은 부가 리소스까지 함께 출력할 수 있습니다. README의 docs/emitters.md>에서 자세한 구조를 확인할 수 있습니다.

winget 외에 어떤 설치 방법을 제공하나요?

Go 설치 후 go install> 명령으로 빌드하거나, 릴리스 페이지에서 바이너리를 내려받을 수 있고, macOS/Linux에서는 Homebrew로 설치할 수 있습니다.

클러스터 없이도 변환할 수 있나요?

--input-file> 플래그로 yaml 또는 json 매니패스트 파일을 지정하면 클러스터에 접속하지 않고도 동일하게 변환할 수 있습니다.

기본 이미터 외에 어떤 출력을 만들 수 있나요?

envoy-gateway, kgateway, agentgateway, airlock-microgateway, gce 이미터를 지정하면 해당 프로젝트의 추가 리소스까지 함께 출력됩니다.