What is Kubernetes 502 Bad Gateway?
A 502 Bad Gateway error is an 5xx server error that indicates a server received an invalid response from a proxy or gateway server. In Kubernetes, this can happen when a client attempts to access an application deployed within a pod, but one of the servers responsible for relaying the request the Ingress, the Service, or the pod itself — is not available/accessible or not properly configured.
In our last post we have seen how to troubleshoot 503 service unavailable error, in this will see how to troubleshoot 502 bad gateway messages. Even 502 error also difficult to diagnose and resolve in Kubernetes, because they can involve one or more moving parts in your Kubernetes cluster. In this post, let’s check the steps that can help you debug the issue and identify the most common causes. Please be noted, as like all the issues, it will be depending on the complexity of your setup and the components failing or misconfigured. For best troubleshooting any issue, it is important that, you should have good understanding on your environment.
How to Troubleshoot 502 Bad Gateway in Kubernetes
Consider a scenario in which you map a Service to a container within a pod, and the client is attempting to access an application running on that container. This creates several points of failure:
- The pod
- The container
- Network ports exposed on the container
- The Service
- The Ingress
Here are the basic steps to debugging a 502 error in a Kubernetes pod, which aims to identify a problem in one or more of these components.
1. Check if the Pod and Containers is Running
If the pod or one of its containers did not start, this could result in a 502 error to clients accessing an application running in the pod.
To identify if this is the case, run this command:
# kubectl get pods
- If the entire pod or the required containers are not running — restart the pod or force Kubernetes to reschedule it.
- If they are running — proceed to the next step.
2. Check if Containers are Listening on the Required Port
Identify what address and port the Service is attempting to access. Run the following command and examine the output to see whether the container running the application has an open port and is listening on the expected address:
# kubectl describe pod [pod-name]
- If you see the container is not listening on the port — check the pod specification. If the pod specification does not specify the port in the
spec:containers:portsfield, add it. If it does specify the port, but it was not opened for some reason, restart the pod.
- If the container is listening on the required post — proceed to the next step.
3. Check if the Service Is Active
If the pod and containers are running and listening on the correct port, the next step is to identify if the Service accessed by the client is active. Note there might be different Services mapped to different containers on the pod.
# kubectl get svc
- If you don’t see the required Service in the list — create it using the
- If you see it in the list — proceed to the next step.