Troubleshooting Kubernetes Deployments & Services: A Practical Guide

Kubernetes is a powerful platform for deploying and managing containerized applications, but even experienced teams face challenges when dealing with Pods, Deployments, and Services. Whether you’re running an eCommerce platform, SaaS application, financial services software, or an AI-powered analytics tool, ensuring smooth deployment and availability is crucial.

In this guide, we’ll walk through a real-world troubleshooting approach to fixing common Kubernetes issues, helping you keep your application running efficiently.

🚀 The Use Case: Deploying a Cloud-Native Application in Kubernetes

Imagine your team is deploying a cloud-native application with the following setup:

• Two Deployments (one for the backend API, another for the frontend UI)
• One Service to expose the application to users

However, the team encounters three major issues:

1. Pods not starting due to image issues
2. The Service is not accessible
3. Deployment struggling with resource limitations

To fix these, we will take a systematic troubleshooting approach and ensure that the application remains stable and performant.

🛠️ Step 1: Setting Up the Kubernetes Environment

Before troubleshooting, let’s verify the cluster setup and ensure the correct namespace is used.

✅ Check the Cluster & Nodes

kubectl cluster-info
kubectl get nodes

Ensure that all nodes are in a Ready state.

✅ Set Up Namespace (if needed)

kubectl create namespace my-application
kubectl config set-context --current --namespace=my-application

✅ Check Manifests for Deployments & Services

Navigate to the directory where Kubernetes manifests are stored:

ls manifests/

Ensure that deployments.yaml and service.yaml exist.

🛠️ Step 2: Troubleshooting Deployment Image Issues

Problem: The Pods aren’t starting, and kubectl get pods shows ImagePullBackOff or ErrImagePull.

✅ Check Pod Status

kubectl get pods -n my-application

If you see ImagePullBackOff, it indicates an issue with the container image.

✅ Investigate Deployment Details

kubectl describe deployment <deployment-name> -n my-application

Look for errors like:

• Incorrect image name
• Authentication failure with the image registry

✅ Verify & Pull Image Manually

docker pull <image-name>:<tag>

If the image doesn’t exist, update your deployments.yaml file:

containers:
- name: my-app
  image: correct-registry/my-app:latest

✅ Apply the Fix

kubectl apply -f manifests/deployments.yaml -n my-application

Restart the Pods if necessary:

kubectl rollout restart deployment <deployment-name> -n my-application

🛠️ Step 3: Fixing Service Configuration Issues

Problem: The Service is running, but the app is not accessible.

✅ Check Service Status

kubectl get svc -n my-application

✅ Inspect Service Configuration

kubectl describe service <service-name> -n my-application

Look for mismatched port configurations.

✅ Fix Port Mismatch in service.yaml

ports:
  - port: 80
    targetPort: 8080

Ensure targetPort matches the container’s containerPort.

✅ Verify Service Endpoints

kubectl get endpoints <service-name> -n my-application

If no endpoints are listed, it means no Pods are connected to the Service.

✅ Test Connectivity

kubectl port-forward svc/<service-name> 8080:80 -n my-application
curl http://localhost:8080

✅ Restart Pods (If Needed)

kubectl rollout restart deployment <deployment-name> -n my-application

🛠️ Step 4: Optimizing Deployment Resource Usage

Problem: Deployment is running, but it’s struggling with high CPU/memory usage.

✅ Check Pod Resource Usage

kubectl top pod -n my-application

✅ Inspect Deployment Resource Limits

kubectl describe deployment <deployment-name> -n my-application

Look for OOMKills (Out of Memory errors) or high CPU usage.

✅ Define Resource Requests & Limits

In deployments.yaml, add resource constraints:

resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

✅ Apply Changes & Monitor Performance

kubectl apply -f manifests/deployments.yaml -n my-application
kubectl get pods -w -n my-application

✅ Scale Deployment If Needed

kubectl scale deployment <deployment-name> --replicas=3 -n my-application

📌 Final Validation: Ensuring Stability

After applying fixes, check everything is working as expected.

1. Verify All Resources Are Healthy

   kubectl get all -n my-application
   

2. Monitor Logs for Any Remaining Issues

   kubectl logs -f <pod-name> -n my-application
   

3. Test Application Availability

   kubectl port-forward svc/<service-name> 8080:80 -n my-application
   curl http://localhost:8080
   

4. Monitor Pods and Services

   kubectl get pods -w -n my-application
   

🚀 Key Takeaways

✅ Check Pod & Deployment issues: Ensure container images are correctly specified and available.
✅ Validate Service configuration: Match ports, verify endpoints, and test connectivity.
✅ Monitor resource usage: Set proper CPU and memory limits to prevent failures.
✅ Use logs & events for insights: kubectl logs and kubectl describe provide crucial debugging info.
✅ Scale when needed: Use horizontal scaling (kubectl scale) to improve reliability.

By following these structured troubleshooting techniques, you can ensure your Kubernetes-based application runs smoothly, whether it’s an eCommerce store, a financial analytics tool, a content management system, or an AI-powered SaaS platform. 🚀

Ref : https://pineave-newsletter.beehiiv.com/p/troubleshooting-kubernetes-deployments-services-a-practical-guide