Demo The Power of Status Fields

In this lesson we walk through five common Gateway API troubleshooting scenarios using the NGINX Gateway Fabric. For each case you’ll see the observable symptom, how to inspect status fields and controller messages, the root cause, and the corrective steps to verify the fix.

A presentation slide showing the title "The Power of Status Fields" on the left and a large turquoise curved shape on the right with the word "Demo" inside it. A small "© Copyright KodeKloud" note appears in the lower-left corner.

Summary of scenarios

Scenario	Symptom	Typical Root Cause	Quick Fix
1	Gateway shows `ADDRESS` empty / `PROGRAMMED = Unknown`	Wrong `spec.gatewayClassName` (typo)	Correct `gatewayClassName`, reapply
2	Gateway listener shows `Attached Routes: 0` despite an HTTPRoute present	Typo or incorrect `parentRefs` prevents route from referencing the Gateway	Fix `parentRefs.name` (or other fields), reapply
3	TLS certificate error: `Certificate ref ... not permitted by any ReferenceGrant`	Gateway referencing a Secret in another namespace without a `ReferenceGrant`	Create `ReferenceGrant` in Secret’s namespace (or move Secret)
4	`404 Not Found` from NGINX even though route is accepted	Request path not matched by route rules	Use the correct path or expand route matches
5	`500 Internal Server Error` from NGINX	`backendRef.port` doesn’t match Service port (`BackendNotFound`)	Fix backend port in HTTPRoute to match Service

Useful references:

Scenario 1 — Gateway exists but shows no address / Programmed = Unknown

Symptom: After applying a Gateway manifest the ADDRESS field is empty and PROGRAMMED remains Unknown. Inspect the files and object:

~/coding/kubernetes/nginx-fabric-gateway/kodekloud/lab-4-troubleshooting/tshoot-1
› ls
gateway.yaml

› kubectl get gateway
NAME      CLASS   ADDRESS   PROGRAMMED   AGE
gateway   ngin    Unknown   83s

Check GatewayClass and controller status:

› kubectl get gatewayclasses
NAME   CONTROLLER                                   ACCEPTED   AGE
nginx  gateway.nginx.org/nginx-gateway-controller   True       3h32m

Root cause: the Gateway is referencing the wrong class name (ngin) so the controller does not adopt or program it. Fix: update gateway.yaml to use the correct spec.gatewayClassName (e.g. nginx) and reapply:

› kubectl apply -f gateway.yaml
gateway.gateway.networking.k8s.io/gateway configured

Verify the Gateway is now programmed and has an address:

› kubectl get gateway
NAME      CLASS   ADDRESS        PROGRAMMED   AGE
gateway   nginx   10.96.31.67    True         2m30s

Scenario 2 — HTTPRoute applied but Gateway shows “Attached Routes: 0”

Symptom: An HTTPRoute exists, but the Gateway’s listener shows Attached Routes: 0. Check the route:

› kubectl get httproute
NAME     HOSTNAMES                AGE
coffee   ["cafe.example.com"]      99s

Describe the Gateway (note Attached Routes: 0):

› kubectl describe gateway gateway
# (excerpt)
Listeners:
  Attached Routes: 0

Describe the HTTPRoute to inspect parentRefs and status:

› kubectl describe httproute coffee
Name:         coffee
Namespace:    default
Spec:
  Hostnames:
    cafe.example.com
  Parent Refs:
    Group:        gateway.networking.k8s.io
    Kind:         Gateway
    Name:         gatew
    Section Name: http
Status:  # empty / missing detailed status when parent not found
  (no parents info)

Root cause: a typo in parentRefs.name (gatew instead of gateway) — the controller cannot associate the HTTPRoute with the Gateway, so attachment and parent status are missing. Fix: correct parentRefs.name in coffee-route.yaml to the Gateway name (gateway) and reapply:

# edit coffee-route.yaml to fix parentRefs.name: gateway
› kubectl apply -f coffee-route.yaml
httproute.gateway.networking.k8s.io/coffee configured

Verify status now includes parent conditions and the Gateway shows the attached route:

› kubectl describe httproute coffee
# (excerpt)
Status:
  Parents:
    Conditions:
      Type: Accepted
      Status: True
      Message: The Route is accepted
    Conditions:
      Type: ResolvedRefs
      Status: True
      Message: All references are resolved
