GateShift

Ingress → Gateway API migration with annotation fidelity you can trust.

Quick start · Why GateShift · CLI · Docs · Contributing

---

GateShift converts Kubernetes Ingress (including NGINX / cert-manager annotations) into Gateway API manifests — without silently dropping policy.

Every feature is classified and reported:

Level	Meaning	Behavior
L1	Native Gateway API	Emits HTTPRoute filters (rewrite, redirect, headers)
L2	Provider extension	Emits Policy CRDs (BackendTrafficPolicy, SecurityPolicy, Certificate, …)
L3	Untranslatable	Flags snippets / Lua for humans; validate blocks unsafe apply

CLI: gateshift · Operator: gateshift-operator · License: Apache 2.0

---

Why GateShift

Capability	Baseline ingress2gateway	GateShift
Hosts / paths / backends	Yes	Yes
Annotation fidelity	Often dropped	L1 / L2 / L3 matrix + readiness score
Snippets	Ignored	Pattern library (promote safe idioms)
Canary Ingress pairs	Manual	Weighted HTTPRoute merge
Controller fit	Rarely checked	validate capability matrix
GitOps	Manual	migrate PR / dry-run artifacts
In-cluster	N/A	MigrationRequest operator

Design deep-dive: docs/ARCHITECTURE.md · comparison: docs/BEATING_INGRESS2GATEWAY.md

---

Install / build

Requirements: Go 1.22+, optional Docker + KinD for cluster tests.

git clone https://github.com/gateshift/gateshift.git
cd gateshift
make tidy test build
# Linux:   bin/gateshift
# Windows: bin/gateshift.exe

Cross-compile for WSL / Linux from Windows:

$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o bin/gateshift ./cmd/gateshift

---

Quick start

# Audit migratability
gateshift audit -f examples/ingress-checkout.yaml --target=envoy-gateway

# Emit Gateway API manifests
gateshift convert -f examples/ingress-checkout.yaml --target=envoy-gateway -o gateway.yaml

# Fail closed on untranslatable features
gateshift validate -f examples/ingress-checkout.yaml --target=envoy-gateway

# Structural comparison
gateshift diff -f examples/ingress-checkout.yaml

# GitOps dry-run (writes .gateshift-pr/); set GITHUB_TOKEN + --auto-pr for a real PR
gateshift migrate -f examples/ingress-checkout.yaml --target=envoy-gateway

# Annotation catalog / gap analysis
gateshift coverage -f examples/ingress-checkout.yaml

Live cluster:

gateshift audit --namespace shop --target=envoy-gateway

Targets: standard · envoy-gateway · cilium · istio · kong

End-to-end demo (real app on KinD): examples/demo-podinfo · bash scripts/demo-podinfo.sh

---

CLI reference

Command	Purpose
audit	L1/L2/L3 matrix + readiness score (file or --namespace)
convert	Emit Gateway / HTTPRoute / Policy YAML
diff	Structural Ingress vs Gateway API view
validate	Provider capability / conformance gate
migrate	Convert + GitHub PR or local dry-run pack
coverage	Catalog coverage and per-key [OK] / [GAP] / [??]
version	Print CLI version

---

Annotation coverage

L1 — rewrite-target, ssl-redirect, force-ssl-redirect, permanent/temporal redirects, CORS, from-to-www-redirect, app-root, x-forwarded-prefix

L2 — rate limits, cert-manager issuers, affinity / session cookies, IP allow/deny, proxy timeouts & body size, backend TLS, canary merge, mirroring, use-regex, auth-url scaffolds (Envoy), and the rest of the tracked catalog

L3 / pattern-assisted — configuration-snippet, server-snippet, modsecurity-snippet

Tracked catalog coverage is 100% of listed keys (gateshift coverage). Snippets stay L3 by design: pattern-assisted, never silently dropped.

---

Cluster smoke test (KinD)

See docs/TESTING.md.

# Ubuntu WSL (requires Linux binary at bin/gateshift)
export PATH=$HOME/bin:$PATH
bash scripts/test-smoke.sh
# Expected: PASS and HTTP body checkout-ok

---

Operator

kubectl apply -f config/crd/migrationrequest.yaml
# or: helm install gateshift-operator charts/gateshift-operator
kubectl apply -f examples/migrationrequest.yaml
make build-operator

The reconciler watches MigrationRequest, converts the referenced Ingress, updates status, and optionally opens a GitOps PR.

---

Repository layout

api/v1alpha1/              MigrationRequest API
cmd/gateshift/             CLI entrypoint
cmd/gateshift-operator/    Operator manager
internal/cli/              Cobra commands
internal/controller/       Reconciler
pkg/adapters/              AnnotationAdapter plugin interface
pkg/adapters/nginx/        NGINX / cert-manager adapters + catalog
pkg/patterns/              Snippet pattern library
pkg/ir/                    Intermediate representation
pkg/convert/               Ingress → IR → YAML (+ canary merge)
pkg/conformance/           Provider capability checks
pkg/cluster/               Live Ingress listing
pkg/gitops/                GitHub PR + dry-run artifacts
charts/gateshift-operator/ Helm chart
config/crd/                CRD manifests
examples/                  Sample Ingress + demos
examples/corpus/           Regression fixtures
scripts/                   KinD e2e / smoke / demo
docs/                      Architecture, testing, roadmap
Logo/                      Project brand asset

---

Documentation

Doc	Description
docs/ARCHITECTURE.md	Pipeline, adapter model, cutover strategy
docs/TESTING.md	Unit, CLI, and KinD smoke testing
docs/BEATING_INGRESS2GATEWAY.md	Differentiation and coverage strategy
docs/ROADMAP.md	Near-term and longer-term work
CONTRIBUTING.md	How to extend adapters and patterns
SECURITY.md	Vulnerability reporting
CODE_OF_CONDUCT.md	Community standards

---

Status

Area	Maturity
CLI convert / audit / validate	Usable
Pattern library / canary merge	Usable
KinD smoke path (Envoy Gateway)	Proven
podinfo end-to-end demo	Proven
Operator / Helm	Scaffold — harden before wide deploy
Multi-controller (Traefik, ALB, GCE)	Planned

GateShift prioritizes safe, reviewable migration over claiming fully automatic conversion of every Ingress edge case.

---

License

Apache License 2.0 — see LICENSE.