Fix: AIC Can't Find Default GatewayProxy In APISIX

Dec 1, 2025 by Alex Johnson 51 views

Troubleshooting: APISIX Ingress Controller (AIC) Failing to Discover Default GatewayProxy

Introduction

When deploying APISIX in API-driven mode, a common issue arises where the APISIX Ingress Controller (AIC) fails to discover the default GatewayProxy created by the Helm chart. This article delves into the root causes, troubleshooting steps, and solutions for this problem. If you're encountering errors such as GatewayProxy.apisix.apache.org "apisix-config" not found, or seeing 404 errors when accessing the APISIX admin API, you're in the right place. Let's dive into how to resolve this.

Understanding the Problem: Why AIC Can't Find GatewayProxy

The APISIX Ingress Controller (AIC) acts as a bridge between Kubernetes Ingress resources and the APISIX API gateway. It dynamically configures APISIX based on the Ingress, Service, and other Kubernetes resources. The GatewayProxy resource is crucial for AIC as it defines the connection parameters to the APISIX control plane. When AIC cannot discover the GatewayProxy, it fails to synchronize configurations, leading to routes and upstreams not being properly registered. Several factors can cause this issue, including misconfigurations in the Helm chart values, incorrect namespace settings, or timing issues during deployment.

Diagnosing the Issue: Steps to Identify the Root Cause

To effectively resolve the issue, a systematic approach to diagnosis is essential. Start by verifying the GatewayProxy resource itself. Use the command kubectl get gatewayproxies -n apisix to confirm that the apisix-config GatewayProxy has been created in the correct namespace. If the resource is missing, it indicates a problem with the Helm chart deployment or the createDefault setting.

Next, examine the AIC logs for error messages. The logs often provide valuable clues about the failure. Look for errors such as failed to get gateway proxy: GatewayProxy.apisix.apache.org "apisix-config" not found. This specific error confirms that the AIC cannot locate the GatewayProxy resource. Also, check the AIC logs for any issues related to connecting to the APISIX admin API. A successful connection is crucial for AIC to synchronize configurations.

Ensure that the namespace specified in the GatewayProxy configuration matches the namespace where APISIX and AIC are deployed. Namespace mismatches are a common cause of discovery issues. Verify that the apisix.adminService.namespace setting in the Helm values is correctly configured. If there are discrepancies, it could prevent AIC from communicating with the APISIX admin service.

Common Causes and Solutions

1. Incorrect Helm Chart Configuration

A common pitfall is misconfiguring the Helm chart values, particularly the ingress-controller.gatewayProxy.createDefault setting. Ensure this setting is set to true to automatically create the default GatewayProxy. Also, verify that the apisix.adminService.namespace setting matches the namespace where APISIX is deployed. An incorrect namespace will prevent AIC from discovering the GatewayProxy.

To rectify this, review your values.yaml file or the Helm install command. Ensure that the following settings are correctly configured:

ingress-controller:
  gatewayProxy:
    createDefault: true
  apisix:
    adminService:
      namespace: apisix

If changes are made, redeploy APISIX using Helm to apply the updated configuration. This ensures that the AIC can correctly discover the GatewayProxy and synchronize configurations.

2. Namespace Mismatch

Another frequent issue is a mismatch between the namespace of the GatewayProxy and the AIC. The AIC must be deployed in the same namespace as the GatewayProxy to discover it. If the GatewayProxy is created in the apisix namespace, the AIC should also be deployed in the apisix namespace.

To address this, verify the namespace configurations for both APISIX and the AIC. Use the command kubectl get deployments -n <namespace> to check the namespace of the AIC deployment. If the namespaces do not match, redeploy the AIC in the correct namespace. This ensures that the AIC can locate the GatewayProxy and establish a connection with the APISIX admin API.

3. Timing Issues During Deployment

In some cases, the AIC might start before the GatewayProxy is fully initialized. This can lead to the AIC failing to discover the GatewayProxy initially. To mitigate this, ensure that the GatewayProxy is fully running before the AIC attempts to connect. You can achieve this by adding a dependency or a startup probe to the AIC deployment.

