{"id":"l-dk-5-4","courseId":"docker-kubernetes","lang":"en","kind":"lesson","summary":"Route public HTTPS traffic to notes-api with Gateway API, harden its Pods with a securityContext, and diagnose broken Pods quickly with get, describe, logs, events and kubectl debug.","html":"

Two things stand between notes-api and real users. It isn’t reachable from the internet yet, and when something breaks at 3 a.m., you need to find out what within minutes. This lesson covers both, and finishes with the security settings that complete the production picture.

\n

Getting HTTP traffic in

\n

A LoadBalancer Service per app works for one service. With ten, you’re paying for ten load balancers, managing ten certificates, and routing by hostname or path is impossible. You want one shared entry point that routes HTTP requests to the right Service.

\n

For years the answer was Ingress. It still works, but the Ingress API is frozen and gets no new features, and the widely used community ingress-nginx controller was retired in March 2026: no more releases or security fixes. The Kubernetes project points new work at Gateway API, which is generally available as gateway.networking.k8s.io/v1. It’s installed as an add-on (its CRDs plus an implementation, such as your cloud’s load balancer controller, Envoy Gateway, Cilium or Istio), and many managed clusters offer it out of the box.

\n

Gateway API splits the job by role:

\n\n
\n GatewayClass is chosen by the cluster operator. The Gateway public in namespace infra terminates TLS on port 443. The HTTPRoute notes-api in namespace notes attaches to it and sends requests for notes.skylane.example to the notes-api Service, which forwards to Pods.\n \n GatewayClass\n cluster ops\n \n Gateway :443\n platform\n \n HTTPRoute\n notes team\n \n Service\n \n Pods\n \n \n \n \n notes.skylane.example → notes-api:80\n
Each team owns its layer, and routes attach to a shared Gateway
\n

The platform team’s Gateway, once per cluster:

\n
infra/gateway.yaml
apiVersion: gateway.networking.k8s.io/v1\nkind: Gateway\nmetadata:\n  name: public\n  namespace: infra\nspec:\n  gatewayClassName: skylane-lb        # provided by your implementation\n  listeners:\n    - name: https\n      protocol: HTTPS\n      port: 443\n      hostname: \"*.skylane.example\"\n      tls:\n        mode: Terminate\n        certificateRefs:\n          - name: skylane-wildcard-tls\n      allowedRoutes:\n        namespaces:\n          from: All
\n

Your route, in the notes namespace:

\n
k8s/httproute.yaml
apiVersion: gateway.networking.k8s.io/v1\nkind: HTTPRoute\nmetadata:\n  name: notes-api\n  namespace: notes\nspec:\n  parentRefs:\n    - name: public\n      namespace: infra\n  hostnames:\n    - notes.skylane.example\n  rules:\n    - matches:\n        - path:\n            type: PathPrefix\n            value: /\n      backendRefs:\n        - name: notes-api\n          port: 80
\n

kubectl describe httproute notes-api shows whether the Gateway accepted the route, under Status. If you’re migrating existing Ingress objects, the ingress2gateway tool converts them, including many ingress-nginx annotations.

\n

The debugging playbook

\n

When notes-api misbehaves, resist guessing. Follow the same order every time, and let each step choose the next:

\n
Terminal
kubectl get pods -l app.kubernetes.io/name=notes-api\nkubectl describe pod <pod>\nkubectl logs <pod> --previous\nkubectl events --for pod/<pod> --types=Warning
\n

The STATUS column tells you where to look:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
StatusWhat it meansWhere to look
PendingNo node can take the Poddescribe: events like Insufficient cpu or unmatched node selectors
ImagePullBackOffThe kubelet can’t pull the imagedescribe: wrong tag, missing pull credentials, wrong architecture
CreateContainerConfigErrorA referenced ConfigMap or Secret key is missingdescribe names the key
CrashLoopBackOffThe app starts and exits, repeatedlylogs --previous, plus the exit code in describe (137 = OOM or killed)
Running, 0/1 readyReadiness probe is failingdescribe shows probe failures; check what /readyz depends on

If Pods are healthy but requests fail, work outwards: kubectl get endpointslices -l kubernetes.io/service-name=notes-api (empty means selector or readiness), then the route’s status, then the Gateway.

\n

Distroless images have no shell, so kubectl exec can’t help. Attach an ephemeral debug container instead. It joins the Pod’s network namespace, and with --target it can see the app’s processes too:

\n
Terminal
kubectl debug -it <pod> --image=busybox:1.37 --target=api\n# inside: nslookup notes-db, wget -qO- localhost:3000/readyz, ps
\n\n

The last piece: securityContext

\n

In lesson 2.2 you ran the image as non-root and promised to enforce it in the cluster. Here it is, on the notes-api container:

\n
k8s/deployment.yaml
          securityContext:\n            runAsNonRoot: true\n            allowPrivilegeEscalation: false\n            readOnlyRootFilesystem: true\n            capabilities:\n              drop: [\"ALL\"]
\n

runAsNonRoot makes the kubelet refuse to start the container if the image would run as UID 0. It checks a numeric UID, so an image whose USER is a name such as node fails with CreateContainerConfigError; write USER 1000 in the Dockerfile or add runAsUser: 1000 here. Give the app an emptyDir volume at /tmp if it needs scratch space under a read-only root.

\n

That completes notes-api’s path: a cached multi-stage build, a small non-root image pinned by digest and scanned, a Compose stack for development, and a Deployment with probes, resources, autoscaling, safe rollouts, a Gateway route and a hardened security context. Each of those settings is in the file because an incident taught someone it was needed. Keep that habit: when something breaks, ask which setting would have made it impossible, and add it.

\n","toc":[{"id":"sec-1","text":"Getting HTTP traffic in","level":2},{"id":"sec-2","text":"The debugging playbook","level":2},{"id":"sec-3","text":"The last piece: securityContext","level":2}],"takeaways":["Gateway API splits external traffic into GatewayClass (the implementation), Gateway (the entry point and TLS) and HTTPRoute (an app’s routing rules), so platform and app teams each own their part.","Ingress still works but is frozen, and the community ingress-nginx controller was retired in March 2026; new setups should use Gateway API.","Read Pod status first, then kubectl describe for events, then kubectl logs --previous for crashes; the status tells you which tool to reach for.","kubectl debug --target attaches a temporary container with tools to a running Pod, which is how you inspect distroless images.","A production Pod runs as non-root with no privilege escalation, a read-only root filesystem and all capabilities dropped."],"further":[{"title":"Gateway API","url":"https://kubernetes.io/docs/concepts/services-networking/gateway/"},{"title":"Debug Running Pods","url":"https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/"},{"title":"Configure a Security Context for a Pod or Container","url":"https://kubernetes.io/docs/tasks/configure-pod-container/security-context/"},{"title":"Ingress NGINX Retirement","url":"https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/"}],"quiz":[{"q":"

Your platform team runs a shared Gateway in the infra namespace. What do you, the notes-api team, create to expose notes.skylane.example?

","options":[{"text":"A new GatewayClass for notes-api.","why":"GatewayClasses describe an implementation and are usually set up once per cluster by the platform team."},{"text":"An HTTPRoute in the notes namespace that references the shared Gateway in parentRefs and the notes-api Service in backendRefs.","why":"Correct. Routes belong to app teams; the Gateway decides (via allowedRoutes) which namespaces may attach."},{"text":"A second Gateway listening on port 443.","why":"That duplicates the platform’s entry point and its TLS setup. Attach a route to the existing one."},{"text":"A LoadBalancer Service for notes-api.","why":"That bypasses the shared entry point and gives you a separate public address to manage."}],"answer":1},{"q":"

A Pod shows ImagePullBackOff. Which is the most useful next step?

","options":[{"text":"kubectl logs <pod>","why":"The container never started, so there are no logs to read."},{"text":"kubectl rollout restart deployment/notes-api","why":"New Pods will fail to pull the same image the same way."},{"text":"kubectl debug -it <pod> --image=busybox:1.37","why":"There’s no running container to attach to, and the problem is the pull, not the Pod’s runtime."},{"text":"kubectl describe pod <pod> and read the pull error in the events: wrong tag, missing registry credentials, or no image for this architecture.","why":"Correct. The events state exactly why the kubelet couldn’t pull."}],"answer":3},{"q":"

notes-api is in CrashLoopBackOff. kubectl logs <pod> shows only a line or two of startup output. What should you run?

","options":[{"text":"kubectl logs <pod> --previous, to read the output of the container instance that crashed.","why":"Correct. The current instance may have only just started. --previous shows the last one’s output, including the error that killed it."},{"text":"kubectl delete pod <pod>, so it starts fresh.","why":"The replacement runs the same image with the same config and crashes the same way, and you’ve lost the evidence."},{"text":"kubectl scale deployment/notes-api --replicas=0","why":"That stops the crash loop by stopping the service, without telling you anything."},{"text":"kubectl get nodes","why":"Node health rarely causes a crash loop in a single app; the app’s own output is the place to start."}],"answer":0},{"q":"

notes-api’s image is distroless, so kubectl exec -it <pod> -- sh fails. How do you check DNS resolution from inside the Pod?

","options":[{"text":"Rebuild the image with a shell, deploy it, and try again.","why":"It changes the thing you’re debugging and takes a full release cycle."},{"text":"Use kubectl port-forward and run nslookup on your laptop.","why":"That resolves names with your laptop’s DNS, not the Pod’s."},{"text":"kubectl debug -it <pod> --image=busybox:1.37 --target=api, then run nslookup notes-db in the debug container.","why":"Correct. The ephemeral container shares the Pod’s network namespace (and, with --target, its process view), bringing the tools the image lacks."},{"text":"Read /etc/resolv.conf with kubectl logs.","why":"Logs show what the process printed, not files inside the container."}],"answer":2}],"exercise":{"kind":"choice","multiple":true,"options":["crash-logs","pending-describe","pull-logs","notready-probe","crash-delete"],"correct":["crash-logs","pending-describe","notready-probe"],"title":"First move for each symptom","prompt":"

You’re on call for notes-api. For each symptom below, a teammate proposes a first move. Select every pairing where the first move is the right one.

\n","hints":["Ask of each: has a container actually run yet? If not, it has no logs.","Which moves gather evidence, and which ones destroy it?","Three pairings are right."],"explanation":"

A crash loop leaves its error in the previous container’s output, so logs --previous comes first. A Pending Pod was never scheduled; describe shows the scheduler’s reason. A Running Pod that isn’t ready is failing its readiness probe; describe shows the failures and /readyz tells you which dependency is down. An image pull failure has no logs because no container ran; read the pull error in describe. Deleting a crashing Pod throws away its logs and events and the replacement crashes the same way.

\n","checkLabels":{},"optionText":{"crash-logs":{"text":"CrashLoopBackOff → kubectl logs <pod> --previous","why":"Correct. The crashed instance’s output usually contains the error that killed it."},"pending-describe":{"text":"Pending for five minutes → kubectl describe pod <pod> and read the scheduling events","why":"Correct. Events like Insufficient memory or an unmatched node selector explain why no node accepted it."},"pull-logs":{"text":"ImagePullBackOff → kubectl logs <pod>","why":"The container never started, so there are no logs. describe shows the pull error."},"notready-probe":{"text":"Running but 0/1 ready → kubectl describe pod <pod> for probe failures, then check what /readyz depends on","why":"Correct. Readiness failures are recorded as events, and the endpoint’s dependencies are usually the cause."},"crash-delete":{"text":"CrashLoopBackOff → kubectl delete pod <pod> so it restarts cleanly","why":"The replacement runs the same image and config and crashes the same way, and the old Pod’s evidence is gone."}}},"words":676,"readMinutes":3}