Service Entry

ServiceEntry enables adding additional entries into Istio’s internal service registry, so that auto-discovered services in the mesh can access/route to these manually specified services. A service entry describes the properties of a service (DNS name, VIPs, ports, protocols, endpoints). These services could be external to the mesh (e.g., web APIs) or mesh-internal services that are not part of the platform’s service registry (e.g., a set of VMs talking to services in Kubernetes). In addition, the endpoints of a service entry can also be dynamically selected by using the workloadSelector field. These endpoints can be VM workloads declared using the WorkloadEntry object or Kubernetes pods. The ability to select both pods and VMs under a single service allows for migration of services from VMs to Kubernetes without having to change the existing DNS names associated with the services.

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/v1alpha3
  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
  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
  1. apiVersion: networking.istio.io/v1beta1
  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. - example.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. name: external-svc-httpbin
  5. namespace : egress
  6. spec:
  7. hosts:
  8. - example.com
  9. exportTo:
  10. - "."
  11. location: MESH_EXTERNAL
  12. ports:
  13. - number: 80
  14. name: http
  15. protocol: HTTP
  16. 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
  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. - example.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: example.com
  1. apiVersion: networking.istio.io/v1beta1
  2. kind: VirtualService
  3. metadata:
  4. name: gateway-routing
  5. namespace: egress
  6. spec:
  7. hosts:
  8. - example.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: example.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 resolution 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/v1alpha3
  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
  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. 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
  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
  1. apiVersion: networking.istio.io/v1beta1
  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
  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

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.

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

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: ServiceEntry
  3. metadata:
  4. name: httpbin
  5. namespace : httpbin-ns
  6. spec:
  7. hosts:
  8. - example.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. - example.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.

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

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

FieldTypeDescriptionRequired
hostsstring[]

The hosts associated with the ServiceEntry. Could be a DNS name with wildcard prefix.

  1. The hosts field is used to select matching hosts in VirtualServices and DestinationRules.
  2. For HTTP traffic the HTTP Host/Authority header will be matched against the hosts field.
  3. For HTTPs or TLS traffic containing Server Name Indication (SNI), the SNI value will be matched against the hosts field.

NOTE 1: When resolution is set to type DNS and no endpoints are specified, the host field will be used as the DNS name of the endpoint to route traffic to.

NOTE 2: If the hostname matches with the name of a service from another service registry such as Kubernetes that also supplies its own set of endpoints, the ServiceEntry will be treated as a decorator of the existing Kubernetes service. Properties in the service entry will be added to the Kubernetes service if applicable. Currently, only the following additional properties will be considered by istiod:

  1. subjectAltNames: In addition to verifying the SANs of the service accounts associated with the pods of the service, the SANs specified here will also be verified.
Yes
addressesstring[]

The virtual IP addresses associated with the service. Could be CIDR prefix. For HTTP traffic, generated route configurations will include http route domains for both the addresses and hosts field values and the destination will be identified based on the HTTP Host/Authority header. If one or more IP addresses are specified, the incoming traffic will be identified as belonging to this service if the destination IP matches the IP/CIDRs specified in the addresses field. If the Addresses field is empty, traffic will be identified solely based on the destination port. In such scenarios, the port on which the service is being accessed must not be shared by any other service in the mesh. In other words, the sidecar will behave as a simple TCP proxy, forwarding incoming traffic on a specified port to the specified destination endpoint IP/host. Unix domain socket addresses are not supported in this field.

No
portsServicePort[]

The ports associated with the external service. If the Endpoints are Unix domain socket addresses, there must be exactly one port.

Yes
locationLocation

Specify whether the service should be considered external to the mesh or part of the mesh.

No
resolutionResolution

Service resolution mode for the hosts. Care must be taken when setting the resolution mode to NONE for a TCP port without accompanying IP addresses. In such cases, traffic to any IP on said port will be allowed (i.e. 0.0.0.0:<port>).

Yes
endpointsWorkloadEntry[]

One or more endpoints associated with the service. Only one of endpoints or workloadSelector can be specified.

No
workloadSelectorWorkloadSelector

Applicable only for MESH_INTERNAL services. Only one of endpoints or workloadSelector can be specified. Selects one or more Kubernetes pods or VM workloads (specified using WorkloadEntry) based on their labels. The WorkloadEntry object representing the VMs should be defined in the same namespace as the ServiceEntry.

No
exportTostring[]

A list of namespaces to which this service is exported. Exporting a service allows it to be used by sidecars, gateways and virtual services defined in other namespaces. This feature provides a mechanism for service owners and mesh administrators to control the visibility of services across namespace boundaries.

If no namespaces are specified then the service is exported to all namespaces by default.

The value “.” is reserved and defines an export to the same namespace that the service is declared in. Similarly the value “*” is reserved and defines an export to all namespaces.

For a Kubernetes Service, the equivalent effect can be achieved by setting the annotation “networking.istio.io/exportTo” to a comma-separated list of namespace names.

No
subjectAltNamesstring[]

If specified, the proxy will verify that the server certificate’s subject alternate name matches one of the specified values.

NOTE: When using the workloadEntry with workloadSelectors, the service account specified in the workloadEntry will also be used to derive the additional subject alternate names that should be verified.

No

ServicePort

ServicePort describes the properties of a specific port of a service.

FieldTypeDescriptionRequired
numberuint32

A valid non-negative integer port number.

Yes
protocolstring

The protocol exposed on the port. MUST BE one of HTTP|HTTPS|GRPC|HTTP2|MONGO|TCP|TLS. TLS implies the connection will be routed based on the SNI header to the destination without terminating the TLS connection.

Yes
namestring

Label assigned to the port.

Yes
targetPortuint32

The port number on the endpoint where the traffic will be received. If unset, default to number.

No

ServiceEntry.Location

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.

NameDescription
MESH_EXTERNAL

Signifies that the service is external to the mesh. Typically used to indicate external services consumed through APIs.

MESH_INTERNAL

Signifies that the service is part of the mesh. Typically used to indicate services added explicitly as part of expanding the service mesh to include unmanaged infrastructure (e.g., VMs added to a Kubernetes based service mesh).

ServiceEntry.Resolution

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.

NameDescription
NONE

Assume that incoming connections have already been resolved (to a specific destination IP address). Such connections are typically routed via the proxy using mechanisms such as IP table REDIRECT/ eBPF. After performing any routing related transformations, the proxy will forward the connection to the IP address to which the connection was bound.

STATIC

Use the static IP addresses specified in endpoints (see below) as the backing instances associated with the service.

DNS

Attempt to resolve the IP address by querying the ambient DNS, asynchronously. If no endpoints are specified, the proxy will resolve the DNS address specified in the hosts field, if wildcards are not used. If endpoints are specified, the DNS addresses specified in the endpoints will be resolved to determine the destination IP address. DNS resolution cannot be used with Unix domain socket endpoints.

DNS_ROUND_ROBIN

Attempt to resolve the IP address by querying the ambient DNS, asynchronously. Unlike DNS, DNS_ROUND_ROBIN only uses the first IP address returned when a new connection needs to be initiated without relying on complete results of DNS resolution, and connections made to hosts will be retained even if DNS records change frequently eliminating draining connection pools and connection cycling. This is best suited for large web scale services that must be accessed via DNS. The proxy will resolve the DNS address specified in the hosts field, if wildcards are not used. DNS resolution cannot be used with Unix domain socket endpoints.