Troubleshooting

This guide helps you diagnose and resolve common issues encountered during QMigrator deployment and operation on Kubernetes. Follow the steps in each section to identify and fix problems related to Gateway configuration, routing, TLS certificates, and application access.

Common Issues

Gateway Not Getting External IP

Symptom: The Gateway resource is created but doesn't receive an external IP address or hostname, preventing external access to your application.

Possible Causes: - Gateway Controller is not running or misconfigured - Cloud provider load balancer provisioning failed - Insufficient permissions or quota limits - Gateway class name mismatch

Diagnosis:

Check the Gateway status and events:

kubectl describe gateway qmig-gateway -n <namespace>

Look for error messages in the Events section, such as:

• "Failed to assign to load balancer"
• "No addresses have been assigned to the Gateway"
• "Gateway class not found"

Verify the Gateway Controller is running:

kubectl get pods -n nginx-gateway  # or your controller namespace

All controller pods should be in Running state.

Resolution:

1. If Gateway Controller is not running:

   # Check controller logs
   kubectl logs -n nginx-gateway -l app.kubernetes.io/name=nginx-gateway-fabric
   
   # Restart the controller
   kubectl rollout restart deployment -n nginx-gateway
   

2. If gateway class name is incorrect:

   # List available gateway classes
   kubectl get gatewayclasses
   
   # Update your values.yaml with the correct class name
   gateway.gatewayClassName: "correct-class-name"
   

3. For cloud-specific issues:

   • AWS: Check EC2 load balancer limits and IAM permissions
   • Azure: Verify AKS has permissions to create public IPs
   • GCP: Check GKE service account permissions

4. Check cloud provider load balancer:

   # Get the service created by the gateway
   kubectl get svc -n <namespace>
   
   # Describe the load balancer service
   kubectl describe svc <gateway-service-name> -n <namespace>
   

HTTPRoute Not Working

Symptom: Gateway has an external IP, but requests to the application fail with 404, 502, or timeout errors.

Possible Causes: - Backend services are not running - HTTPRoute configuration errors - Service name or port mismatch - Parent reference (gateway listener) mismatch - Hostname not configured properly

Diagnosis:

1. Verify backend services are running:

   kubectl get services -n <namespace>
   kubectl get pods -n <namespace>
   

   Ensure all application pods are in Running state and services have valid endpoints.

2. Check HTTPRoute status and configuration:

   kubectl describe httproute -n <namespace>
   

   Look for:
   • Route status should be Accepted
   • Parent references should match your Gateway
   • Backend references should show valid services

3. Check service endpoints:

   kubectl get endpoints <service-name> -n <namespace>
   

   If endpoints are empty, the service selector doesn't match any pods.

Resolution:

1. If pods are not running:

   # Check pod logs for errors
   kubectl logs <pod-name> -n <namespace>
   
   # Check pod events
   kubectl describe pod <pod-name> -n <namespace>
   

2. If service names don't match: Update your HTTPRoute to use correct service names:

   backendRefs:
   - name: qmig-app  # Must match actual service name
     port: 4200
   

3. If gateway listener names don't match:

   # Check gateway listener names
   kubectl get gateway qmig-gateway -n <namespace> -o yaml
   
   # Ensure HTTPRoute parentRefs match listener names
   parentRefs:
   - name: qmig-gateway
     sectionName: http  # Must match gateway listener name
   

4. Test connectivity from within the cluster:

   # Create a test pod
   kubectl run test --image=curlimages/curl -it --rm -- sh
   
   # Inside the pod, test the service
   curl http://<service-name>:<port>
   

5. Check HTTPRoute hostname configuration:

   # Verify DNS resolution
   nslookup your-domain.com
   
   # Test with curl using Host header
   curl -H "Host: your-domain.com" http://<gateway-external-ip>
   

TLS Certificate Issues

Symptom: HTTPS connections fail with certificate errors, or certificates are not being issued automatically.

Possible Causes: - cert-manager is not running or misconfigured - Certificate Issuer not properly configured - DNS validation failing for Let's Encrypt - Gateway annotation missing or incorrect

Diagnosis:

1. Check certificate status:

   kubectl get certificate -n <namespace>
   

   Look for certificate status - should be Ready=True.

2. Get detailed certificate information:

   kubectl describe certificate -n <namespace>
   

   Check the Events section for error messages like:
   • "Failed to create Order"
   • "Waiting for HTTP-01 challenge propagation"
   • "Failed to determine a valid solver configuration"

3. Verify cert-manager is running:

   kubectl get pods -n cert-manager
   

   All cert-manager pods should be in Running state.

4. Check certificate request:

   kubectl get certificaterequest -n <namespace>
   kubectl describe certificaterequest -n <namespace>
   

Resolution:

1. If certificate issuer is missing or incorrect:

   # Check issuers
   kubectl get issuer -n <namespace>
   kubectl get clusterissuer
   
   # Verify gateway has correct annotation
   kubectl get gateway qmig-gateway -n <namespace> -o yaml | grep annotations -A 5
   

   Ensure annotation matches issuer type:

   # For ClusterIssuer
   cert-manager.io/cluster-issuer: letsencrypt
   
   # For Issuer
   cert-manager.io/issuer: letsencrypt
   

2. If HTTP-01 challenge is failing:

   # Check challenge status
   kubectl get challenges -n <namespace>
   kubectl describe challenge -n <namespace>
   

   Common fixes:
   • Ensure HTTPRoute is configured for HTTP (port 80) access
   • Verify domain DNS points to gateway external IP
   • Check firewall rules allow HTTP traffic

3. Force certificate renewal:

   # Delete the certificate to trigger re-issuance
   kubectl delete certificate <cert-name> -n <namespace>
   
   # Watch for new certificate creation
   kubectl get certificate -n <namespace> -w
   

4. Check cert-manager logs for detailed errors:

   kubectl logs -n cert-manager -l app=cert-manager --tail=100
   

Invalid Registry Credentials

Issue: helm registry login fails with authentication error

Resolution:

1. Verify credentials are copied correctly (no extra spaces)
2. Click Show button to reveal password instead of copying masked value
3. Contact support if issue persists

License Key Not Working

Issue: License key is rejected during application login

Resolution:

1. Ensure license has not expired (check Expiration Date)
2. Verify key is copied completely without line breaks
3. Ensure correct license file uploaded
4. Contact support for license renewal or validation