github.com/cilium/cilium@v1.16.2/Documentation/network/servicemesh/gateway-api/troubleshooting.rst

github.com/cilium/cilium@v1.16.2/Documentation/network/servicemesh/gateway-api/troubleshooting.rst (about)

1 This page guides you through the different mechanics of Gateway API and how to troubleshoot them.
2
3 Be sure to follow the Generic and Setup Verification steps from the :ref:`Troubleshooting Ingress & Service Mesh page<troubleshooting_servicemesh>`.
4
5 Checking resources
6 ******************
7
8 #. Check the Gateway resource
9
10 .. code-block:: shell-session
11
12 $ kubectl get gateway -A
13 NAMESPACE NAME CLASS ADDRESS PROGRAMMED AGE
14 website http-gateway cilium 172.21.255.202 True 5h
15 webshop tls-gateway cilium 172.21.255.203 True 5h
16
17 The preceding command returns an overview of all the Gateways in the cluster. Check the following:
18
19 * Is the Gateway programmed?
20
21 A programmed Gateway means that Cilium prepared a configuration for it.
22
23 * If the ``Programmed true`` indicator is missing, make sure that Gateway API is enabled in the Cilium configuration.
24
25 * Does the gateway have an address?
26
27 You can check the service with ``kubectl get service``.
28 If the gateway has an address, it means that a LoadBalancer service is assigned to the gateway.
29 If no IP appears, you might be missing a LoadBalancer implementation.
30
31 * Is the class ``cilium``?
32
33 Cilium only programs Gateways with the class ``cilium``.
34
35 * If the Gateway API resource type (``Gateway``, ``HTTPRoute``, etc.) is not found, make sure that the Gateway API CRDs are installed.
36
37 You can use ``kubectl describe gateway`` to investigate issues more thoroughly.
38
39 .. code-block:: shell-session
40
41 $ kubectl describe gateway <name>
42
43 Conditions:
44 Message: Gateway successfully scheduled
45 Reason: Accepted
46 Status: True
47 Type: Accepted
48 Message: Gateway successfully reconciled
49 Reason: Programmed
50 Status: True
51 Type: Programmed
52 [...]
53 Listeners:
54 Attached Routes: 2
55 Conditions:
56 Message: Listener Ready
57 Reason: Programmed
58 Status: True
59 Type: Programmed
60 Message: Listener Accepted
61 Reason: Accepted
62 Status: True
63 [...]
64
65 You can see the general status of the gateway as well as the status of the configured listeners.
66
67 Listener status displays the number of routes successfully attached to the listener.
68
69 You can see status conditions for both gateway and listener:
70
71 * ``Accepted``: the Gateway configuration was accepted.
72 * ``Programmed``: the Gateway configuration was programmed into Envoy.
73 * ``ResolvedRefs``: all referenced secrets were found and have permission for use.
74
75 If any of these conditions are set to false, the ``Message`` and ``Reason`` fields give more information.
76
77 #. Check the HTTPRoute resource
78
79 When the Gateway is functional, you can check the routes to verify if they are configured correctly.
80 The way to check route status is similar to checking the status of a gateway resource.
81
82 While these instructions are written for HTTPRoute, they also apply to other route types.
83
84 .. code-block:: shell-session
85
86 $ kubectl get httproute -A
87 NAMESPACE NAME HOSTNAMES AGE
88 website homepage www.example.org 17m
89 webshop catalog-service 17m
90 webshop cart-service 17m
91
92 To get more information, enter ``kubectl describe httproute <name>``.
93
94 .. code-block:: shell-session
95
96 $ kubectl describe httproute <name>
97 Status:
98 Parents:
99 Conditions:
100 Last Transition Time: 2023-06-05T15:11:53Z
101 Message: Accepted HTTPRoute
102 Observed Generation: 1
103 Reason: Accepted
104 Status: True
105 Type: Accepted
106 Last Transition Time: 2023-06-05T15:11:53Z
107 Message: Service reference is valid
108 Observed Generation: 1
109 Reason: ResolvedRefs
110 Status: True
111 Type: ResolvedRefs
112 Controller Name: io.cilium/gateway-controller
113 Parent Ref:
114 Group: gateway.networking.k8s.io
115 Kind: Gateway
116 Name: same-namespace
117
118 Status lists the conditions that are relevant for the specific ``HTTPRoute``.
119 Conditions are listed by parent reference to the gateway. If you linked the route to multiple gateways, multiple entries appear.
120 Conditions include ``Reason``, ``Type``, ``Status`` and ``Message``. ``Type`` indicates the condition type, and ``Status`` indicates with a boolean whether the condition type is met. Optionally, ``Message`` gives you more information about the condition.
121
122 Notice the following condition types:
123
124 * ``Accepted``: The HTTPRoute configuration was correct and accepted.
125 * ``ResolvedRefs``: The referenced services were found and are valid references.
126
127 If any of these are set to false, you can get more information by looking at the ``Message`` and ``Reason`` fields.
128
129 #. Check Cilium Operator logs
130
131 The Cilium Operator logs may contain further debugging information. For example, if the required Custom Resource Definitions (CRDs) are not installed, an error will be logged:
132
133 .. code-block:: shell-session
134
135 $ kubectl logs -n kube-system deployments/cilium-operator | grep gateway
136 level=error msg="Required GatewayAPI resources are not found, please
137 refer to docs for installation instructions" error="customresourcedefinitions.apiextensions.k8s.io \"gatewayclasses.gateway.networking.k8s.io\" not found
138 customresourcedefinitions.apiextensions.k8s.io \"gateways.gateway.networking.k8s.io\" not found
139 customresourcedefinitions.apiextensions.k8s.io \"httproutes.gateway.networking.k8s.io\" not found
140 customresourcedefinitions.apiextensions.k8s.io \"referencegrants.gateway.networking.k8s.io\" not found
141 customresourcedefinitions.apiextensions.k8s.io \"grpcroutes.gateway.networking.k8s.io\" not found
142 customresourcedefinitions.apiextensions.k8s.io \"tlsroutes.gateway.networking.k8s.io\" not found" subsys=gateway-api
143
144 Common mistakes
145 ***************
146
147 .. include:: mistakes-warning.rst
148
149 * The backend service does not exist.
150
151 To verify whether the backend service was found, run ``kubectl describe httproute <name>`` and inspect the ``conditions`` field:
152
153 .. code-block:: shell-session
154
155 Parents:
156 Conditions:
157 Last Transition Time: 2023-06-06T13:55:10Z
158 Message: Service "backend" not found
159 Observed Generation: 1
160 Reason: BackendNotFound
161 Status: False
162 Type: ResolvedRefs
163 Last Transition Time: 2023-06-06T13:55:10Z
164 Message: Accepted HTTPRoute
165 Observed Generation: 1
166 Reason: Accepted
167 Status: True
168 Type: Accepted
169 Controller Name: io.cilium/gateway-controller
170
171 * The gateway specified under ``parentRefs`` does not exist.
172
173 To verify whether the gateway was found, run ``kubectl describe httproute <name>`` and inspect the ``conditions`` field:
174
175 .. code-block:: shell-session
176
177 Parents:
178 Conditions:
179 Last Transition Time: 2023-06-06T13:56:40Z
180 Message: Gateway.gateway.networking.k8s.io "my-gatewai" not found
181 Observed Generation: 2
182 Reason: InvalidHTTPRoute
183 Status: False
184 Type: Accepted
185
186 Underlying mechanics: a high level overview
187 *******************************************
188
189 A Cilium deployment has two parts that handle Gateway API resources: the Cilium agent and the Cilium operator.
190
191 The Cilium operator watches all Gateway API resources and verifies whether the resources are valid.
192 If resources are valid, the operator marks them as accepted. That starts the process of translation into Cilium Envoy Configuration resources.
193
194 The Cilium agent then picks up the Cilium Envoy Configuration resources.
195
196 The Cilium agent uses the resources to supply the configuration to the built in Envoy or the Envoy DaemonSet. Envoy handles traffic.