Service Entry (2024)

14 minute read

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

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

apiVersion: networking.istio.io/v1alpha3kind: ServiceEntrymetadata: name: external-svc-httpsspec: hosts: - api.dropboxapi.com - www.googleapis.com - api.facebook.com location: MESH_EXTERNAL ports: - number: 443 name: https protocol: TLS resolution: DNS

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

apiVersion: networking.istio.io/v1alpha3kind: ServiceEntrymetadata: name: external-svc-mongoclusterspec: hosts: - mymongodb.somedomain # not used addresses: - 192.192.192.192/24 # VIPs ports: - number: 27018 name: mongodb protocol: MONGO location: MESH_INTERNAL resolution: STATIC endpoints: - address: 2.2.2.2 - address: 3.3.3.3

and the associated DestinationRule

apiVersion: networking.istio.io/v1alpha3kind: DestinationRulemetadata: name: mtls-mongoclusterspec: host: mymongodb.somedomain trafficPolicy: tls: mode: MUTUAL clientCertificate: /etc/certs/myclientcert.pem privateKey: /etc/certs/client_private_key.pem caCertificates: /etc/certs/rootcacerts.pem

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

apiVersion: networking.istio.io/v1alpha3kind: VirtualServicemetadata: name: gateway-routing namespace: egressspec: hosts: - example.com exportTo: - "*" gateways: - mesh - istio-egressgateway http: - match: - port: 80 gateways: - mesh route: - destination: host: istio-egressgateway.istio-system.svc.cluster.local - match: - port: 80 gateways: - istio-egressgateway route: - destination: host: example.com

The following example demonstrates the use of wildcards in the hosts forexternal services. If the connection has to be routed to the IP addressrequested by the application (i.e. application resolves DNS and attemptsto connect to a specific IP), the resolution mode must be set to NONE.

apiVersion: networking.istio.io/v1alpha3kind: ServiceEntrymetadata: name: external-svc-wildcard-examplespec: hosts: - "*.bar.com" location: MESH_EXTERNAL ports: - number: 80 name: http protocol: HTTP resolution: NONE

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

apiVersion: networking.istio.io/v1alpha3kind: ServiceEntrymetadata: name: unix-domain-socket-examplespec: hosts: - "example.unix.local" location: MESH_EXTERNAL ports: - number: 80 name: http protocol: HTTP resolution: STATIC endpoints: - address: unix:///var/run/example/socket

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

apiVersion: networking.istio.io/v1alpha3kind: ServiceEntrymetadata: name: external-svc-dnsspec: hosts: - foo.bar.com location: MESH_EXTERNAL ports: - number: 80 name: http protocol: HTTP resolution: DNS endpoints: - address: us.foo.bar.com ports: http: 8080 - address: uk.foo.bar.com ports: http: 9080 - address: in.foo.bar.com ports: http: 7080

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

The following example illustrates the usage of a ServiceEntrycontaining a subject alternate namewhose format conforms to the SPIFFE standard:

apiVersion: networking.istio.io/v1alpha3kind: ServiceEntrymetadata: name: httpbin namespace : httpbin-nsspec: hosts: - example.com location: MESH_INTERNAL ports: - number: 80 name: http protocol: HTTP resolution: STATIC endpoints: - address: 2.2.2.2 - address: 3.3.3.3 subjectAltNames: - "spiffe://cluster.local/ns/httpbin-ns/sa/httpbin-service-account"

The following example demonstrates the use of ServiceEntry with aworkloadSelector to handle the migration of a servicedetails.bookinfo.com from VMs to Kubernetes. The service has twoVM-based instances with sidecars as well as a set of Kubernetespods managed by a standard deployment object. Consumers of thisservice in the mesh will be automatically load balanced across theVMs and Kubernetes.

apiVersion: networking.istio.io/v1alpha3kind: WorkloadEntrymetadata: name: details-vm-1spec: serviceAccount: details address: 2.2.2.2 labels: app: details instance-id: vm1---apiVersion: networking.istio.io/v1alpha3kind: WorkloadEntrymetadata: name: details-vm-2spec: serviceAccount: details address: 3.3.3.3 labels: app: details instance-id: vm2

Assuming there is also a Kubernetes deployment with pod labelsapp: details using the same service account details, thefollowing service entry declares a service spanning both VMs andKubernetes:

apiVersion: networking.istio.io/v1alpha3kind: ServiceEntrymetadata: name: details-svcspec: hosts: - details.bookinfo.com location: MESH_INTERNAL ports: - number: 80 name: http protocol: HTTP resolution: STATIC workloadSelector: labels: app: details

ServiceEntry

ServiceEntry enables adding additional entries into Istio’s internalservice registry.

