diff --git a/content/docs/main/integrations/istio/service-entry.md b/content/docs/main/integrations/istio/service-entry.md new file mode 100644 index 000000000..33bdd4ea6 --- /dev/null +++ b/content/docs/main/integrations/istio/service-entry.md @@ -0,0 +1,318 @@ +--- +title: ServiceEntries +weight: 20 # (Assuming a logical weight after External Auth, adjust as needed) +description: Register and route external services through kgateway using Istio ServiceEntries. +--- + +By creating a ServiceEntry, you can extend kgateway's capabilities to manage traffic for external services, even if they aren't a part of Istio's service registry. This allows you to apply traffic management, security, and observability features to a wider range of endpoints, such as virtual machines (VMs) communicating with services in your Kubernetes cluster. + +# ServiceEntries with kgateway + +An **[Istio ServiceEntry](https://istio.io/latest/docs/reference/config/networking/service-entry/)** is a Kubernetes custom resource that allows you to integrate and manage external services within your Istio service mesh. kgateway supports ServiceEntries for services residing outside your Kubernetes cluster. Whether it’s a legacy application, a third-party API, or a remote database, ServiceEntries allow you to treat these external dependencies as first-class citizens of your mesh, in addition to applying kgateway policies. + +The `ServiceEntry` resource offers flexible mechanisms to define how these external services are discovered and addressed, tailored to different operational needs: + +* **Static Endpoints:** Uses explicitly defined IP addresses or hostnames as endpoints. + +* **DNS Resolution:** Dynamically discovers endpoints by performing a DNS lookup on the specified host. + +* **Workload Selector:** Routes traffic to in-mesh workloads that match a specific set of Kubernetes labels. + +* **Workload Entry**: Integrates non-Kubernetes workloads, such as virtual machines or bare-metal servers, into the service mesh. + +## Before You Begin + +1. Follow the [Get started guide](https://kgateway.dev/docs/main/quickstart/) to install kgateway. +2. Follow the [Sample app guide](https://kgateway.dev/docs/main/operations/sample-app/) to create a gateway proxy with an HTTP listener and deploy the httpbin sample app. +3. Follow the [Istio documentation](https://istio.io/latest/docs/ambient/getting-started/) to install Istio and set up [Ambient Mesh](https://kgateway.dev/docs/main/integrations/istio/ambient/ambient-ingress/) in your cluster. +4. Label the `httpbin` namespace to add the httpbin sample-app to the ambient mode. +```sh +kubectl label ns httpbin istio.io/dataplane-mode=ambient +``` + +## Targeting ServiceEntry Backends with HTTPRoute and TrafficPolicies + +1. Create a Testing Namespace `gwtest` to deploy our Gateways, HTTPRoutes and ServiceEntries. + +```sh +kubectl create namespace gwtest +``` + +2. The `Gateway` resource, listens for HTTP traffic on port `8080`. The `HTTPRoute`, then matches incoming requests for the hostname and directs them to a backend specified as an Istio `ServiceEntry`. This separation of concerns means the ingress logic remains constant, while the `ServiceEntry` itself dictates the backend's discovery and resolution strategy. + +```yaml +kubectl apply -f - < + locality: r3/z3/sz3 +EOF +``` +--- +### 2\. DNS Resolution + +For external services hosted in dynamic cloud environments or those whose IP addresses are subject to change, DNS resolution is the recommended approach. This method eliminates the need for manual configuration updates, as Istio dynamically discovers and tracks the service's endpoints. + +The key here is `resolution: DNS`. The `ServiceEntry` relies on DNS lookups for the specified `hosts` (`se.example.com` in this case) to determine the service's current IP addresses. The `endpoints` field is intentionally omitted, as discovery is handled automatically. + +```yaml +kubectl apply -f - < | grep example-se + +``` +This command will show you a list of the configured endpoints for the example-se ServiceEntry, which should directly display 1.1.1.1, 2.2.2.2, and 3.3.3.3. This is the most robust way to prove the configuration is correctly loaded. + +----- + +### 2\. DNS Resolution + +For external services hosted in dynamic cloud environments or those whose IP addresses are subject to change, DNS resolution is the recommended approach. This method eliminates the need for manual configuration updates, as Istio dynamically discovers and tracks the service's endpoints. + +The key here is `resolution: DNS`. The `ServiceEntry` relies on DNS lookups for the specified `hosts` (`se.example.com` in this case) to determine the service's current IP addresses. The `endpoints` field is intentionally omitted, as discovery is handled automatically. + +```yaml +kubectl apply -f - < | grep "reviews-workloadentry" +# Test Traffic Flow +kubectl run -it test-pod --image=busybox:latest -- /bin/sh +curl -s http://se.example.com/health +``` +A successful response here proves that traffic is flowing correctly from your Kubernetes pod to the external VM. + +----- + +### 5\. Egress ServiceEntry (Outbound Traffic) + +While the primary examples in this document focus on using `ServiceEntry` resources as backends for `kgateway`'s ingress traffic, `ServiceEntry` is also crucial for managing outbound (Egress) traffic from services *within* your mesh. This allows you to apply Istio's policies to traffic leaving your cluster, ensuring consistency and control over external dependencies. + +Here's an example of a `ServiceEntry` that configures outbound access to `github.com` via HTTPS, demonstrating how to enable and manage Egress to a real-world external service. + +```yaml +kubectl apply -f - <