Skip to main content

Troubleshooting Guide

This guide covers common issues when working with Platform Applications and how to resolve them.

What You'll Learn​

  • How to diagnose PlatformApplication issues
  • Common pod, networking, and configuration problems
  • Useful kubectl commands for debugging
  • How to check operator and external secrets status

Platform Application Issues​

Platform Application Not Ready​

Check the status conditions:

kubectl describe platformapplication <name> -n <namespace>

Look for the Conditions section and any error messages in Events.

Common issues:

  • Image pull errors
  • Invalid configuration
  • Missing secrets

Platform Application Not Creating Resources​

# Check Platform Application status
kubectl describe platformapplication <name> -n <namespace>

# Look for conditions and events

Common causes:

  • Image pull errors (check image name and registry access)
  • Invalid configuration in the spec
  • Missing or misconfigured secrets
  • Operator not running or unhealthy

Pod and Deployment Issues​

Pods Not Starting​

Check pod events:

kubectl describe pod <pod-name> -n <namespace>

Check logs:

kubectl logs -n <namespace> <pod-name>

Common issues:

  • Image not found (verify image name and registry access)
  • Readiness probe failing (check container logs and probe configuration)
  • Resource constraints (check cluster capacity)
  • Missing secrets or config

Cannot Access Application​

Ensure port-forward is running:

kubectl port-forward -n <namespace> svc/<service-name> 8080:8080

Check service exists:

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

Ingress and Networking Issues​

Application Not Accessible Externally​

  1. Check HTTPRoute/VirtualService: Ensure routing rules were created

    kubectl get httproute -n <namespace>
    # or
    kubectl get virtualservice -n <namespace>

  2. Check Gateway: Verify the gateway is running and healthy

    kubectl get gateway -n <namespace>

  3. Check DNS: Ensure DNS is resolving to the correct load balancer

    nslookup <your-hostname>

  4. Check Firewall: Verify firewall rules allow traffic to the ingress gateway

404 Not Found​

  • Verify the path configuration matches your application's routes
  • Check that the service is routing to the correct port
  • Ensure the HTTPRoute/VirtualService is correctly configured
kubectl describe httproute <name> -n <namespace>
# or
kubectl describe virtualservice <name> -n <namespace>

TLS/Certificate Errors​

The platform automatically manages TLS certificates.

Check certificate status:

kubectl get certificate -n <namespace>

Check cert-manager logs if certificate provisioning fails:

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

Common issues:

  • DNS not correctly configured (required for Let's Encrypt)
  • Certificate not yet issued (can take a few minutes)
  • Invalid hostname configuration

DNS Not Resolving​

  • Wait for DNS propagation (can take 5-10 minutes)
  • Check External DNS logs: 
    kubectl logs -n external-dns -l app=external-dns
  • Verify the hostname is correctly configured in the Platform Application status

Configuration Issues​

Config Not Appearing in Pod​

  1. Check ConfigMap: Verify the ConfigMap was created

    kubectl get configmap -n <namespace> -l p6m.dev/app=<app-name>
    kubectl describe configmap -n <namespace> -l p6m.dev/app=<app-name>

  2. Check Pod Events: Look for mount failures

    kubectl describe pod <pod-name> -n <namespace>

  3. Restart Pods: Config changes require pod restart

    kubectl rollout restart deployment <deployment-name> -n <namespace>

Wrong Config Values​

  • Verify you applied the correct environment's manifest
  • Check for typos in the configuration or patch files
  • Ensure Kustomize is merging patches correctly: kubectl kustomize path/to/env

ConfigMap Exists But Not in Pods​

Check that the Platform Application is correctly configured:

kubectl describe platformapplication <name> -n <namespace>

Look for any error messages in the status conditions.

Secret Issues​

Secret Not Syncing​

  1. Check ExternalSecret status:

    kubectl describe externalsecret <name> -n <namespace>

    Look for error messages in Events.

  2. Verify secret exists in cloud:

    # AWS
    aws secretsmanager describe-secret --secret-id <secret-name>

    # Azure
    az keyvault secret show --vault-name <vault-name> --name <secret-name>

  3. Check IAM/RBAC permissions:

    • Ensure the service account has permission to read the secret
    • Check CloudWatch Logs (AWS) or Log Analytics (Azure) for access denied errors

  4. Check External Secrets Operator logs:

    kubectl logs -n external-secrets-system -l app.kubernetes.io/name=external-secrets

Common issues:

  • Secret doesn't exist in cloud secret store
  • IAM/RBAC permissions not configured
  • Invalid secret name (must match exactly)
  • Wrong cloud account or region

Secret Exists But Not in Pod​

  1. Restart the pod:

    kubectl rollout restart deployment -n <namespace>

  2. Check secret mount:

    kubectl describe pod -n <namespace>

    Look for the secret in the "Mounts" or "Environment" section.

Wrong Secret Values​

  • Verify you're reading from the correct cloud secret (name matches exactly)
  • Check for typos in secret names
  • Ensure the secret is in the correct cloud account/region
  • Verify the secret format is correct (JSON key-value pairs)

Diagnostic Commands​

Check All Platform Application Resources​

# Get Platform Application status
kubectl get platformapplication <name> -n <namespace>

# Check overall status
kubectl get platformapplication <name> -n <namespace> -o jsonpath='{.status.phase}'

# Check managed resources
kubectl get platformapplication <name> -n <namespace> -o jsonpath='{.status.managedResources}' | jq

# Full details
kubectl describe platformapplication <name> -n <namespace>

Check Pods​

# List pods
kubectl get pods -n <namespace> -l p6m.dev/app=<app-name>

# Pod details
kubectl describe pod <pod-name> -n <namespace>

# Pod logs
kubectl logs <pod-name> -n <namespace>

# Check environment variables
POD=$(kubectl get pods -n <namespace> -l p6m.dev/app=<app-name> -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n <namespace> $POD -- env

Check Operator​

# Check operator is running
kubectl get pods -n platform-application-operator-system

# Check operator logs
kubectl logs -n platform-application-operator-system -l app=platform-application-operator

Tutorial Sections​