Field	Type	Description	Required
`hosts`	`string[]`	The hosts associated with the ServiceEntry. Could be a DNSname with wildcard prefix. The hosts field is used to select matching hosts in VirtualServices and DestinationRules. For HTTP traffic the HTTP Host/Authority header will be matched against the hosts field. For HTTPs or TLS traffic containing Server Name Indication (SNI), the SNI valuewill be matched against the hosts field. NOTE 1: When resolution is set to type DNS and no endpointsare specified, the host field will be used as the DNS name of theendpoint to route traffic to. NOTE 2: If the hostname matches with the name of a servicefrom another service registry such as Kubernetes that alsosupplies its own set of endpoints, the ServiceEntry will betreated as a decorator of the existing Kubernetesservice. Properties in the service entry will be added to theKubernetes service if applicable. Currently, only the followingadditional properties will be considered by `istiod`: subjectAltNames: In addition to verifying the SANs of theservice accounts associated with the pods of the service, theSANs specified here will also be verified.	Yes
`addresses`	`string[]`	The virtual IP addresses associated with the service. Could be CIDRprefix. For HTTP traffic, generated route configurations will include http routedomains for both the `addresses` and `hosts` field values and the destination willbe 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 serviceif the destination IP matches the IP/CIDRs specified in the addressesfield. If the Addresses field is empty, traffic will be identifiedsolely based on the destination port. In such scenarios, the port onwhich the service is being accessed must not be shared by any otherservice in the mesh. In other words, the sidecar will behave as asimple TCP proxy, forwarding incoming traffic on a specified port tothe specified destination endpoint IP/host. Unix domain socketaddresses are not supported in this field.	No
`ports`	`ServicePort[]`	The ports associated with the external service. If theEndpoints are Unix domain socket addresses, there must be exactly oneport.	No
`location`	`Location`	Specify whether the service should be considered external to the meshor part of the mesh.	No
`resolution`	`Resolution`	Service resolution mode for the hosts. Care must be takenwhen setting the resolution mode to NONE for a TCP port withoutaccompanying IP addresses. In such cases, traffic to any IP onsaid port will be allowed (i.e. `0.0.0.0:<port>`).	No
`endpoints`	`WorkloadEntry[]`	One or more endpoints associated with the service. Only one of`endpoints` or `workloadSelector` can be specified.	No
`workloadSelector`	`WorkloadSelector`	Applicable only for MESH_INTERNAL services. Only one of`endpoints` or `workloadSelector` can be specified. Selects oneor more Kubernetes pods or VM workloads (specified using`WorkloadEntry`) based on their labels. The `WorkloadEntry` objectrepresenting the VMs should be defined in the same namespace asthe ServiceEntry.	No
`exportTo`	`string[]`	A list of namespaces to which this service is exported. Exporting a serviceallows it to be used by sidecars, gateways and virtual services defined inother namespaces. This feature provides a mechanism for service ownersand mesh administrators to control the visibility of services acrossnamespace boundaries. If no namespaces are specified then the service is exported to allnamespaces by default. The value “.” is reserved and defines an export to the same namespace thatthe service is declared in. Similarly the value “*” is reserved anddefines an export to all namespaces. For a Kubernetes Service, the equivalent effect can be achieved by settingthe annotation “networking.istio.io/exportTo” to a comma-separated listof namespace names.	No
`subjectAltNames`	`string[]`	If specified, the proxy will verify that the server certificate’ssubject alternate name matches one of the specified values. NOTE: When using the workloadEntry with workloadSelectors, theservice account specified in the workloadEntry will also be usedto derive the additional subject alternate names that should beverified.	No

ServicePort

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

Field	Type	Description	Required
`number`	`uint32`	A valid non-negative integer port number.	Yes
`protocol`	`string`	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 tothe destination without terminating the TLS connection.	No
`name`	`string`	Label assigned to the port.	Yes
`targetPort`	`uint32`	The port number on the endpoint where the traffic will bereceived. If unset, default to `number`.	No

ServiceEntry.Location

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

Name	Description
`MESH_EXTERNAL`	Signifies that the service is external to the mesh. Typically usedto indicate external services consumed through APIs.
`MESH_INTERNAL`	Signifies that the service is part of the mesh. Typically used toindicate services added explicitly as part of expanding the servicemesh to include unmanaged infrastructure (e.g., VMs added to aKubernetes based service mesh).

ServiceEntry.Resolution

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

Name	Description
`NONE`	Assume that incoming connections have already been resolved (to aspecific destination IP address). Such connections are typicallyrouted via the proxy using mechanisms such as IP table REDIRECT/eBPF. After performing any routing related transformations, theproxy will forward the connection to the IP address to which theconnection was bound.
`STATIC`	Use the static IP addresses specified in endpoints (see below) as thebacking instances associated with the service.
`DNS`	Attempt to resolve the IP address by querying the ambient DNS,asynchronously. If no endpoints are specified, the proxywill resolve the DNS address specified in the hosts field, ifwildcards are not used. If endpoints are specified, the DNSaddresses specified in the endpoints will be resolved to determinethe destination IP address. DNS resolution cannot be used with Unixdomain socket endpoints.
`DNS_ROUND_ROBIN`	Attempt to resolve the IP address by querying the ambient DNS,asynchronously. Unlike `DNS`, `DNS_ROUND_ROBIN` only uses thefirst IP address returned when a new connection needs to be initiatedwithout relying on complete results of DNS resolution, and connectionsmade to hosts will be retained even if DNS records change frequentlyeliminating draining connection pools and connection cycling.This is best suited for large web scale services thatmust be accessed via DNS. The proxy will resolve the DNS addressspecified in the hosts field, if wildcards are not used. DNS resolutioncannot be used with Unix domain socket endpoints.