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.

    1. apiVersion: networking.istio.io/v1beta1
    2. kind: ServiceEntry
    3. metadata:
    4.   name: external-svc-https
    5. spec:
    6.   hosts:
    7.   - api.dropboxapi.com
    8.   - www.googleapis.com
    9.   - api.facebook.com
    10.   location: MESH_EXTERNAL
    11.   ports:
    12.   - number: 443
    13.     name: https
    14.     protocol: TLS
    15.   resolution: DNS

    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
    1. apiVersion: networking.istio.io/v1beta1
    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
    1. apiVersion: networking.istio.io/v1beta1
    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
    1. apiVersion: networking.istio.io/v1beta1
    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.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: VirtualService
    3. metadata:
    4.   name: tls-routing
    5. spec:
    6.   hosts:
    7.   - wikipedia.org
    8.   - "*.wikipedia.org"
    9.   tls:
    10.   - match:
    11.     - sniHosts:
    12.       - wikipedia.org
    13.       - "*.wikipedia.org"
    14.     route:
    15.     - destination:
    16.         host: internal-egress-firewall.ns1.svc.cluster.local

    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.   - httpbin.com
    9.   exportTo:
    10.   - "."
    11.   location: MESH_EXTERNAL
    12.   ports:
    13.   - number: 80
    14.     name: http
    15.     protocol: HTTP
    16.   resolution: DNS
    1. apiVersion: networking.istio.io/v1beta1
    2. kind: ServiceEntry
    3. metadata:
    4.   namespace : egress
    5. spec:
    6.   hosts:
    7.   - httpbin.com
    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
    6. spec:
    7.  selector:
    8.    istio: egressgateway
    9.  servers:
    10.  - port:
    11.      number: 80
    12.      name: http
    13.      protocol: HTTP
    14.    hosts:
    15.    - "*"
    1. apiVersion: networking.istio.io/v1beta1
    2. kind: Gateway
    3. metadata:
    4.  name: istio-egressgateway
    5.  namespace: istio-system
    6. spec:
    7.  selector:
    8.    istio: egressgateway
    9.  servers:
    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
    1. apiVersion: networking.istio.io/v1beta1
    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.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: ServiceEntry
    3. metadata:
    4.   name: external-svc-wildcard-example
    5. spec:
    6.   hosts:
    7.   - "*.bar.com"
    8.   location: MESH_EXTERNAL
    9.   ports:
    10.   - number: 80
    11.     name: http
    12.     protocol: HTTP
    13.   resolution: NONE
    1. apiVersion: networking.istio.io/v1beta1
    2. kind: ServiceEntry
    3. metadata:
    4.   name: external-svc-wildcard-example
    5. spec:
    6.   hosts:
    7.   - "*.bar.com"
    8.   location: MESH_EXTERNAL
    9.   ports:
    10.   - number: 80
    11.     name: http
    12.     protocol: HTTP
    13.   resolution: 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/v1beta1
    2. kind: ServiceEntry
    3. metadata:
    4.   name: unix-domain-socket-example
    5. spec:
    6.   hosts:
    7.   - "example.unix.local"
    8.   location: MESH_EXTERNAL
    9.   ports:
    10.   - number: 80
    11.     name: http
    12.     protocol: HTTP
    13.   resolution: STATIC
    14.   endpoints:
    15.   - 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.   name: external-svc-dns
    4. spec:
    5.   hosts:
    6.   - foo.bar.com
    7.   location: MESH_EXTERNAL
    8.   ports:
    9.   - number: 80
    10.     name: http
    11.     protocol: HTTP
    12.   resolution: DNS
    13.   endpoints:
    14.   - address: us.foo.bar.com
    15.     ports:
    16.       http: 8080
    17.   - address: uk.foo.bar.com
    18.     ports:
    19.       http: 9080
    20.   - address: in.foo.bar.com
    21.     ports:
    22.       http: 7080
    1. apiVersion: networking.istio.io/v1beta1
    2. kind: ServiceEntry
    3. metadata:
    4.   name: external-svc-dns
    5. spec:
    6.   hosts:
    8.   location: MESH_EXTERNAL
    9.   ports:
    10.   - number: 80
    11.     name: http
    12.     protocol: HTTP
    13.   resolution: DNS
    14.   endpoints:
    15.   - address: us.foo.bar.com
    16.     ports:
    17.       http: 8080
    18.   - address: uk.foo.bar.com
    19.     ports:
    20.       http: 9080
    21.   - address: in.foo.bar.com
    22.     ports:
    23.       http: 7080

    The following example illustrates the usage of a ServiceEntry containing a subject alternate name whose format conforms to the :

    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"
    1. apiVersion: networking.istio.io/v1beta1
    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"

    The following example demonstrates the use of ServiceEntry with a workloadSelector to handle the migration of a service details.bookinfo.com from VMs to Kubernetes. The service has two VM-based instances with sidecars as well as a set of Kubernetes pods managed by a standard deployment object. Consumers of this service in the mesh will be automatically load balanced across the VMs and Kubernetes. VM for the details.bookinfo.com service. This VM has sidecar installed and bootstrapped using the details-legacy service account. The sidecar receives HTTP traffic on port 80 (wrapped in istio mutual TLS) and forwards it to the application on the localhost on the same port.

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: WorkloadEntry
    3. metadata:
    4.   name: details-vm-1
    5. spec:
    6.   serviceAccount: details
    7.   address: 2.2.2.2
    8.   labels:
    9.     app: details
    10.     instance-id: vm1
    11. ---
    12. apiVersion: networking.istio.io/v1alpha3
    13. kind: WorkloadEntry
    14. metadata:
    15.   name: details-vm-2
    16. spec:
    17.   serviceAccount: details
    18.   address: 3.3.3.3
    19.   labels:
    20.     app: details
    21.     instance-id: vm2
    1. apiVersion: networking.istio.io/v1beta1
    2. kind: WorkloadEntry
    3. metadata:
    4.   name: details-vm-1
    5. spec:
    6.   serviceAccount: details
    7.   address: 2.2.2.2
    8.   labels:
    9.     app: details
    10.     instance-id: vm1
    11. ---
    12. apiVersion: networking.istio.io/v1beta1
    13. kind: WorkloadEntry
    14. metadata:
    15.   name: details-vm-2
    16. spec:
    17.   serviceAccount: details
    18.   address: 3.3.3.3
    19.   labels:
    20.     app: details
    21.     instance-id: vm2

    Assuming there is also a Kubernetes deployment with pod labels app: details using the same service account details, the following service entry declares a service spanning both VMs and Kubernetes:

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: ServiceEntry
    3. metadata:
    4.   name: details-svc
    5. spec:
    6.   hosts:
    7.   - details.bookinfo.com
    8.   location: MESH_INTERNAL
    9.   ports:
    10.   - number: 80
    11.     name: http
    12.     protocol: HTTP
    13.   resolution: STATIC
    14.   workloadSelector:
    15.     labels:
    16.       app: details

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

    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.