diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 1b0d3c89a83e..65d887bd53c8 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -41,6 +41,8 @@ Topics: File: ossm-about-gateways - Name: Getting traffic into a mesh File: ossm-getting-traffic-into-a-mesh +- Name: Directing outbound traffic through a gateway + File: ossm-directing-outbound-traffic --- Name: Observability Dir: observability diff --git a/gateways/ossm-directing-outbound-traffic.adoc b/gateways/ossm-directing-outbound-traffic.adoc new file mode 100644 index 000000000000..34e8f1ba489f --- /dev/null +++ b/gateways/ossm-directing-outbound-traffic.adoc @@ -0,0 +1,12 @@ +:_content-type: ASSEMBLY +[id="ossm-directing-outbound-traffic-through-a-gateway"] += Directing outbound traffic through a gateway +include::_attributes/common-attributes.adoc[] +:context: ossm-directing-outbound-traffic-through-a-gateway + +toc::[] + +Using {istio} APIs, you can configure gateway proxies that were installed using gateway injection to direct traffic that is bound for an external service. + +include::modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc[leveloffset=+1] +include::modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc b/modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc new file mode 100644 index 000000000000..7b0bc0fd1467 --- /dev/null +++ b/modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc @@ -0,0 +1,8 @@ +// This procedure is used in the following assembly: +// * gateways/ossm-directing-outbound-traffic-through-a-gateway + +:_mod-docs-content-type: PROCEDURE +[id="ossm-about-directing-egress-traffic-through-a-gateway_{context}"] += About directing egress traffic through a gateway + +You can configure a gateway to define exit points from a mesh. This allows you to apply {istio} features, such as monitoring and route rules, to the traffic exiting the mesh. \ No newline at end of file diff --git a/modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc b/modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc new file mode 100644 index 000000000000..25cfd8227f60 --- /dev/null +++ b/modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc @@ -0,0 +1,233 @@ +// This procedure is used in the following assembly: +// * gateways/ossm-directing-outbound-traffic-through-a-gateway + +:_mod-docs-content-type: PROCEDURE +[id="ossm-directing-egress-traffic-through-a-gateway-using-istio-apis_{context}"] += Directing egress traffic through a gateway using Istio APIs + +Use {istio} APIs to direct outbound HTTP traffic through a gateway that was installed using gateway injection. + +.Prerequisites + +* You have installed a gateway using gateway injection. + +.Procedure + +. Create a namespace called `curl` by running the following command: ++ +[source,terminal] +---- +$ oc create namespace curl +---- + +. Depending on the update strategy you are using, enable sidecar injection in the namespace by running the appropriate commands: + +.. If you are using the `InPlace` update strategy, run the following command: ++ +[source,terminal] +---- +$ oc label namespace curl istio-injection=enabled +---- + +.. If you are using the `RevisionBased` update strategy, run the following commands: + +... Display the revision name by running the following command: ++ +[source,terminal] +---- +$ oc get istiorevisions.sailoperator.io +---- ++ +.Example output +[source,terminal] +---- +NAME TYPE READY STATUS IN USE VERSION AGE +default-v1-23-0 Local True Healthy True v1.23.0 3m33s +---- + +... Label the namespace with the revision name to enable sidecar injection by running the following command: ++ +[source,terminal] +---- +$ oc label namespace curl istio.io/rev=default-v1-23-0 +---- + + +. Deploy a `curl` application by running the following command: ++ +[source,terminal] +---- +$ oc apply -n curl -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/curl/curl.yaml +---- + +. Export a `CURL_POD` environment variable that has been initialized with the name of the curl pod: ++ +[source,terminal] +---- +$ export CURL_POD=$(oc get pod -n curl -l app=curl -o jsonpath='{.items[0].metadata.name}') +---- + +. Create a YAML file named `http-se.yaml` that directs traffic from the mesh to an external service. The following example defines a `ServiceEntry` for a URL. ++ +.Example configuration +[source,yaml,subs="attributes,verbatim"] +---- +apiVersion: networking.istio.io/v1 +kind: ServiceEntry +metadata: + name: egress-se + namespace: curl +spec: + hosts: + - docs.redhat.com + ports: + - number: 80 + name: http-port + protocol: HTTP + location: MESH_EXTERNAL + resolution: DNS +---- + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f http-se.yaml +---- + +. Ensure the `ServiceEntry` configuration was applied correctly. Send an HTTP request to the host that you specified in the previous step by running the following command: ++ +[source,terminal] +---- +$ oc exec "$CURL_POD" -n curl -c curl -- curl -sSL -o /dev/null -D - http://docs.redhat.com +---- ++ +This command should return HTTP status codes, such as `301` (redirect) or `200` (success), indicating that the connection works. + +. Create a YAML file named `http-gtw.yaml` that creates an egress `Gateway` and routes traffic from the mesh to the host specified for the external service. ++ +.Example configuration +[source,yaml,subs="attributes,verbatim"] +---- +apiVersion: networking.istio.io/v1alpha3 +kind: Gateway +metadata: + name: egress-gw + namespace: # Namespace where the egress gateway is deployed +spec: + selector: + istio: # Selects the egress-gateway instance to handle this traffic + servers: + - port: + number: 80 + name: http + protocol: HTTP + hosts: + - docs.redhat.com # External service host, not a full URL. +--- +apiVersion: networking.istio.io/v1alpha3 +kind: DestinationRule +metadata: + name: egress-dr + namespace: # Namespace where the egress gateway is deployed +spec: + host: ..svc.cluster.local + subsets: + - name: rh-docs +---- + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f http-gtw.yaml +---- + +. Create a YAML file named `http-vs.yaml` that sets up a `VirtualService` to manage the flow of traffic from the application sidecars through the egress gateway to the external host. ++ +.Example configuration +[source,yaml,subs="attributes,verbatim"] +---- +apiVersion: networking.istio.io/v1alpha3 +kind: VirtualService +metadata: + name: egress-vs + namespace: curl # Namespace where the curl pod is running +spec: + hosts: + - docs.redhat.com # External service host, not a full URL. + gateways: + - mesh + - /egress-gw # Egress gateway name defined in the file that you used in the previous step. + http: + - match: + - gateways: + - mesh + port: 80 + route: + - destination: + host: ..svc.cluster.local + subset: rh-docs + port: + number: 80 + weight: 100 + - match: + - gateways: + - /egress-gw # Egress gateway name defined in the file that you used in the previous step. + port: 80 + route: + - destination: + host: docs.redhat.com + port: + number: 80 + weight: 100 +---- + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f http-vs.yaml +---- + +. Resend the HTTP request to the URL: ++ +[source,terminal] +---- +$ oc exec "$CURL_POD" -n curl -c curl -- curl -sSL -o /dev/null -D - http://docs.redhat.com +---- ++ +The terminal should display information similar to the following output: ++ +.Example output +[source,terminal] +---- +... +HTTP/1.1 301 Moved Permanently +... +location: +... + +HTTP/2 200 +Content-Type: text/html; charset=utf-8 +---- + +. Ensure that the request was routed through the gateway by running the following command: ++ +[source,terminal] +---- +$ oc logs deployment/ -n | tail -1 +---- ++ +[NOTE] +==== +Access logging must be enabled for this verification step to work. You can enable access logging to the standard output by setting the `spec.values.meshConfig.accessLogFile` field to `/dev/stdout` in the {istio} resource. +==== ++ +The terminal should display information similar to the following output: ++ +.Example output +[source,terminal] +---- +[2024-11-07T14:35:52.428Z] "GET / HTTP/2" 301 - via_upstream - "-" 0 0 24 24 "10.128.2.30" "curl/8.11.0" "79551af2-341b-456d-b414-9220b487a03b" "docs.redhat.com" "23.55.176.201:80" outbound|80||docs.redhat.com 10.128.2.29:49766 10.128.2.29:80 10.128.2.30:38296 - +---- \ No newline at end of file