Service Entry CRD reference-Alibaba Cloud Service Mesh-阿里云帮助中心

A Service Entry adds an entry to the internal service registry of Istio so that services in the mesh can access or route traffic to these manually specified services. A Service Entry describes the properties of a service, such as its DNS name, virtual IP addresses (VIPs), ports, protocol, and endpoints. These services can be external to the mesh, such as a web API, or internal services that are not part of the cluster's service registry. You can also use the workloadSelector field to dynamically select the endpoints for a Service Entry. These endpoints can be workloads declared using WorkloadEntry objects or Kubernetes pods. This topic provides configuration examples and field descriptions for a Service Entry.

Configuration examples

Example 1: Access an external API over HTTPS from an internal application

The following example shows how an internal application can access external APIs over HTTPS. The sidecar inspects the Server Name Indication (SNI) value in the ClientHello message to route traffic to the appropriate external service.

Expand to view the ServiceEntry YAML

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

Example 2: Use a service entry with TLS routing in a virtual service

The following example shows how to use a service entry with TLS routing in a virtual service to route traffic to an internal egress firewall based on the SNI value.

Expand to view the ServiceEntry YAML

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

Expand to view the VirtualService YAML

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

Example 3: Forward all traffic for external services through a dedicated egress gateway

The following example shows how to forward all traffic for external services through a dedicated egress gateway. The exportTo field controls the visibility of the Service Entry to other namespaces in the mesh. By default, the service is exported to all namespaces. The following example restricts visibility to the current namespace, which is represented by `.`, preventing other namespaces from using it.

Expand to view the ServiceEntry YAML

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

Expand to view the Gateway YAML

The Gateway defines a gateway to handle all egress traffic.

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

Expand to view the VirtualService YAML

The VirtualService routes traffic from the sidecar to the gateway service (istio-egressgateway.istio-system.svc.cluster.local) and from the gateway to the external service. The virtual service is exported to all namespaces, which allows them to route traffic to the external service through the gateway. Forcing traffic destined for external services to pass through a managed middle proxy is a common practice for traffic control.

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: gateway-routing
  namespace: egress
spec:
  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

Example 4: Use a wildcard character in the host of an external service

The following example shows how to use a wildcard character in the host of an external service. If the connection must be routed to the IP address requested by the application (that is, the application resolves the DNS and attempts to connect to a specific IP), you must set the resolution mode to NONE.

Expand to view the ServiceEntry YAML

apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: external-svc-wildcard-example
spec:
  hosts:
  - "*.bar.com"
  location: MESH_EXTERNAL
  ports:
  - number: 80
    name: http
    protocol: HTTP
  resolution: NONE

Example 5: Obtain a service through a Unix domain socket on the client host

The following example shows how to access a service through a Unix domain socket on the client host. To use a Unix address endpoint, you must set resolution to STATIC.

Expand to view the ServiceEntry YAML

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

Example 6: Create a VirtualService for an HTTP service backed by multiple DNS-addressable endpoints

For HTTP-based services, you can create a VirtualService backed by multiple DNS-addressable endpoints. In this case, the application can use the HTTP_PROXY environment variable to transparently reroute API calls for the VirtualService to a selected backend. For example, the following configuration creates a non-existent external service named foo.bar.com that is backed by three domain names: us.foo.bar.com:8080, uk.foo.bar.com:9080, and in.foo.bar.com:7080. When HTTP_PROXY=http://localhost/, application calls to http://foo.bar.com are load balanced across the three domains. For example, a call to http://foo.bar.com/baz might be converted to http://uk.foo.bar.com/baz.

Expand to view the ServiceEntry YAML

apiVersion: networking.istio.io/v1beta1
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:
      http: 8080
  - address: uk.foo.bar.com
    ports:
      http: 9080
  - address: in.foo.bar.com
    ports:
      http: 7080

Example 7: ServiceEntry with a SPIFFE-compliant subject alternative name

Expand to view the ServiceEntry YAML

apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: httpbin
  namespace : httpbin-ns
spec:
  hosts:
  - example.com
  location: MESH_INTERNAL
  ports:
  - number: 80
    name: http
    protocol: HTTP
  resolution: STATIC
  endpoints:
  - address: 2.2.X.X
  - address: 3.3.X.X
  subjectAltNames:
  - "spiffe://cluster.local/ns/httpbin-ns/sa/httpbin-service-account"

Field descriptions

ServiceEntry

A ServiceEntry adds service records to the internal service registry of Service Mesh.

Field

Type

Required

Description

hosts

string[]

Yes

The hosts associated with the ServiceEntry. DNS names with a wildcard prefix are supported.

The hosts field is used to select matching hosts in VirtualServices and DestinationRules.
For HTTP traffic, the HTTP Host and Authority headers are matched against the hosts field.
For HTTPS or TLS traffic that includes Server Name Indication (SNI), the SNI value is matched against the hosts field.

Note the following about this field:

