Ingress to Gateway API

KubeLB CLI ships with two interfaces for migrating Ingress resources to Gateway API: a command-line workflow and a web dashboard. Both use the same conversion engine and configuration and produce identical results.

Use the CLI for scripting, CI/CD pipelines, and targeted operations from the terminal. Use the dashboard for a visual overview of the migration, side-by-side YAML comparison, or batch operations.

For background on why to migrate and the overall strategy, see the Ingress to Gateway API Migration guide. For the Helm-based automated approach, see Automated Conversion with KubeLB.

Prerequisites

1. Install the CLI

Download the kubelb-cli archive from the kubermatic/kubelb releases page; the binary inside is named kubelb. See Installation for details and source builds.

2. Set your kubeconfig

The ingress commands only need a kubeconfig pointing to the cluster with your Ingress resources. No tenant name or KubeLB backend is required.

export KUBECONFIG=/path/to/kubeconfig

3. Install Gateway API CRDs

Your target cluster needs Gateway API CRDs installed. The easiest way is to install Envoy Gateway which bundles everything. If you also want automatic policy generation (CORS, rate limiting, IP allowlists), Envoy Gateway’s CRDs are required.

# Install Envoy Gateway (includes Gateway API + policy CRDs)
helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.3.0 -n envoy-gateway-system --create-namespace

4. Review configuration

Check the Configuration table below and set options via environment variables or flags. Defaults work for most setups.

CLI Workflow

The kubelb ingress command group covers the migration step by step: list your Ingresses, inspect individual ones with get, preview the converted output, and convert when satisfied.

List Ingresses

The list command shows all Ingress resources alongside their conversion status:

# List ingresses in a specific namespace
kubelb ingress list -n default

# List across all namespaces
kubelb ingress list -A

Output includes a summary row and a table:

Total: 5 | Converted: 2 | Partial: 0 | Pending: 0 | Failed: 0 | Skipped: 1 | New: 2

NAMESPACE   NAME        STATUS      HOSTS                ROUTES   WARNINGS
default     api-app     converted   api.example.com      1        -
default     web-app     converted   web.example.com      1        -
default     legacy      skipped     legacy.example.com   -        -
staging     frontend    new         app.staging.io       -        -
staging     backend     new         api.staging.io       -        -

Status values: converted, partial, pending, failed, skipped, new.

Preview Conversions

Always preview before converting. Preview shows the Gateway API resources that would be created without touching the cluster:

# Preview a single ingress
kubelb ingress preview my-app -n default

# Preview all ingresses in a namespace
kubelb ingress preview --all -n default

# Preview everything across all namespaces
kubelb ingress preview -A

Output includes any conversion warnings followed by the generated YAML: Gateway, HTTPRoutes, GRPCRoutes, and Envoy Gateway policies (if applicable). Review the warnings carefully; they indicate annotations that need manual follow-up.

Convert Ingresses

Once the preview looks right, convert:

# Convert a single ingress
kubelb ingress convert my-app -n default

# Convert all ingresses in a namespace
kubelb ingress convert --all -n default

# Convert across all namespaces
kubelb ingress convert -A

# Dry-run: print what would be applied without touching the cluster
kubelb ingress convert --all -n default --dry-run

# Export to files instead of applying (useful for GitOps workflows)
kubelb ingress convert -A --output-dir ./manifests

When converting, the CLI:

1. Creates or updates the shared Gateway resource with TLS listeners
2. Copies TLS secrets to the Gateway namespace (if --copy-tls-secrets is enabled)
3. Creates HTTPRoute and/or GRPCRoute for each Ingress
4. Creates Envoy Gateway policies (SecurityPolicy, BackendTrafficPolicy) for supported annotations
5. Waits for route acceptance by the Gateway controller
6. Annotates each source Ingress with its conversion status

Run kubelb ingress list again to see updated statuses.

Skip Ingresses

To exclude an Ingress from conversion, annotate it:

kubectl annotate ingress my-legacy-app kubelb.k8c.io/skip-conversion=true

Skipped Ingresses show status skipped in the list and are ignored by --all and -A operations.

Web Dashboard

The dashboard provides the same capabilities in a browser. Start it with:

kubelb serve

This opens a local web server at http://localhost:8080. Use --addr :3000 for a different port. You can use environment variables or flags to configure the dashboard.

Demo

Dashboard

CLI

Support

The conversion tools support ingress-nginx as the source controller and Envoy Gateway as the target implementation; see supported controllers and the KubeLB Ingress to Gateway API Converter guide.

Configuration

The ingress conversion commands only need a KUBECONFIG; no tenant name or KubeLB backend connection is required. All conversion behavior is controlled through these options, settable as flags or environment variables:

For details on which annotations are converted and how policies are generated, see the annotation tables in the automation guide.

Choosing Your Approach

A common approach: start with the dashboard or CLI to assess the migration, then enable automation through the KubeLB Helm chart for ongoing conversion of new Ingresses.