Controller Name: gateway.nginx.org/nginx-gateway-controller
Parent Ref:
  Name: gateway
  Section Name: http

› kubectl describe gateway gateway
# (excerpt)
Listeners:
  Attached Routes: 1
  Conditions:
    Type: Accepted
    Status: True
    Message: The Listener is accepted

Scenario 3 — TLS: Gateway can’t access Secret in another namespace (ReferenceGrant needed)

Symptom: Gateway’s HTTPS listener fails to resolve the TLS secret and shows:

Certificate ref to secret certificate/cafe-secret not permitted by any ReferenceGrant

Inspect namespaces, Secrets and Gateway:

› kubectl get ns
NAME         STATUS   AGE
certificate  Active   68s
default      Active   7h11m

› kubectl get secrets -n certificate
NAME         TYPE                DATA   AGE
cafe-secret  kubernetes.io/tls   2      75s

› kubectl get gateway
NAME    CLASS   ADDRESS        PROGRAMMED   AGE
gateway nginx    10.96.205.15   True         81s

Describe the Gateway to see TLS certificate reference and the error:

› kubectl describe gateway gateway
# (excerpt)
Listeners:
  Name: https
  Port: 443
  Protocol: HTTPS
  Tls:
    Certificate Refs:
      Kind: Secret
      Name: cafe-secret
      Namespace: certificate
      Mode: Terminate
Conditions:
  Type: ResolvedRefs
  Status: False
  Message: Certificate ref to secret certificate/cafe-secret not permitted by any ReferenceGrant
  Reason: RefNotPermitted

Root cause: Gateways in the default namespace cannot reference a Secret in the certificate namespace by default. The Gateway API requires an explicit ReferenceGrant in the Secret’s namespace to allow cross-namespace references. Fix: Create a ReferenceGrant in the Secret namespace (certificate) that allows the Gateway to reference the Secret. Example manifest (ref-grant.yaml):

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: access-certificate
  namespace: certificate
spec:
  to:
  - group: ""
    kind: Secret
    name: cafe-secret
  from:
  - group: gateway.networking.k8s.io
    kind: Gateway
    namespace: default

Apply it:

› kubectl apply -f ref-grant.yaml
referencegrant.gateway.networking.k8s.io/access-certificate created

Verify the Gateway listener conditions are resolved and programmed:

› kubectl describe gateway gateway
# (excerpt)
Listeners:
  Conditions:
    Type: ResolvedRefs
    Status: True
    Message: All references are resolved
    Type: Programmed
    Status: True
    Message: The Listener is programmed

Note: alternatively, place the TLS Secret in the same namespace as the Gateway to avoid needing a ReferenceGrant. When cross-namespace references are required, ReferenceGrant is the recommended approach.

Scenario 4 — 404 Not Found: route exists but you requested the wrong path

Symptom: Gateway and HTTPRoute are accepted, but client requests return 404 Not Found. Verify Service and Pods:

› kubectl get svc
NAME          TYPE        CLUSTER-IP      PORT(S)
coffee        ClusterIP   10.96.197.88    80/TCP
gateway-nginx NodePort    10.96.205.15    80:31437/TCP
kubernetes    ClusterIP   10.96.0.1       443/TCP

› kubectl get pod
NAME                             READY STATUS RESTARTS AGE
coffee-5b9c74f9d9-9rf2f          1/1   Running 0        6h54m
gateway-nginx-5f9d4c4ff-zbk45    1/1   Running 0        52s

Inspect the HTTPRoute manifest:

# coffee-route.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: coffee
spec:
  parentRefs:
  - name: gateway
    sectionName: http
  hostnames:
  - "cafe.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /coffee
    backendRefs:
    - name: coffee
      port: 80

The client requested a different path (/tea):

› curl --resolve cafe.example.com:8080:127.0.0.1 \
  http://cafe.example.com:8080/tea --include
HTTP/1.1 404 Not Found
Server: nginx
...

Root cause: The route only matches PathPrefix /coffee. Requests to /tea do not match and return 404. Fix options:

Use the correct path: request /coffee.
Or update the HTTPRoute to include additional matches for /tea or a broader prefix.

Example correct request:

› curl --resolve cafe.example.com:8080:127.0.0.1 \
  http://cafe.example.com:8080/coffee --include
HTTP/1.1 200 OK
Server: nginx
...
URI: /coffee
Request ID: a7109559ef3e306fc5d0b65727ec43e0

