Common Issues and Solutions

When issues arise while working with the Ingress Controller, the gateway and controller logs are usually the best place to start, as they often reveal the underlying issue quickly.

This document covers common issues you may encounter and provides practical guidance to troubleshoot and resolve them efficiently.

GatewayProxy Missing or Misconfigured

GatewayProxy defines the Control Plane endpoint and Admin API key used by the Ingress Controller to communicate with the Control Plane. If your resources are not being synchronized to the gateway, a common cause is that the GatewayProxy resource is either missing or incorrectly configured.

Verify that the GatewayProxy resource exists and is created in the correct namespace:

kubectl get gatewayproxy --all-namespaces

If GatewayProxy exists, review the GatewayProxy configuration:

kubectl describe gatewayproxy <gatewayproxy-name> -n <namespace>

IngressClassName Missing or Unspecified

For the following resources, the Ingress Controller only processes them when the ingressClassName matches the controller’s configured IngressClass:

• Ingress
• ApisixRoute
• ApisixUpstream
• ApisixTLS
• ApisixPluginConfig
• ApisixGlobalRule
• ApisixConsumer

If the ingressClassName is missing or specified incorrectly, the resource will not be synchronized to the gateway.

ingress annotation

For Ingress resources, the controller first checks spec.ingressClassName. If it is not set, it falls back to the kubernetes.io/ingress.class annotation, which is supported for backward compatibility.

Verify which IngressClass resources (cluster-scoped) exist:

kubectl get ingressclass

Review the IngressClass configuration to ensure it references the intended Ingress Controller:

kubectl describe ingressclass <ingressclass-name>

Verify that your resources have specified the correct ingressClassName, for instance:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

etcd Failures

When running APISIX on Kubernetes in a deployment mode that uses etcd as the configuration backend, you may encounter etcd pods that repeatedly restart (CrashLoopBackOff) or fail to reach a healthy state. Hosting etcd as a Kubernetes StatefulSet can introduce operational challenges: pods may crash when they restart, scale, or lose access to persistent storage, and cluster membership can become unstable.

Because of these risks, it is generally recommended to run APISIX in standalone mode, which does not require etcd. This mode simplifies the deployment and avoids the complexity of managing an etcd cluster inside Kubernetes.

For deployments that truly require etcd, it is generally more reliable to host the etcd cluster on separate virtual machines or dedicated infrastructure outside of Kubernetes.

Route Priority Across Resources

A higher value indicates a higher route priority. When multiple resource types are used together (Ingress, HTTPRoute, and APISIXRoute), routing behavior may be affected by differences in how route priorities are assigned and evaluated.

The following explains how priority is handled for each resource type:

• Ingress: Does not support explicit route priorities. Routes generated from Ingress resources are assigned a default priority of 0, which is generally the lowest.
• HTTPRoute: Uses a dynamically computed 38-bit priority. Because this value is derived from multiple attributes, the resulting priority is not fixed and cannot be reliably predicted.
• APISIXRoute: Allows explicit configuration of route priority. To guarantee that an APISIXRoute is matched before an HTTPRoute, its priority must be set higher than 274,877,906,943 (2^38 − 1).

HTTPRoute Filter and PluginConfig

When both HTTPRoute filters and PluginConfig CRDs are applied to the same route, you may experience unexpected plugin behavior. Understanding how these interact helps avoid configuration conflicts.

The Ingress Controller maps built-in Gateway API HTTPRoute filters to specific plugins:

• RequestHeaderModifier maps to proxy-rewrite
• RequestRedirect maps to redirect
• RequestMirror maps to proxy-mirror
• URLRewrite maps to proxy-rewrite
• ResponseHeaderModifier maps to response-rewrite
• CORS maps to cors
• ExtensionRef maps to a user-defined plugin reference

When both filters and a PluginConfig CRD are applied:

• If filters are applied first, PluginConfig overrides any overlapping plugin settings.
• If PluginConfig is applied first, filters merge with PluginConfig settings, and overlapping fields from filters take precedence.

Gateway API Routes Return 404 After Upgrade

After upgrading to APISIX Ingress Controller 2.1.0, Gateway API HTTPRoute or GRPCRoute resources may return 404. This can happen when Gateway listener ports do not match the ports that APISIX or API7 Gateway actually listens on.

In the default listener_port_match_mode: auto mode, the Ingress Controller may inject a server_port route variable from the matched Gateway listener ports. The server_port variable is evaluated by the data plane against its actual listening port, such as 9080 or 9443. If the Gateway listener uses 80 or 443 but the gateway Service maps those ports to 9080 or 9443, the route may not match.

To resolve the issue, use one of the following approaches:

• Set listener_port_match_mode to "off" in the controller configuration to disable server_port route-var injection.
• Configure APISIX or API7 Gateway to listen on the same ports declared in the Gateway listeners.