This project is in the process of being donated to the CNCF and is not affiliated with the Kubernetes project.
Debug your setup

Debug your setup

Use built-in tools to troubleshoot issues in your kgateway setup.

Kgateway is based on Envoy proxy. If you experience issues in your environment, such as policies that are not applied or traffic that is not routed correctly, in a lot of cases, these errors can be observed at the proxy. In this guide you learn how to use the kgateway and Envoy debugging tools to troubleshoot misconfigurations on the gateway.

Debug your gateway setup

  1. Make sure that the kgateway control plane and gateway proxies are running. For any pod that is not running, describe the pod for more details.

    kubectl get pods -n kgateway-system
  2. Check the HTTPRoutes for the status of the route and any attached policies.

    kubectl get httproute <name> -n <namespace>
  3. Access the debugging interface of your gateway proxy on your localhost. Configuration might be missing on the gateway or might be applied to the wrong route. For example, if you apply multiple policies to the same route by using the targetRefs section, only the oldest policy is applied. The newer policy configuration might be ignored and not applied to the gateway.

    kubectl port-forward deploy/gloo-proxy-http -n kgateway-system 19000 &  
    Figure: Debugging interface of the gateway proxy.

    Common endpoints that can help troubleshoot your setup further, include:

    Endpoint Description
    config_dump Get the configuration that is available in the Envoy proxy. Any kgateway resources that you create are translated in to Envoy configuration. Depending on whether or not you enabled resource validation, you might have applied invalid configuration that is rejected Envoy. You can also use glooctl proxy dump to get the Envoy proxy configuration.
    listeners See the listeners that are configured on your gateway.
    logging Review the log level that is set for each component.
    stats/prometheus View metrics that Envoy emitted and sent to the built-in Prometheus instance.
  4. Review the logs for each component. Each component logs the sync loops that it runs, such as syncing with various environment signals like the Kubernetes API. You can fetch the latest logs for all the components with the following command.

    # kgateway control plane
    kubectl logs -n kgateway-system deployment/kgateway
    
    # Replace $GATEWAY_NAME with the name of your gateway.
    kubectl logs -n kgateway-system deployment/gloo-proxy-$GATEWAY_NAME