headlamp-polaris-plugin/docs/troubleshooting/network-problems.md

Network Problems

Troubleshooting network connectivity issues for the Headlamp Polaris Plugin.

Overview

The plugin accesses Polaris through the Kubernetes service proxy. Network issues can occur at multiple points in this chain:

Headlamp Pod → K8s API Server → Polaris Dashboard Service

Common Issues

NetworkPolicy Blocking Access

Symptom: Timeout or connection errors despite correct RBAC

Cause: NetworkPolicy in polaris namespace blocking API server ingress

Solution:

Allow ingress from the Kubernetes API server to Polaris dashboard:

---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-apiserver-to-polaris
  namespace: polaris
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: polaris
      app.kubernetes.io/component: dashboard
  policyTypes:
    - Ingress
  ingress:
    # Allow from API server
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: kube-system
        - podSelector:
            matchLabels:
              component: kube-apiserver
      ports:
        - protocol: TCP
          port: 80

Note: The API server performs the proxy hop, not the Headlamp pod directly.

Test Network Connectivity

# 1. Test service proxy endpoint
kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json

# If successful: JSON output
# If failed: Check NetworkPolicies and service status

# 2. Check NetworkPolicies
kubectl -n polaris get networkpolicy

# 3. Test direct service access (from within cluster)
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
  curl http://polaris-dashboard.polaris/results.json

# If this works but service proxy doesn't, check API server network access

CORS Issues (Custom URL)

Symptom: Error when using custom Polaris URL in settings

Cause: CORS not configured on external Polaris deployment

Solution:

Configure Polaris dashboard to allow Headlamp origin:

# Polaris Helm values
dashboard:
  enabled: true
  env:
    - name: CORS_ALLOWED_ORIGINS
      value: "https://headlamp.example.com"

Test CORS headers:

curl -v -H "Origin: https://headlamp.example.com" \
  https://my-polaris.example.com/results.json

# Check for:
# Access-Control-Allow-Origin: https://headlamp.example.com

References

• Kubernetes NetworkPolicies
• Service Proxy