When resolution is set to DNS and no endpoints are specified, the hosts field is used as the DNS name of the endpoint to which traffic is routed.
If a hostname matches a service name in another service registry, such as Kubernetes, and that service registry also provides its own set of endpoints, the ServiceEntry is treated as a supplement to the existing Kubernetes service. If the ServiceEntry provides additional properties that can be added to the Kubernetes service, those properties are added. Currently, only adding subject alternative names (SANs) is supported. This property means that in addition to verifying the SAN of the ServiceAccount associated with the service's pods, the SANs specified here are also verified.

addresses

string[]

The virtual IP addresses or CIDR prefixes associated with the service. This field does not support Unix domain socket addresses. For HTTP traffic, the generated routing configuration includes HTTP routing domains for the values in the addresses and hosts fields, and identifies the destination based on the HTTP Host and Authority headers.

If one or more IP addresses are specified, incoming traffic is identified as belonging to this service if the destination IP matches an IP or CIDR specified in the addresses field.
If the addresses field is empty, traffic is identified based only on the destination port. In this case, the port used to access the service cannot be shared with any other service in the mesh. The sidecar acts as a simple TCP proxy, forwarding incoming traffic on the specified port to the specified destination endpoint IP or host.

ports

ServicePort[]

Yes

The ports associated with the ServiceEntry. If endpoints is a Unix domain socket address, only one port can be configured.

location

Location

Specifies whether the service is considered external to the mesh or part of the mesh.

resolution

Resolution

Yes

The service resolution mode for the hosts. When the resolution mode is set to NONE, traffic to any IP on a TCP port that does not have an associated IP address is allowed (for example, 0.0.0.0:<port>).

endpoints

WorkloadEntry[]

One or more endpoints associated with the service. You can specify either endpoints or workloadSelector, but not both.

workloadSelector

WorkloadSelector

Applies only to MESH_INTERNAL services. You can specify either endpoints or workloadSelector, but not both. Selects one or more Kubernetes pods based on their labels.

exportTo

string[]

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 service visibility across namespace boundaries.

If no namespace is specified, the service is exported to all namespaces by default.
The value . is reserved and defines an export to the same namespace where the ServiceEntry is defined.
The value * is reserved and defines an export to all namespaces.

For a Kubernetes Service, you can achieve the same effect by setting the networking.istio.io/exportTo annotation to a comma-separated list of namespace names.

subjectAltNames

string[]

If specified, the proxy verifies that the server certificate's subject alternative names match one of the specified values.

ServicePort

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

Field	Type	Required	Description
number	uint32	Yes	A valid non-negative integer port number.
protocol	string	Yes	The protocol exposed on the port. Valid values are HTTP, HTTPS, GRPC, HTTP2, MONGO, TCP, or TLS. TLS indicates that the connection is routed to the destination based on the SNI header without terminating the TLS connection.
name	string	Yes	A label assigned to the port.
targetPort	uint32	No	The port number on the endpoint that receives the traffic. If not set, this defaults to the value of number.

ServiceEntry.Location

Location specifies whether the service is internal or external to the Service Mesh. The features of the Service Mesh, such as mutual TLS (mTLS) authentication and policy enforcement, differ for services inside and outside the mesh. When communicating with services outside the mesh, mTLS authentication is disabled, and policy enforcement is performed on the client side instead of the server side.

Field

Description

MESH_EXTERNAL

Indicates that the service is outside the mesh. This is typically used for external services accessed through an API.

MESH_INTERNAL

Indicates that the service is part of the mesh. This is used to indicate that the service is added to the mesh but is not a service provided by Kubernetes.

ServiceEntry.Resolution

Resolution determines how the proxy resolves the IP addresses of the network endpoints associated with the service to route requests to one of them. The resolution mode specified here does not affect how the application resolves the IP address associated with the service. The application may still need to use DNS to resolve the service to an IP address so that the outbound traffic can be captured by the proxy. For HTTP services, the application can communicate with the service defined in the hosts field by communicating directly with the proxy, for example, by setting HTTP_PROXY.

Field	Description
NONE	Assumes that the incoming connection is already resolved to a specific destination IP address. Such connections are typically routed through the proxy using mechanisms like IP Table REDIRECT or eBPF. After performing any routing-related transformations, the proxy forwards the connection to the IP address to which the connection is bound.
STATIC	Uses the static IP addresses specified in the endpoints as the backend instances associated with the service.
DNS	Attempts to resolve the IP address by asynchronously querying the environment's DNS. DNS resolution cannot be used with Unix domain socket endpoints. If endpoints is not specified, the proxy resolves the DNS address specified in the hosts field, provided no wildcard character is used. If endpoints is specified, the proxy resolves the DNS addresses specified in endpoints to determine the destination IP addresses.
DNS_ROUND_ROBIN	Attempts to resolve the IP address by asynchronously querying the environment's DNS. Unlike DNS, DNS_ROUND_ROBIN uses only the first IP address returned when a new connection needs to be initiated, without relying on the full result of the DNS resolution. Connections to the host are preserved even if DNS records change frequently, which eliminates connection pool exhaustion and connection looping issues. This method is suitable for large, web-scale services that must be accessed through DNS. If no wildcard character is used, the proxy resolves the DNS address specified in the hosts field. DNS resolution cannot be used with Unix domain socket endpoints.