Automated Conversion with KubeLB [Beta]

KubeLB can automatically convert your Ingress resources to Gateway API. Point it at your Ingresses, and it creates the equivalent HTTPRoutes and GRPCRoutes for you.

How It Works

1. The converter watches your Ingress resources
2. For each Ingress, it creates an HTTPRoute (or GRPCRoute for gRPC backends)
3. For annotations that map to Envoy Gateway policies (CORS, rate limiting, timeouts, etc.), it creates the corresponding SecurityPolicy or BackendTrafficPolicy resources.
4. It manages a Gateway resource with listeners for your TLS hosts
5. Status annotations on your Ingress tell you what happened

The created routes persist even after you delete the source Ingress, allowing you to migrate gradually and delete Ingresses at your own pace.

Getting Started

Choose Your Mode

Integrated Mode (Recommended)

You’re already using KubeLB for load balancing and want to add conversion:

kubelb:
  tenantName: <your-tenant-name>
  clusterSecretName: kubelb-cluster
  enableGatewayAPI: true
  ingressConversion:
    enabled: true
    gatewayName: kubelb
    gatewayClass: kubelb

With integrated mode, KubeLB handles everything for you:

• No Gateway setup required per tenant cluster — KubeLB manages the Gateway lifecycle, GatewayClass, and all CRDs. No need to install Envoy Gateway separately in each tenant cluster. Envoy Gateway is installed in the manager cluster.
• Policy support out of the box — Envoy Gateway policies (ClientTrafficPolicy, BackendTrafficPolicy) work automatically since KubeLB’s manager cluster has the CRDs installed.
• Centralized traffic management — Converted routes are synced to the manager cluster where KubeLB serves traffic using its Layer 7 load balancing capabilities.
• Multi-tenant ready — Each tenant cluster can run the converter independently while KubeLB handles traffic routing centrally.

Standalone Mode

You just want the converter, without KubeLB’s load balancing and other controllers:

kubelb:
  ingressConversion:
    enabled: true
    standaloneMode: true
    gatewayName: my-gateway
    gatewayClass: eg  # match your Gateway implementation

In standalone mode, you don’t need tenantName or clusterSecretName.

Prerequisites

Before running the converter, set up your environment for Gateway API and Envoy Gateway:

1. Install Envoy Gateway

Follow the Envoy Gateway installation guide to install it in your cluster. This is required to ensure that Gateway API CRDs and Envoy Gateway CRDs are installed in the cluster.

In integrated mode, this should be installed only once in the Management Cluster. In standalone mode, this should be installed in each tenant cluster since KubeLB load balancing and controllers are disabled in standalone mode.

2. Create a GatewayClass

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

In integrated mode, this should be created in the Management Cluster and in standalone mode, this should be created in each tenant cluster.

Make sure the gatewayClass in your values matches this name.

3. (Integrated Mode Only) Create SecurityPolicy CRD

SecurityPolicy is not installed by KubeLB itself and needs to be installed manually in the tenant cluster:

kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/refs/tags/v1.6.3/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml

Since in standalone mode, we install Envoy Gateway in each tenant cluster, the SecurityPolicy CRD will be installed automatically by the Envoy Gateway Helm Chart.

4. (Optional) Pre-create a Gateway

The converter creates a Gateway automatically. If you need custom parameters (specific listeners, infrastructure settings, etc.), create it yourself first:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80

Set gatewayName and gatewayNamespace in your values to match. The converter will use your existing Gateway instead of creating one.

Install

helm upgrade --install kubelb-ccm oci://quay.io/kubermatic/helm-charts/kubelb-ccm --version=v1.3.1 --namespace kubelb -f values.yaml --create-namespace

helm upgrade --install kubelb-ccm oci://quay.io/kubermatic/helm-charts/kubelb-ccm-ee --version=v1.3.1 --namespace kubelb -f values.yaml --create-namespace

Check Your Results

After installation, check if your Ingresses are being converted:

# Watch all converted Ingresses
watch "kubectl get ingress -A -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,STATUS:.metadata.annotations.kubelb\.k8c\.io/conversion-status' | grep -E 'converted|partial'"

# Check conversion status for a specific Ingress
kubectl get ingress my-app -o jsonpath='{.metadata.annotations.kubelb\.k8c\.io/conversion-status}'

# View any warnings (annotations that couldn't be fully converted)
kubectl get ingress my-app -o jsonpath='{.metadata.annotations.kubelb\.k8c\.io/conversion-warnings}'

# List created routes
kubectl get httproutes -l kubelb.k8c.io/source-ingress=my-app.default

The status will be one of:

• converted — Everything worked
• partial — Some routes worked, others didn’t
• pending — Routes created but Gateway controller hasn’t accepted them yet
• skipped — Ingress uses unsupported features (like canary)
• failed — Something went wrong

Customizing Behavior

Filter Which Ingresses to Convert

By default, all Ingresses are converted. To convert only specific ones:

ingressConversion:
  ingressClass: "nginx"  # only convert Ingresses with this class

To exclude a specific Ingress, annotate it:

metadata:
  annotations:
    kubelb.k8c.io/skip-conversion: "true"

Transform Hostnames

Useful for migrating between environments. Convert app.staging.example.com to app.prod.example.com:

