Service Entry

    The following example declares a few external APIs accessed by internal applications over HTTPS. The sidecar inspects the SNI value in the ClientHello message to route to the appropriate external service.

    The following configuration adds a set of MongoDB instances running on unmanaged VMs to Istio’s registry, so that these services can be treated as any other service in the mesh. The associated DestinationRule is used to initiate mTLS connections to the database instances.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: ServiceEntry
    3. metadata:
    4.   name: external-svc-mongocluster
    5. spec:
    6.   hosts:
    7.   - mymongodb.somedomain # not used
    8.   addresses:
    9.   - 192.192.192.192/24 # VIPs
    10.   ports:
    11.   - number: 27018
    12.     name: mongodb
    13.     protocol: MONGO
    14.   location: MESH_INTERNAL
    15.   resolution: STATIC
    16.   endpoints:
    17.   - address: 2.2.2.2
    18.   - address: 3.3.3.3

    and the associated DestinationRule

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: DestinationRule
    3. metadata:
    4.   name: mtls-mongocluster
    5. spec:
    6.   host: mymongodb.somedomain
    7.   trafficPolicy:
    8.     tls:
    9.       mode: MUTUAL
    10.       clientCertificate: /etc/certs/myclientcert.pem
    11.       privateKey: /etc/certs/client_private_key.pem
    12.       caCertificates: /etc/certs/rootcacerts.pem

    The following example uses a combination of service entry and TLS routing in a virtual service to steer traffic based on the SNI value to an internal egress firewall.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: ServiceEntry
    3. metadata:
    4.   name: external-svc-redirect
    5. spec:
    6.   hosts:
    7.   - wikipedia.org
    8.   - "*.wikipedia.org"
    9.   location: MESH_EXTERNAL
    10.   ports:
    11.   - number: 443
    12.     name: https
    13.     protocol: TLS
    14.   resolution: NONE

    And the associated VirtualService to route based on the SNI value.

    The virtual service with TLS match serves to override the default SNI match. In the absence of a virtual service, traffic will be forwarded to the wikipedia domains.

    The following example demonstrates the use of a dedicated egress gateway through which all external service traffic is forwarded. The ‘exportTo’ field allows for control over the visibility of a service declaration to other namespaces in the mesh. By default, a service is exported to all namespaces. The following example restricts the visibility to the current namespace, represented by “.”, so that it cannot be used by other namespaces.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: ServiceEntry
    3. metadata:
    4.   name: external-svc-httpbin
    5.   namespace : egress
    6. spec:
    7.   hosts:
    8.   exportTo:
    9.   - "."
    10.   location: MESH_EXTERNAL
    11.   ports:
    12.   - number: 80
    13.     name: http
    14.     protocol: HTTP
    15.   resolution: DNS

    Define a gateway to handle all egress traffic.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: Gateway
    3. metadata:
    4.  name: istio-egressgateway
    5.  namespace: istio-system
    6. spec:
    7.  selector:
    8.    istio: egressgateway
    10.  - port:
    11.      number: 80
    12.      name: http
    13.      protocol: HTTP
    14.    hosts:
    15.    - "*"

    And the associated VirtualService to route from the sidecar to the gateway service (istio-egressgateway.istio-system.svc.cluster.local), as well as route from the gateway to the external service. Note that the virtual service is exported to all namespaces enabling them to route traffic through the gateway to the external service. Forcing traffic to go through a managed middle proxy like this is a common practice.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: VirtualService
    3. metadata:
    4.   name: gateway-routing
    5.   namespace: egress
    6. spec:
    7.   hosts:
    8.   - httpbin.com
    9.   exportTo:
    10.   - "*"
    11.   gateways:
    12.   - mesh
    13.   - istio-egressgateway
    14.   http:
    15.   - match:
    16.     - port: 80
    17.       gateways:
    18.       - mesh
    19.     route:
    20.     - destination:
    21.         host: istio-egressgateway.istio-system.svc.cluster.local
    22.   - match:
    23.     - port: 80
    24.       gateways:
    25.       - istio-egressgateway
    26.     route:
    27.     - destination:
    28.         host: httpbin.com

    The following example demonstrates the use of wildcards in the hosts for external services. If the connection has to be routed to the IP address requested by the application (i.e. application resolves DNS and attempts to connect to a specific IP), the discovery mode must be set to NONE.

    The following example demonstrates a service that is available via a Unix Domain Socket on the host of the client. The resolution must be set to STATIC to use Unix address endpoints.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: ServiceEntry
    3. metadata:
    4.   name: unix-domain-socket-example
    5.   hosts:
    6.   - "example.unix.local"
    7.   location: MESH_EXTERNAL
    8.   ports:
    9.   - number: 80
    10.     name: http
    11.     protocol: HTTP
    12.   resolution: STATIC
    13.   endpoints:
    14.   - address: unix:///var/run/example/socket

    For HTTP-based services, it is possible to create a VirtualService backed by multiple DNS addressable endpoints. In such a scenario, the application can use the HTTP_PROXY environment variable to transparently reroute API calls for the VirtualService to a chosen backend. For example, the following configuration creates a non-existent external service called foo.bar.com backed by three domains: us.foo.bar.com:8080, uk.foo.bar.com:9080, and in.foo.bar.com:7080

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: ServiceEntry
    3. metadata:
    4.   name: external-svc-dns
    5. spec:
    6.   hosts:
    7.   - foo.bar.com
    8.   location: MESH_EXTERNAL
    9.   ports:
    10.   - number: 80
    11.     name: http
    12.     protocol: HTTP
    13.   resolution: DNS
    15.   - address: us.foo.bar.com
    16.     ports:
    17.       https: 8080
    18.   - address: uk.foo.bar.com
    19.     ports:
    20.       https: 9080
    21.   - address: in.foo.bar.com
    22.     ports:
    23.       https: 7080

    With HTTP_PROXY=http://localhost/, calls from the application to http://foo.bar.com will be load balanced across the three domains specified above. In other words, a call to http://foo.bar.com/baz would be translated to http://uk.foo.bar.com/baz.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: ServiceEntry
    3. metadata:
    4.   name: httpbin
    5.   namespace : httpbin-ns
    6. spec:
    7.   hosts:
    8.   - httpbin.com
    9.   location: MESH_INTERNAL
    10.   ports:
    11.   - number: 80
    12.     name: http
    13.     protocol: HTTP
    14.   resolution: STATIC
    15.   endpoints:
    16.   - address: 2.2.2.2
    17.   - address: 3.3.3.3
    18.   subjectAltNames:
    19.   - "spiffe://cluster.local/ns/httpbin-ns/sa/httpbin-service-account"

    ServiceEntry enables adding additional entries into Istio’s internal service registry.

    Endpoint defines a network address (IP or hostname) associated with the mesh service.

    Location specifies whether the service is part of Istio mesh or outside the mesh. Location determines the behavior of several features, such as service-to-service mTLS authentication, policy enforcement, etc. When communicating with services outside the mesh, Istio’s mTLS authentication is disabled, and policy enforcement is performed on the client-side as opposed to server-side.

    Resolution determines how the proxy will resolve the IP addresses of the network endpoints associated with the service, so that it can route to one of them. The resolution mode specified here has no impact on how the application resolves the IP address associated with the service. The application may still have to use DNS to resolve the service to an IP so that the outbound traffic can be captured by the Proxy. Alternatively, for HTTP services, the application could directly communicate with the proxy (e.g., by setting HTTP_PROXY) to talk to these services.