Service Entry

Service Entry

ServiceEntry enables adding additional entries into Istio’s internalservice registry, so that auto-discovered services in the mesh canaccess/route to these manually specified services. A service entrydescribes the properties of a service (DNS name, VIPs, ports, protocols,endpoints). These services could be external to the mesh (e.g., webAPIs) or mesh-internal services that are not part of the platform’sservice registry (e.g., a set of VMs talking to services in Kubernetes).

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/v1alpha3
kind: ServiceEntry
metadata:
  name: external-svc-https
spec:
  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/v1alpha3
kind: ServiceEntry
metadata:
  name: external-svc-mongocluster
spec:
  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/v1alpha3
kind: DestinationRule
metadata:
  name: mtls-mongocluster
spec:
  host: mymongodb.somedomain
  trafficPolicy:
    tls:
      mode: MUTUAL
      clientCertificate: /etc/certs/myclientcert.pem
      privateKey: /etc/certs/client_private_key.pem
      caCertificates: /etc/certs/rootcacerts.pem

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

apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
  name: external-svc-redirect
spec:
  hosts:
  - wikipedia.org
  - "*.wikipedia.org"
  location: MESH_EXTERNAL
  ports:
  - number: 443
    name: https
    protocol: TLS
  resolution: NONE

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

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: tls-routing
spec:
  hosts:
  - wikipedia.org
  - "*.wikipedia.org"
  tls:
  - match:
    - sniHosts:
      - wikipedia.org
      - "*.wikipedia.org"
    route:
    - destination:
        host: internal-egress-firewall.ns1.svc.cluster.local

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

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

apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
  name: external-svc-httpbin
  namespace : egress
spec:
  hosts:
  - httpbin.com
  exportTo:
  - "."
  location: MESH_EXTERNAL
  ports:
  - number: 80
    name: http
    protocol: HTTP
  resolution: DNS

Define a gateway to handle all egress traffic.

apiVersion: networking.istio.io/v1alpha3
kind: Gateway
metadata:
 name: istio-egressgateway
 namespace: istio-system
spec:
 selector:
   istio: egressgateway
 servers:
 - port:
     number: 80
     name: http
     protocol: HTTP
   hosts:
   - "*"

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/v1alpha3
kind: VirtualService
metadata:
  name: gateway-routing
  namespace: egress
spec:
  hosts:
  - httpbin.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: httpbin.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 discovery mode must be set to NONE.

apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
  name: external-svc-wildcard-example
spec:
  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/v1alpha3
kind: ServiceEntry
metadata:
  name: unix-domain-socket-example
spec:
  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/v1alpha3
kind: ServiceEntry
metadata:
  name: external-svc-dns
spec:
  hosts:
  - foo.bar.com
  location: MESH_EXTERNAL
  ports:
  - number: 80
    name: http
    protocol: HTTP
  resolution: DNS
  endpoints:
  - address: us.foo.bar.com
    ports:
      https: 8080
  - address: uk.foo.bar.com
    ports:
      https: 9080
  - address: in.foo.bar.com
    ports:
      https: 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/v1alpha3
kind: ServiceEntry
metadata:
  name: httpbin
  namespace : httpbin-ns
spec:
  hosts:
  - httpbin.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"

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 that when resolution is set to type DNSand no endpoints are specified, the host field will be used as the DNS nameof the endpoint to route traffic to.	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`	`Port[]`	The ports associated with the external service. If theEndpoints are Unix domain socket addresses, there must be exactly oneport.	Yes
`location`	`Location`	Specify whether the service should be considered external to the meshor part of the mesh.	No
`resolution`	`Resolution`	Service discovery 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:).	Yes
`endpoints`	`Endpoint[]`	One or more endpoints associated with the service.	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.NOTE: in the current release, the `exportTo` value is restricted to“.” or “” (i.e., the current namespace or all namespaces).	No
`subjectAltNames`	`string[]`	The list of subject alternate names allowed for workload instances thatimplement this service. This information is used to enforcesecure-naming.If specified, the proxy will verify that the servercertificate’s subject alternate name matches one of the specified values.	No

ServiceEntry.Endpoint

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

Field	Type	Description	Required
`address`	`string`	Address associated with the network endpoint without theport. Domain names can be used if and only if the resolution is setto DNS, and must be fully-qualified without wildcards. Use the formunix:///absolute/path/to/socket for Unix domain socket endpoints.	Yes
`ports`	`map<string, uint32>`	Set of ports associated with the endpoint. The ports must beassociated with a port name that was declared as part of theservice. Do not use for `unix://` addresses.	No
`labels`	`map<string, string>`	One or more labels associated with the endpoint.	No
`network`	`string`	Network enables Istio to group endpoints resident in the same L3domain/network. All endpoints in the same network are assumed to bedirectly reachable from one another. When endpoints in differentnetworks cannot reach each other directly, an Istio Gateway can beused to establish connectivity (usually using theAUTO_PASSTHROUGH mode in a Gateway Server). This isan advanced configuration used typically for spanning an Istio meshover multiple clusters.	No
`locality`	`string`	The locality associated with the endpoint. A locality correspondsto a failure domain (e.g., country/region/zone). Arbitrary failuredomain hierarchies can be represented by separating eachencapsulating failure domain by /. For example, the locality of anan endpoint in US, in US-East-1 region, within availability zoneaz-1, in data center rack r11 can be represented asus/us-east-1/az-1/r11. Istio will configure the sidecar to route toendpoints within the same locality as the sidecar. If none of theendpoints in the locality are available, endpoints parent locality(but within the same network ID) will be chosen. For example, ifthere are two endpoints in same network (networkID “n1”), say e1with locality us/us-east-1/az-1/r11 and e2 with localityus/us-east-1/az-2/r12, a sidecar from us/us-east-1/az-1/r11 localitywill prefer e1 from the same locality over e2 from a differentlocality. Endpoint e2 could be the IP associated with a gateway(that bridges networks n1 and n2), or the IP associated with astandard service endpoint.	No
`weight`	`uint32`	The load balancing weight associated with the endpoint. Endpointswith higher weights will receive proportionally higher traffic.	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,during request processing. 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.