Scenario 5 — 500 Internal Server Error: backend port mismatch (BackendNotFound)

Symptom: The HTTPRoute is attached and accepted, but requests return 500 Internal Server Error. Reproduce the symptom:

› kubectl get gateway
NAME    CLASS   ADDRESS        PROGRAMMED   AGE
gateway nginx    10.96.12.59    True         75s

› kubectl get httproute
NAME    HOSTNAMES               AGE
coffee  ["cafe.example.com"]    75s

› curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coffee --include
HTTP/1.1 500 Internal Server Error
Server: nginx
...

Describe the HTTPRoute and inspect backend references:

› kubectl describe httproute coffee
# (excerpt)
Rules:
  Backend Refs:
    Name: coffee
    Port: 808
Status:
  Parents:
    Conditions:
      Type: ResolvedRefs
      Status: False
      Message: No matching port for Service coffee and port 808
      Reason: BackendNotFound

Check the Service ports:

› kubectl get svc coffee -o wide
NAME     TYPE       CLUSTER-IP     PORT(S)
coffee   ClusterIP  10.96.197.88   80/TCP

Root cause: the HTTPRoute references port 808, but the Service exposes port 80. The controller cannot resolve the backend port, so NGINX cannot forward traffic and returns a 500. Fix: update the HTTPRoute backendRefs.port to match the Service port 80. Example before/after: Before (incorrect):

# incorrect: backendRefs.port: 808
rules:
- matches:
  - path:
      type: PathPrefix
      value: /coffee
  backendRefs:
  - name: coffee
    port: 808

After (fixed):

# corrected: backendRefs.port: 80
rules:
- matches:
  - path:
      type: PathPrefix
      value: /coffee
  backendRefs:
  - name: coffee
    port: 80

Apply and verify:

› kubectl apply -f coffee-route.yaml
httproute.gateway.networking.k8s.io/coffee configured

› kubectl describe httproute coffee
# (excerpt)
Status:
  Parents:
    Conditions:
      Type: ResolvedRefs
      Status: True
      Message: All references are resolved

Request should now succeed:

› curl --resolve cafe.example.com:8080:127.0.0.1 \
  http://cafe.example.com:8080/coffee --include
HTTP/1.1 200 OK
Server: nginx
...
URI: /coffee
Request ID: 5b9e772af3cc2168626d1f29ab51abcd

When troubleshooting Gateway API resources, start with status fields and controller messages — they are purposefully descriptive. Typical culprits are incorrect GatewayClass names, typos in parentRefs, missing ReferenceGrant for cross-namespace Secrets, mismatched service ports, or incorrect route paths. Isolate whether the issue is control plane (controller not adopting), data plane (NGINX config/backends), or client-side (wrong hostname/path), then fix manifests or permissions and reapply.

Introduction & Why Gateway API

Core Gateway API Resources

Advanced Traffic Management

TLS and Cross-Namespace Security

Troubleshooting and Best Practices

Demo The Power of Status Fields

Scenario 1 — Gateway exists but shows no address / Programmed = Unknown

Scenario 2 — HTTPRoute applied but Gateway shows “Attached Routes: 0”

Scenario 3 — TLS: Gateway can’t access Secret in another namespace (ReferenceGrant needed)

Scenario 4 — 404 Not Found: route exists but you requested the wrong path

Scenario 5 — 500 Internal Server Error: backend port mismatch (BackendNotFound)

Watch Video

Practice Lab

​Scenario 1 — Gateway exists but shows no address / Programmed = Unknown

​Scenario 2 — HTTPRoute applied but Gateway shows “Attached Routes: 0”

​Scenario 3 — TLS: Gateway can’t access Secret in another namespace (ReferenceGrant needed)

​Scenario 4 — 404 Not Found: route exists but you requested the wrong path

​Scenario 5 — 500 Internal Server Error: backend port mismatch (BackendNotFound)

Watch Video

Practice Lab

Scenario 1 — Gateway exists but shows no address / Programmed = Unknown

Scenario 2 — HTTPRoute applied but Gateway shows “Attached Routes: 0”

Scenario 3 — TLS: Gateway can’t access Secret in another namespace (ReferenceGrant needed)

Scenario 4 — 404 Not Found: route exists but you requested the wrong path

Scenario 5 — 500 Internal Server Error: backend port mismatch (BackendNotFound)