Ingress to Envoy Gateway

ingress2eg helps translate Ingress to Gateway API and Envoy Gateway CRD resources.

⚠️ Important Notice

This is an unofficial POC tool forked from ingress2gateway.

• This tool is a temporary solution until official support is available
• aim to backport features to the official ingress2gateway project
• Once official support is complete, strongly recommend using ingress2gateway instead

🎯 Scope

This project primarily focuses on converting NGINX Ingress resources to Envoy Gateway, in response to the retirement of ingress-nginx. The main goal is to provide a migration path for users transitioning from NGINX Ingress to Envoy Gateway.

🚀 Supported Features

This tool supports converting the following NGINX Ingress annotations to Envoy Gateway resources:

Feature Category	NGINX Ingress Annotations	Envoy Gateway Resources	Description
Session Affinity	affinity, session-cookie-name, session-cookie-max-age, session-cookie-expires, session-cookie-samesite	BackendTrafficPolicy (LoadBalancer.ConsistentHash)	Cookie-based session affinity for sticky sessions
Authentication - Basic	auth-type, auth-secret *1	SecurityPolicy (BasicAuth)	HTTP Basic Authentication
Authentication - mTLS	auth-tls-secret	ClientTrafficPolicy (ClientTLSSettings)	Mutual TLS authentication at Gateway listener level
Authentication - External	auth-url *2, auth-response-headers	SecurityPolicy (ExtAuth)	External authentication service integration
Backend TLS	proxy-ssl-secret, proxy-ssl-verify, proxy-ssl-name, proxy-ssl-server-name	Backend (BackendTLSSettings)	TLS configuration for upstream connections
Backend Protocol	backend-protocol	HTTPRoute / GRPCRoute	Protocol detection and route type conversion (HTTP/GRPC)
Buffer Limits	proxy-body-size	BackendTrafficPolicy (BackendConnection.BufferLimit)	Client request buffer size limits
Canary Deployment	canary, canary-by-header, canary-by-header-value, canary-weight, canary-weight-total	HTTPRoute (HTTPRouteRule with weights/matches)	Header-based and weight-based traffic splitting
CORS	enable-cors, cors-allow-origin, cors-allow-methods, cors-allow-headers, cors-expose-headers, cors-max-age, cors-allow-credentials	SecurityPolicy (CORS)	Cross-Origin Resource Sharing policy
Header Modification	x-forwarded-prefix, upstream-vhost	HTTPRoute (RequestHeaderModifier filter)	Request header manipulation
IP Range Control	whitelist-source-range, denylist-source-range	SecurityPolicy (Authorization)	IP-based access control with allowlist/denylist
Rate Limiting	limit-rps, limit-rpm	BackendTrafficPolicy (RateLimit.Local)	Request rate limiting per client IP
Redirect	ssl-redirect, force-ssl-redirect, permanent-redirect, temporal-redirect, app-root	HTTPRoute (RequestRedirect filter)	HTTP to HTTPS and URL redirects
Regex Path Matching	use-regex	HTTPRoute (PathMatchRegularExpression)	Regular expression path matching
Retry Policy	proxy-next-upstream, proxy-next-upstream-tries	BackendTrafficPolicy (Retry)	Automatic request retry on failures
URL Rewrite	rewrite-target	HTTPRoute (URLRewrite filter) or HTTPRouteFilter (ExtensionRef)	Path rewriting with or without regex
SSL Passthrough	ssl-passthrough	TLSRoute	TLS passthrough mode without termination
Timeout	proxy-connect-timeout	BackendTrafficPolicy (Timeout.TCP)	Connection timeout configuration

Notes

*1 Basic Authentication Requirements:

• Only basic auth-type is supported. Other authentication types (e.g., digest) are not converted.
• For Envoy Gateway, the Secret must contain a key named .htpasswd in htpasswd format.
• Example Secret format:

  apiVersion: v1
  kind: Secret
  metadata:
    name: basic-auth-secret
  type: Opaque
  data:
    .htpasswd: <base64-encoded-htpasswd-content>

*2 External Authentication Requirements:

• Only kubernetes service endpoint is supported in auth-url. (e.g., http://auth-service.namespace.svc.cluster.local/auth)

🚀 Quick Start

Installation

Option 1: Install directly with go install

go install github.com/kkk777-7/ingress2eg@latest

Option 2: Build from source

git clone https://github.com/kkk777-7/ingress2eg.git
cd ingress2eg
make build

Basic Usage

Convert from Kubernetes Cluster

Convert all Ingress resources in the current namespace:

ingress2eg print

Convert from a specific namespace:

ingress2eg print --namespace myapp

Convert from all namespaces:

ingress2eg print --all-namespaces

Convert from File

Convert Ingress resources from a YAML or JSON file:

ingress2eg print --input-file ingress.yaml

Save the output to a file:

ingress2eg print --input-file ingress.yaml > gateway-resources.yaml

Advanced Options

Specify a custom Ingress class (default is nginx):

ingress2eg print --ingress-nginx-ingress-class=custom-nginx

Change output format:

# Output as JSON
ingress2eg print --output json

# Output as YAML (default)
ingress2eg print --output yaml

Example

Given an Ingress resource with NGINX annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-app
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "route"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: nginx
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

Run the conversion:

ingress2eg print --input-file ingress.yaml

This will generate:

• Gateway resource
• HTTPRoute resource
• BackendTrafficPolicy with session affinity configuration
• SecurityPolicy with CORS configuration

The tool will display informational messages showing which annotations were parsed and converted:

parsed Affinity (affinity, session-cookie-name) of ingress default/example-app
parsed CORS (enable-cors, cors-allow-origin) of ingress default/example-app
converted Affinity annotations of ingress default/example-app for rule rule-0
converted CORS annotations of ingress default/example-app for rule rule-0

📚 References

Gateway API

• Gateway API Specification
• Gateway API GEPs

NGINX Ingress

• NGINX Ingress Controller Documentation
• NGINX Ingress Controller GitHub
• Retirement Announcement

Envoy Gateway

• Envoy Gateway Documentation
• Envoy Gateway GitHub