ingressConversion:
  domainReplace: "staging.example.com"
  domainSuffix: "prod.example.com"

Add Gateway Annotations

The converter creates a Gateway resource for you. To add annotations (e.g., for cert-manager):

ingressConversion:
  gatewayAnnotations: "cert-manager.io/cluster-issuer=letsencrypt,external-dns.alpha.kubernetes.io/target=lb.example.com"

All Configuration Options

TLS Secret Handling

When an Ingress references a TLS secret, Gateway API requires the secret to be in the same namespace as the Gateway. Since the converter creates a shared Gateway (typically in the kubelb namespace), TLS secrets from Ingress namespaces must be copied.

How it works:

1. When copyTLSSecrets: true (default), secrets are copied from the Ingress namespace to the Gateway namespace
2. Copied secrets are named ingress-<namespace>-<secretname> to avoid conflicts
3. The Gateway’s listener references the copied secret

Example: An Ingress in namespace app with secretName: tls-cert results in:

• Secret copied to kubelb/ingress-app-tls-cert
• Gateway listener references ingress-app-tls-cert

With domain transformation:

When using domainReplace and domainSuffix to transform hostnames, the original TLS certificate may not be valid for the new domain. In this case:

1. The original secret is still copied (provides a starting point)
2. Configure cert-manager on the Gateway to issue new certificates for the transformed domains
3. Cert-manager will overwrite the copied secret with a valid certificate

ingressConversion:
  domainReplace: "old.example.com"
  domainSuffix: "new.example.com"
  gatewayAnnotations: "cert-manager.io/cluster-issuer=letsencrypt"

Disabling secret sync:

If you manage TLS secrets separately using different workflows or cert-manager can generate them for new domains. It’s recommended to disable the secret sync and manage TLS secrets separately:

ingressConversion:
  copyTLSSecrets: false

What Gets Converted

Annotations That Work Automatically

These NGINX annotations are converted to native Gateway API features:

Envoy Gateway Policy Generation

For policy generation, we only support Envoy Gateway as the target Gateway API implementation. The converter auto-creates SecurityPolicy and BackendTrafficPolicy resources. ClientTrafficPolicy is not auto-created because it targets Gateway, this results in it being applied to all listeners on the Gateway and that can cause issues for other HTTPRoutes on the same Gateway. Annotations requiring ClientTrafficPolicy generate warnings instead.

Policy generation is enabled by default in both standalone and integrated modes, and can be disabled by configuring the values.yaml with:

ingressConversion:
  disableEnvoyGatewayFeatures: true

When disabled, annotations are still converted to suggestions placed in the conversion-warnings annotation on the Ingress resource.

Annotations with Auto-Created Policies

These annotations automatically create Envoy Gateway policies:

Annotations That Need Manual Follow-up

These annotations generate warnings only—manual configuration is required:

Note: After manual follow-up, update the annotation kubelb.k8c.io/conversion-status to converted. This helps track which Ingresses have been fully migrated. This is required so that the converter knows that the conversion is complete and it can stop watching the Ingress resource.

Annotations That Don’t Work

These have no Gateway API equivalent:

Canary Ingresses

Ingresses with nginx.ingress.kubernetes.io/canary: "true" are skipped entirely. NGINX canary Ingresses work by modifying a primary Ingress, which doesn’t translate to Gateway API.

Instead, use HTTPRoute’s native traffic splitting:

spec:
  rules:
  - backendRefs:
    - name: stable
      port: 80
      weight: 90
    - name: canary
      port: 80
      weight: 10

Limitations

• RegularExpression paths depend on your Gateway implementation’s support
• Envoy Gateway policies are created locally in the tenant cluster—ensure Envoy Gateway CRDs are installed
• cert-manager annotations aren’t propagated automatically—use gatewayAnnotations instead
• GRPCRoute doesn’t support HTTPRoute filters (redirects, rewrites, headers)
• Gateway listeners are shared across all converted Ingresses
• TLS secrets are copied to Gateway namespace by default; with domain transformation, you may need cert-manager to issue new certificates

Troubleshooting

Re-triggering Conversion for an Ingress

Once an Ingress is marked as converted or partial, the converter stops watching it. If the conversion was incorrect or you want to re-run it (e.g., after fixing Gateway configuration), reset the status:

# Reset conversion status to re-trigger conversion
kubectl annotate ingress <ingress-name> kubelb.k8c.io/conversion-status-

# Also remove the verification timestamp if present
kubectl annotate ingress <ingress-name> kubelb.k8c.io/verification-timestamp-

The converter will pick up the Ingress on its next reconciliation cycle and re-convert it.

Finding Broken Conversions

To find Ingresses that were marked as converted but whose HTTPRoutes are not actually accepted:

# List all HTTPRoutes with their acceptance status
kubectl get httproute -A -o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name} Accepted={.status.parents[0].conditions[?(@.type=="Accepted")].status} Reason={.status.parents[0].conditions[?(@.type=="Accepted")].reason}{"\n"}{end}'

# Find routes that are not accepted
kubectl get httproute -A -o json | jq -r '.items[] | select(.status.parents[0].conditions[] | select(.type=="Accepted" and .status!="True")) | "\(.metadata.namespace)/\(.metadata.name): \(.status.parents[0].conditions[] | select(.type=="Accepted") | .reason)"'

Common Issues