Skip to content

Troubleshooting

Common issues and solutions for Playpen.

Prerequisites issues

kubectl not found

Problem: kubectl: command not found

Solution: - Install kubectl: https://kubernetes.io/docs/tasks/tools/ - Verify: kubectl version --client

Docker daemon not running

Problem: Cannot connect to the Docker daemon

Solution: - Start Docker Desktop - Verify: docker ps

Kubernetes cluster not available

Problem: The connection to the server ... was refused

Solution: - Enable Kubernetes in Docker Desktop settings - Or start kind/minikube: kind create cluster or minikube start - Verify: kubectl cluster-info

Installation issues

Storage class not found

Problem: storageclass.storage.k8s.io "local-path" not found

Solution: 

# Install local-path-provisioner
kubectl apply -f infra/k8s/local-path-provisioner.yaml

Pods stuck in Pending

Problem: Pods remain in Pending state

Solution: 

# Check pod events
kubectl describe pod <pod-name> -n playpen-platform

# Common causes:
# - Insufficient resources (CPU/memory)
# - Storage class not available
# - Node selector issues

Nexus takes too long to start

Problem: Nexus pod not ready after 10+ minutes

Solution: 

# Check logs
kubectl logs -n playpen-platform deployment/nexus

# Increase resources in nexus-values.yaml

Jenkins agents not connecting

Problem: Jenkins cannot create agent pods

Solution: 1. Verify Kubernetes cloud configuration in Jenkins 2. Check service account permissions: 

kubectl get rolebinding jenkins-agent -n playpen-platform
3. Verify Jenkins can access Kubernetes API

Service access issues

Port forward fails

Problem: Unable to listen on port: listen tcp4 0.0.0.0:8080: bind: address already in use

Solution: 

# Find process using port
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

# Kill process or use different port
kubectl port-forward -n playpen-platform svc/jenkins 8081:8080

Cannot access service via port-forward

Problem: Service not responding after port-forward

Solution: 1. Verify service is running: 

kubectl get pods -n playpen-platform
2. Check service endpoints: 
kubectl get endpoints -n playpen-platform
3. Check service logs: 
kubectl logs -n playpen-platform deployment/<service-name>

Configuration issues

Nexus admin password not found

Problem: Cannot find admin password file

Solution: 

# Wait for Nexus to initialize (may take 5-10 minutes)
kubectl wait --for=condition=ready pod -l app=nexus -n playpen-platform --timeout=600s

# Get password
kubectl exec -n playpen-platform deployment/nexus -- cat /nexus-data/admin.password

Dex token issuance fails

Problem: Cannot get OIDC token from Dex

Solution: 1. Verify Dex is running: 

kubectl get pods -n playpen-platform -l app=dex
2. Check Dex health: 
kubectl exec -n playpen-platform deployment/dex -- wget -q -O- http://localhost:5556/healthz
3. Verify client credentials: 
kubectl get secret dex-credentials -n playpen-platform -o yaml

PostgreSQL connection refused

Problem: Cannot connect to PostgreSQL

Solution: 1. Verify PostgreSQL is running: 

kubectl get pods -n playpen-platform -l app=postgres
2. Check connection string 3. Test connection from within cluster

Resource issues

Out of memory

Problem: Pods killed due to OOM

Solution: 1. Check resource limits: 

kubectl describe pod <pod-name> -n playpen-platform
2. Increase limits in deployment manifests 3. Add more resources to cluster

Disk space full

Problem: Persistent volumes running out of space

Solution: 

# Check PVC usage
kubectl get pvc -n playpen-platform

# Expand PVC (if supported)
kubectl patch pvc <pvc-name> -n playpen-platform -p '{"spec":{"resources":{"requests":{"storage":"50Gi"}}}}'

Jenkins issues

Kaniko build fails

Problem: Kaniko executor fails with permission errors

Solution: 1. Verify service account has correct permissions 2. Check Kaniko executor command 3. Ensure Nexus Docker registry is accessible

Pipeline cannot access Nexus

Problem: Cannot upload artifacts to Nexus

Solution: 1. Verify Nexus credentials in Jenkins 2. Check Nexus repository exists and is accessible 3. Test Nexus connection

Getting help

If issues persist:

  1. Check service logs: 
    kubectl logs -n playpen-platform deployment/<service-name>
  2. Check pod events: 
    kubectl describe pod <pod-name> -n playpen-platform
  3. Verify installation: 
    make verify

Next steps