Nav Troubleshoot

Nav Troubleshoot — Platform Diagnostics

Strukturerte diagnostiske trær for vanlige problemer på Nais-plattformen. Erstatter «spør i Slack-kanalen» med guidet feilsøking.

Workflow

1. Identifiser symptomet — hva feiler?
2. Følg diagnostisk tre — steg-for-steg med kommandoer
3. Finn rotårsak — hva outputen betyr
4. Fiks — konkret løsning

Symptom-oversikt

| Symptom | Start her | |---------|-----------| | Pod starter ikke / krasjer | [Pod-problemer](#pod-problemer) | | 401 Unauthorized / 403 Forbidden | [Auth-feil](#auth-feil) | | Kafka consumer lag / meldinger prosesseres ikke | [Kafka-problemer](#kafka-problemer) | | Database-tilkoblingsfeil | [Database-problemer](#database-problemer) | | Treg responstid | [Ytelse](#ytelsesproblemer) | | Deploy feiler | [Deploy-problemer](#deploy-problemer) |

Se [diagnostic-trees.md](./references/diagnostic-trees.md) for detaljerte diagnostiske trær med kommandoer.

Pod-problemer

CrashLoopBackOff

# 1. Sjekk pod-status
kubectl get pods -n {namespace} -l app={app-name}

# 2. Sjekk logs fra forrige krasj
kubectl logs -n {namespace} -l app={app-name} --previous --tail=50

# 3. Sjekk events
kubectl describe pod -n {namespace} {pod-name} | grep -A 20 Events

Vanlige årsaker:

| Log-output | Årsak | Løsning | |-----------|-------|---------| | OOMKilled | For lite minne | Øk resources.limits.memory | | java.lang.OutOfMemoryError | Java heap for liten | Legg til -Xmx eller øk memory limit | | Connection refused: localhost:5432 | Database ikke klar | Sjekk Cloud SQL-instans, Flyway-migrasjon | | AZURE_APP_CLIENT_ID not set | Manglende env-var | Sjekk at azure.application.enabled: true i Nais | | No such file or directory | Feil Dockerfile COPY | Verifiser at build-artefakt kopieres riktig | | Port-mismatch | App lytter på feil port | Sjekk at spec.port matcher appens port |

ImagePullBackOff

# Sjekk image-navn
kubectl describe pod -n {namespace} {pod-name} | grep Image

# Vanlige årsaker:
# - Feil image-tag (bygget mislyktes)
# - GAR-autentisering feilet
# - Image finnes ikke

Pending (pod starter aldri)

# Sjekk om det er ressurs-begrensninger
kubectl describe pod -n {namespace} {pod-name} | grep -A 5 Conditions

# Vanlige årsaker:
# - Ikke nok ressurser i klusteret
# - PersistentVolumeClaim ikke bundet
# - Node-selektor matcher ikke

Auth-feil

401 Unauthorized

# 1. Sjekk om token er gyldig
echo "{token}" | cut -d'.' -f2 | base64 -d 2>/dev/null | jq .

# 2. Sjekk issuer
# Token bør ha: "iss": "https://login.microsoftonline.com/{tenant}/v2.0"

# 3. Sjekk audience
# Token bør ha: "aud": "{din-app-client-id}"

# 4. Sjekk om JWKS er tilgjengelig
kubectl exec -n {namespace} {pod} -- wget -qO- $AZURE_OPENID_CONFIG_JWKS_URI | head -1

Diagnostisk tre:

401 Unauthorized
├── Har forespørselen Authorization-header?
│   ├── Nei → Kaller mangler token, sjekk frontend/sidecar
│   └── Ja → Gå videre
│
├── Er token fra riktig issuer?
│   ├── Azure AD men forventet TokenX → Feil auth-flow
│   ├── ID-porten men forventet Azure AD → Feil sidecar-config
│   └── Riktig issuer → Gå videre
│
├── Er audience riktig?
│   ├── Feil audience → Kaller sender token til feil mottaker
│   └── Riktig → Gå videre
│
├── Er token utløpt?
│   ├── exp  0

# 2. Sjekk pod-logs for feil
kubectl logs -n {namespace} -l app={app-name} --tail=100 | grep -i "error\|exception\|failed"

# 3. Sjekk om konsumenten prosesserer
kubectl logs -n {namespace} -l app={app-name} --tail=20 | grep -i "processed\|consumed"

Diagnostisk tre:

Kafka consumer lag
├── Øker lag kontinuerlig?
│   ├── Ja → Konsumenten kan ikke holde tritt
│   │   ├── Sjekk prosesseringstid per melding
│   │   ├── Vurder å øke partitions + replicas
│   │   └── Sjekk om det er en poison pill (melding som feiler)
│   └── Nei, sporadisk → Normal variasjon, sannsynligvis OK
│
├── Er konsumenten oppe?
│   ├── Nei → Sjekk pod-status (CrashLoopBackOff?)
│   └── Ja → Gå videre
│
├── Logger konsumenten feil?
│   ├── Deserialisering-feil → Schema-mismatch, sjekk producer
│   ├── DB-feil → Database-problem, se database-seksjon
│   └── Ingen feil → Sjekk om den faktisk leser fra riktig topic
│
└── Rapids & Rivers?
    ├── Sjekk at validate()-regler matcher meldingsformat
    ├── Sjekk at @event_name er riktig
    └── Prøv å legge til interestedIn() for feilsøking

Database-problemer

Connection refused / timeout

# 1. Sjekk at Cloud SQL-instans kjører
# Nais Console → App → Database → Status

# 2. Sjekk env-vars
kubectl get pod {pod} -n {namespace} -o jsonpath='{range .spec.containers[0].env[*]}{.name}={.value}{"\n"}{end}' | grep DB_

# 3. Sjekk pool-status (i app-logs)
kubectl logs -n {namespace} -l app={app-name} | grep -i "hikari\|connection\|pool"

Diagnostisk tre:

Database-tilkoblingsfeil
├── Er Cloud SQL-instans oppe?
│   ├── Nei → Sjekk GCP Console / Nais Console
│   └── Ja → Gå videre
│
├── Er env-vars satt?
│   ├── DB_HOST/DB_PORT/DB_DATABASE mangler → Sjekk Nais-manifest gcp.sqlInstances
│   └── Satt → Gå videre
│
├── Feilet Flyway-migrasjon?
│   ├── Ja → Sjekk SQL-feil i startup-log
│   └── Nei → Gå videre
│
├── Pool exhaustion?
│   ├── «Connection is not available» → Reduser maxPoolSize, sjekk lekkasjer
│   ├── Mange «active» connections → Trege queries, sjekk EXPLAIN
│   └── Nei → Gå videre
│
└── max_connections nådd?
    ├── Ja → Reduser pool per replica: replicas × maxPool < max_connections
    └── Nei → Sjekk nettverks-tilgang (Cloud SQL proxy)

Ytelsesproblemer

Treg responstid
├── Hvor er flaskehalsen?
│   ├── Sjekk Prometheus: http_request_duration_seconds
│   ├── Sjekk Tempo: distribuert trace
│   └── Sjekk Grafana Loki: loggtider
│
├── Database-queries?
│   ├── Manglende indekser → EXPLAIN ANALYZE
│   ├── N+1 queries → Bruk JOIN eller batch
│   └── Store result sets → Paginering
│
├── Ekstern tjeneste treg?
│   ├── Sjekk response time per dependency
│   ├── Vurder circuit breaker
│   └── Vurder caching
│
└── Ressursbegrensning?
    ├── CPU throttling → ALDRI sett CPU limits, sjekk requests
    └── Memory pressure → Øk memory limit

Deploy-problemer

Deploy feiler
├── GitHub Actions-feil?
│   ├── Build-feil → Sjekk kompileringsfeil i actions-log
│   ├── Docker build-feil → Sjekk Dockerfile
│   └── Push-feil → Sjekk GAR-tilgang
│
├── Nais deploy-feil?
│   ├── «invalid manifest» → Valider YAML-syntaks
│   ├── «unauthorized» → Sjekk deploy-key/workload-identity
│   └── «resource quota exceeded» → Sjekk team-kvote
│
└── Deploy OK, men app feiler?
    ├── Sjekk pod-status (se Pod-problemer over)
    └── Sjekk rollout: kubectl rollout status deployment/{app}

Boundaries

✅ Always

• Start med å identifisere symptomet før du kjører kommandoer
• Følg det diagnostiske treet steg for steg
• Sjekk logs og events før du endrer konfigurasjon
• Foreslå minst invasive fiks først

⚠️ Ask First

• Endre produksjons-konfigurasjon
• Restarte pods i produksjon
• Endre database-konfigurasjon

🚫 Never

• Endre secrets direkte i klusteret
• Kjør kubectl delete pod i prod uten å forstå årsaken
• Ignorer OOMKilled — det vil skje igjen

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: navikt
• Source: navikt/copilot
• License: MIT
• Homepage: https://ki-utvikling.nav.no/nav-pilot

Install and usage instructions live in the source repository linked above.