# Ingress troubleshooting

Use the request-path visual before changing state:

![Kubernetes request path](../architecture/generated/request-path.svg)

The diagram is a public-safe logical path; it contains no hostnames or
addresses.

## Preconditions

- Record the affected hostname, path, resolver location, expected namespace,
  and last known successful request in a private incident record.
- Start with read-only discovery. Do not restart Traefik, delete policy, or
  rotate certificates before locating the first failed handoff.

## Procedure

1. Check DNS from the affected resolver location:

   ```bash
   dig "${HOSTNAME:?set the affected host}"
   ```

   Compare the answer with the intended public or local entry. A correct answer
   from one resolver does not clear other caches or split-horizon DNS.
2. Check the TLS handshake and hostname, then inspect certificate-controller
   status. Certificate presence alone does not prove the client received the
   intended chain or SNI route.
3. Inspect the route and controller handoff:

   ```bash
   kubectl get ingress -A
   kubectl describe ingress "${INGRESS:?set the route}" -n "${NAMESPACE:?set the namespace}"
   ```

   Confirm the requested host/path and referenced Service port. Review Traefik
   events or logs only for that route and time window.
4. Follow the Service selection and port mapping:

   ```bash
   kubectl get service "${SERVICE:?set the service}" -n "${NAMESPACE}" -o yaml
   kubectl get endpointslice -n "${NAMESPACE}" \
     -l "kubernetes.io/service-name=${SERVICE}" -o yaml
   ```

   Ready EndpointSlice addresses prove selection and readiness state, not that
   the application returns the correct response.
5. Inspect selected pods, readiness failures, recent events, and the configured
   container port. Run one bounded request from an approved location and record
   status, latency, and response class without capturing secrets.
6. Compare declared NetworkPolicies with source/destination labels, ports, and
   protocol. Static policy review is not observed traffic; use Cilium/Hubble
   flow data when an L3/L4 or L7 conclusion requires it.

## Expected result

The investigation identifies the first transition where intended and observed
state diverge: DNS, TLS, ingress, Service port/selector, EndpointSlice, pod
readiness, policy/data plane, or application response.

## Failure and rollback

- Preserve the failing output and make the smallest reversible correction at
  that stage.
- Roll back a route, Service, certificate, or policy change if the intended
  transition still fails or another known path regresses.
- Avoid broad restarts and policy deletion. Escalate when the path depends on an
  external DNS provider, certificate authority, load balancer, or network not
  observable from Kubernetes.

Keep private hosts, addresses, certificate details, and tokens out of public
notes. See [service-path analyzer notes](../architecture/service-path-analyzer.md).