Skip to content

Commit 140f0c5

Browse files
rh-tokeeferh-tokeefe
committed
OSSM-9388: Document Gateway API with OSSM
1 parent 60ddd12 commit 140f0c5

File tree

2 files changed

+213
-0
lines changed

2 files changed

+213
-0
lines changed

‎gateways/ossm-getting-traffic-into-a-mesh.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ include::modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc
1414
include::modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc[leveloffset=+2]
1515
include::modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc[leveloffset=+1]
1616
include::modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc[leveloffset=+2]
17+
include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc[leveloffset=+1]

‎modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
// Module included in the following assemblies:
2+
// * service-mesh-docs-main/gateways/ossm-getting-traffic-into-a-mesh.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="ossm-exposing-a-service-by-using-the-kubernetes-gateway-api_{context}"]
6+
= Exposing a service by using the {k8s} Gateway API
7+
8+
Use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources and deploy a gateway. The resources configure the gateway to expose a service in the mesh to traffic outside the mesh. Then, you can set the `Service` for the gateway to `LoadBalancer` to expose the gateway to traffic outside the cluster.
9+
10+
.Prerequisites
11+
12+
* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role.
13+
14+
* You installed the {SMProductName} Operator.
15+
16+
* You deployed the {istio} resource.
17+
18+
.Procedure
19+
20+
. Create a namespace called `httpbin` by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc create namespace httpbin
25+
----
26+
27+
. Deploy a sample service named `httpbin` by running the following command:
28+
+
29+
[source,terminal]
30+
----
31+
$ oc apply -n httpbin -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/httpbin/httpbin.yaml
32+
----
33+
34+
. Create a YAML file named `httpbin-gw.yaml` that defines a {k8s} Gateway resource. This resource configures gateway proxies to expose port 80 (HTTP) for the host, `httpbin.example.com`.
35+
+
36+
.Example gateway resource file
37+
[source,yaml,subs="attributes,verbatim"]
38+
----
39+
apiVersion: gateway.networking.k8s.io/v1
40+
kind: Gateway
41+
metadata:
42+
name: httpbin-gateway
43+
namespace: httpbin
44+
spec:
45+
gatewayClassName: istio
46+
listeners:
47+
- name: default
48+
hostname: "httpbin.example.com" # <1>
49+
port: 80
50+
protocol: HTTP
51+
allowedRoutes:
52+
namespaces:
53+
from: All
54+
----
55+
<1> Specifies the virtual hostname that clients use when attempting to access a mesh service on the associated port.
56+
57+
. Apply the YAML file by running the following command:
58+
+
59+
[source,terminal]
60+
----
61+
$ oc apply -f httpbin-gw.yaml
62+
----
63+
64+
. Create a YAML file named `httpbin-hr.yaml` that defines an `HTTPRoute` resource. The `HTTPRoute` resource specifies the rules that route traffic from the gateway proxy to the `httpbin` service.
65+
+
66+
.Example HTTPRoute file
67+
[source,yaml,subs="attributes,verbatim"]
68+
----
69+
apiVersion: gateway.networking.k8s.io/v1
70+
kind: HTTPRoute
71+
metadata:
72+
name: httpbin
73+
namespace: httpbin
74+
spec:
75+
parentRefs: # <1>
76+
- name: httpbin-gateway
77+
namespace: httpbin
78+
rules:
79+
- matches:
80+
- path:
81+
type: PathPrefix
82+
value: /status
83+
- path:
84+
type: PathPrefix
85+
value: /headers
86+
backendRefs: # <2>
87+
- name: httpbin
88+
port: 8000
89+
----
90+
<1> Binds the `HTTPROUTE` resource to the {k8s} Gateway resource that was created in the previous step by adding the name of the gateway resource to the list of gateways.
91+
<2> Routes the matching traffic to the `httpbin` service by defining a `backendRefs` that includes the name and port of the `httpbin` Service.
92+
93+
. Apply the YAML file by running the following command:
94+
+
95+
[source,terminal]
96+
----
97+
$ oc apply -f httpbin-hr.yaml
98+
----
99+
100+
. Ensure that the Gateway API service is ready, and that an address is allocated to the service, by running the following command:
101+
+
102+
[source,terminal]
103+
----
104+
$ oc wait --for=condition=programmed gtw httpbin-gateway -n httpbin
105+
----
106+
107+
.Verification
108+
109+
. Create a namespace for a `curl` client by running the following command:
110+
+
111+
[source,terminal]
112+
----
113+
$ oc create namespace curl
114+
----
115+
116+
. Deploy a `curl` client by running the following command:
117+
+
118+
[source,terminal]
119+
----
120+
$ oc apply -n curl -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/curl/curl.yaml
121+
----
122+
123+
. Set a `CURL_POD` variable with the name of the `curl` pod by running the following command:
124+
+
125+
[source,terminal]
126+
----
127+
$ CURL_POD=$(oc get pods -n curl -l app=curl -o jsonpath='{.items[*].metadata.name}')
128+
----
129+
130+
. Using the `curl` client, send a request to the `/headers` endpoint of the `httpbin` application through the ingress gateway `Service` resource. Set the Host header of the request to `httpbin.example.com` to match the host that the {k8s} Gateway and `HTTPROUTE` resources specify. Send the `curl` request by running the following command:
131+
+
132+
[source,terminal]
133+
----
134+
$ oc exec $CURL_POD -n curl -- \
135+
curl -s -I \
136+
-H Host:httpbin.example.com \
137+
<gateway_name>-istio.<gateway_namespace>.svc.cluster.local/headers
138+
----
139+
+
140+
The response should return a `200 OK` HTTP status, which indicates that the request was successful.
141+
+
142+
.Example output
143+
+
144+
[source,terminal]
145+
----
146+
HTTP/1.1 200 OK
147+
server: istio-envoy
148+
...
149+
----
150+
151+
. Send a `curl` request to an endpoint that does not have a corresponding Uniform Resource Identifier (URI) prefix match defined in the `httpbin` `HTTPROUTE` by running the following command:
152+
+
153+
[source,terminal]
154+
----
155+
$ oc exec $CURL_POD -n curl -- \
156+
curl -s -I \
157+
-H Host:httpbin.example.com \
158+
<gateway_name>-istio.<gateway_namespace>.svc.cluster.local/get
159+
----
160+
+
161+
The response returns a `404 Not Found` status. This is expected because the `/get` endpoint does not have a matching URI prefix in the `httpbin` `HTTPROUTE` resource.
162+
+
163+
.Example output
164+
+
165+
[source,terminal]
166+
----
167+
HTTP/1.1 404 Not Found
168+
server: istio-envoy
169+
...
170+
----
171+
172+
. Expose the gateway proxy to traffic outside the cluster by setting the `Service` type to `LoadBalancer`. Run the following command:
173+
+
174+
[source,terminal]
175+
----
176+
$ oc patch service <gateway_name>-istio -n <gateway_namespace> -p '{"spec": {"type": "LoadBalancer"}}'
177+
----
178+
+
179+
[NOTE]
180+
====
181+
A gateway can also be exposed to traffic outside the cluster by using {ocp-short-name} Routes. For more information, see "Exposing a gateway to traffic outside the cluster using {ocp-short-name} Routes".
182+
====
183+
184+
. Verify that the `httpbin` service can be accessed from outside the cluster when using the external hostname or IP address of the gateway Service resource. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment in which your cluster is running.
185+
186+
.. Set the `INGRESS_HOST` variable by running the following command:
187+
+
188+
[source,terminal]
189+
----
190+
$ export INGRESS_HOST=$(oc get gtw <gateway_name> -n <gateway_namespace> -o jsonpath='{.status.addresses[0].value}')
191+
----
192+
193+
.. Set the `INGRESS_PORT` variable by running the following command:
194+
+
195+
[source,terminal]
196+
----
197+
$ INGRESS_PORT=$(oc get gtw <gateway_name> -n <gateway_namespace> -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')
198+
----
199+
200+
.. Using the gateway host, send a `curl` request to the `httpbin` service by running the following command:
201+
+
202+
[source,terminal]
203+
----
204+
$ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST:$INGRESS_PORT/headers
205+
----
206+
207+
. Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful.
208+
209+
[role="_additional-resources"]
210+
.Additional resources
211+
212+
* link:https://kubernetes.io/docs/concepts/services-networking/gateway/[Kubernetes Gateway API concept] (Kubernetes documentation)

0 commit comments

Comments
 (0)