To implement a startup probe, add the following configuration to the AIC deployment:

startupProbe:
  httpGet:
    path: /healthz
    port: 10254
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 30

This probe checks the health endpoint of the AIC and ensures that it is running before allowing traffic. Adjust the initialDelaySeconds, periodSeconds, and failureThreshold parameters as needed for your environment. This ensures that the AIC waits for the GatewayProxy to be ready before attempting to connect.

4. RBAC Permissions

Ensure that the AIC has the necessary RBAC (Role-Based Access Control) permissions to access GatewayProxy resources. The AIC service account needs permissions to get, list, and watch GatewayProxy resources in the specified namespace. If the permissions are insufficient, the AIC will fail to discover the GatewayProxy.

To verify and update RBAC permissions, check the roles and role bindings associated with the AIC service account. Ensure that the service account has the following permissions:

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: apisix-ingress-controller
rules:
- apiGroups:
  - apisix.apache.org
  resources:
  - gatewayproxies
  verbs:
  - get
  - list
  - watch

Apply this ClusterRole and create a corresponding RoleBinding to grant the permissions to the AIC service account. This ensures that the AIC has the necessary permissions to access GatewayProxy resources.

Detailed Steps to Resolve the Issue

To provide a clearer understanding of the resolution process, here's a step-by-step guide:

Verify GatewayProxy Existence: Run kubectl get gatewayproxies -n apisix to confirm the GatewayProxy resource exists.
Check AIC Logs: Examine the AIC logs using kubectl logs -n apisix <aic-pod-name> for any error messages.
Review Helm Configuration: Inspect your Helm values.yaml file to ensure ingress-controller.gatewayProxy.createDefault is set to true and apisix.adminService.namespace is correct.
Confirm Namespace Alignment: Ensure the AIC and GatewayProxy are deployed in the same namespace.
RBAC Permissions Check: Verify the AIC service account has the necessary RBAC permissions.
Implement Startup Probe: Add a startup probe to the AIC deployment to handle timing issues.

By following these steps, you can systematically identify and address the root cause of the AIC failing to discover the default GatewayProxy.

Practical Examples and Scenarios

To further illustrate the solutions, let's consider a few practical scenarios:

Scenario 1: Missing GatewayProxy Resource

If the kubectl get gatewayproxies -n apisix command returns no resources, it indicates that the GatewayProxy was not created. This typically occurs when the ingress-controller.gatewayProxy.createDefault setting is set to false or is missing from the Helm values. To resolve this, update your values.yaml file and set ingress-controller.gatewayProxy.createDefault to true. Then, upgrade your Helm release using helm upgrade --install apisix apisix/apisix -n apisix -f values.yaml.

Scenario 2: Namespace Mismatch

Suppose the GatewayProxy is in the apisix namespace, but the AIC is deployed in the default namespace. The AIC logs will show errors like failed to get gateway proxy: GatewayProxy.apisix.apache.org "apisix-config" not found. To fix this, redeploy the AIC in the apisix namespace by modifying the AIC deployment YAML or Helm values accordingly.

Scenario 3: Insufficient RBAC Permissions

If the AIC logs show errors related to unauthorized access, it suggests an RBAC issue. Ensure that the AIC service account has the necessary permissions to get, list, and watch GatewayProxy resources. Create or modify ClusterRoles and RoleBindings to grant these permissions to the AIC service account.

Conclusion

Successfully deploying APISIX with the Ingress Controller in API-driven mode requires careful configuration and troubleshooting. The issue of the AIC failing to discover the default GatewayProxy is a common hurdle, but it can be overcome with a systematic approach. By verifying configurations, examining logs, and ensuring proper RBAC permissions, you can resolve this problem and ensure seamless integration between Kubernetes and APISIX. Remember to double-check your Helm chart values, namespace settings, and AIC deployment configurations to maintain a stable and functional APISIX Ingress Controller.

For more in-depth information and community support, consider visiting the official Apache APISIX website. There, you can find comprehensive documentation, tutorials, and community forums to help you further troubleshoot and optimize your APISIX deployments.