ASMEgressTrafficPolicy CRD description - Alibaba Cloud Service Mesh

ASMEgressTrafficPolicy is a CustomResourceDefinition (CRD) that controls how workloads in your service mesh access external services through an egress gateway. Instead of configuring multiple Istio resources (ServiceEntry, Gateway, VirtualService, DestinationRule) separately, this single CRD defines:

Which workloads can send egress traffic
Which external services they can reach
How ports map between sidecars, the egress gateway, and external endpoints
Whether HTTP requests are upgraded to HTTPS at the gateway

You can use ASMEgressTrafficPolicy in combination with sidecar proxies and authorization policies to enhance traffic shaping. ASMEgressTrafficPolicy is available in Service Mesh (ASM) 1.16.4 and later.

How it works

When a workload sends a request to an external service, the traffic follows this path:

Workload --> Sidecar proxy --> Egress gateway --> External service

The CRD maps ports at each hop. For example, with HTTP traffic on port 80:

Workload :80 --> Sidecar :80 --> Egress gateway :80 --> httpbin.org :80

With HTTPS upgrade enabled, the egress gateway receives HTTP traffic from the sidecar on port 80 and initiates an HTTPS connection to the external service on port 443:

Workload :80 (HTTP) --> Sidecar :80 --> Egress gateway :80 --> (HTTPS upgrade) --> httpbin.org :443

Conventions

Before you create an ASMEgressTrafficPolicy resource, note these required conventions:

Name: The resource name must match the egress gateway name (for example, egressgateway-a).
Namespace: The resource must be created in the istio-egress namespace.

YAML examples

Route HTTP traffic to an external service

In this example, the sleep-a workload in the mytest namespace accesses http://www.httpbin.org through the egressgateway-a gateway on port 80.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMEgressTrafficPolicy
metadata:
  name: egress-by-egressgateway-a
  namespace: istio-egress
spec:
  byEgressGateway:
    name: egressgateway-a
  egressRules:
  - from:
    - namespace: mytest
      workloadSelector:
        app: sleep-a
    to:
    - name: httpbin-service-http
      hosts:
      - www.httpbin.org   # Multiple domains must resolve to the same IP address.
      - httpbin.org
      port:
        name: http
        number: 80
        protocol: HTTP
      byEgressGateway:
        port: 80           # Sidecar :80 --> Gateway :80 --> httpbin.org :80

Upgrade HTTP to HTTPS at the egress gateway

This example defines three routing rules through a single egress gateway:

sleep-a accesses httpbin.org on port 80 (HTTP). The egress gateway upgrades the connection to HTTPS on port 443.
sleep-a accesses httpbin.org on port 443 (HTTPS) through egress gateway port 444.
sleep-b accesses www.aliyun.com on port 443 (HTTPS) through egress gateway port 445.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMEgressTrafficPolicy
metadata:
  name: egress-by-egressgateway-a
  namespace: istio-egress
spec:
  byEgressGateway:
    name: egressgateway-a
  egressRules:
  - from:
     - namespace: mytest
       workloadSelector:
          app: sleep-a
    to:
    - name: httpbin-service-http
      hosts:
      - www.httpbin.org   # Multiple domains must resolve to the same IP address.
      - httpbin.org
      port:
        name: http
        number: 80
        protocol: HTTP
      byEgressGateway:
        port: 80           # Sidecar :80 --> Gateway :80 --> httpbin.org :80
      httpsUpgrade:
        enabled: true      # Set to false to disable the upgrade. The port below is ignored when disabled.
        port: 443          # Sidecar :80 --> Gateway :443 --> httpbin.org :443
    - name: httpbin-service-https
      hosts:
      - www.httpbin.org
      - httpbin.org
      port:
        name: https
        number: 443
        protocol: HTTPS
      byEgressGateway:
        port: 444
  - from:
     - namespace: mytest
       workloadSelector:
          app: sleep-b
    to:
    - name: aliyun-service-https
      hosts:
      - www.aliyun.com
      port:
        name: https
        number: 443
        protocol: HTTPS
      byEgressGateway:
        port: 445

Route HTTP and TCP traffic with automatic port assignment

Starting from ASM 1.24.6.45, ASMEgressTrafficPolicy supports TCP-based external services. Because each TCP service requires a dedicated egress gateway port, ASM can automatically assign redirection ports from the range 10000--20000. To enable automatic assignment, leave all byEgressGateway fields blank in the to entries. These assigned ports are internal to the mesh and do not affect your application services.

Important

To access an external TCP service by domain name, enable the ASM DNS proxy feature. For details, see Use DNS proxy in ASM.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMEgressTrafficPolicy
metadata:
  name: egress-by-egressgateway-a
  namespace: istio-egress
spec:
  byEgressGateway:
    name: egressgateway-a
  egressRules:
  - from:
    - namespace: default
      workloadSelector:
        app: sleep
    to:
    - name: aliyun-com-http       # HTTP route
      hosts:
      - aliyun.com
      port:
        name: http
        number: 80
        protocol: HTTP
    - name: aliyun-https          # HTTPS route
      hosts:
      - aliyun.com
      port:
        name: https
        number: 443
        protocol: HTTPS
    - name: https-upgrade         # HTTP upgraded to HTTPS
      hosts:
      - taobao.com
      port:
        name: http
        protocol: HTTP
        number: 80
      httpsUpgrade:
        enabled: true
        port: 443
    - name: tcp-svc1              # TCP service (by IP)
      hosts:
      - 1.1.1.1
      port:
        name: tcp
        protocol: TCP
        number: 44
    - name: tcp-svc2              # TCP service (by domain)
      hosts:
      - test-tcp.com
      port:
        name: tcp
        protocol: TCP
        number: 444

Field reference

Spec

Field	Type	Required	Description
byEgressGateway	ByEgressGateway	Yes	The egress gateway used for external access. At this level, specify only the gateway `name`, not the `port`.
egressRules	EgressRule[]	Yes	A list of rules that define which workloads can access which external services.

ByEgressGateway

This type appears at two levels with different field requirements:

Context	Specify `name`	Specify `port`
`spec.byEgressGateway`	Yes	No
`to[].byEgressGateway`	No	Yes

Field	Type	Required	Description
name	string	Yes (at `spec` level)	The egress gateway name. Keep it within 32 characters.
port	uint32	No	The egress gateway port that receives traffic for this service. Starting from ASM 1.24.6.45, if all `byEgressGateway` entries in `to[]` are left blank, ASM automatically assigns ports from the range 10000--20000.

EgressRule

Field	Type	Required	Description
name	string	No	A descriptive name for this rule.
from	From[]	Yes	The source workloads that initiate egress traffic.
to	To[]	Yes	The external services that the source workloads can access.

From

Field	Type	Required	Description
namespace	string	Yes	The namespace of the source workload.
workloadSelector	map[string]string	No	Label selector that filters specific workloads within the namespace.

To

Field	Type	Required	Description
name	string	Yes	The name of this external service entry (for example, `httpbin-service-http`).
hosts	string[]	Yes	Domain names of the external service. Multiple domains are allowed, but they must resolve to the same IP address.
port	Port	Yes	The external service port. Includes `name` (string), `number` (uint32), and `protocol` (`HTTP`, `HTTPS`, or `TCP`).
byEgressGateway	ByEgressGateway	Yes	The egress gateway port that handles traffic to this service. At this level, specify only the `port`, not the `name`. Starting from ASM 1.24.6.45, if all `byEgressGateway` fields in the `to` sections are left blank, ASM automatically assigns ports for all services.
httpsUpgrade	HttpsUpgrade	No	Upgrades outbound HTTP requests to HTTPS at the egress gateway. The sidecar sends HTTP traffic to the gateway, and the gateway initiates an HTTPS connection to the external service.

HttpsUpgrade

Field	Type	Required	Description
enabled	bool	Yes	Set to `true` to upgrade HTTP requests to HTTPS at the egress gateway. When set to `false`, the `port` value below is ignored.
port	uint32	Yes	The HTTPS port on the external service (typically `443`).

Alibaba Cloud Service Mesh:ASMEgressTrafficPolicy CRD description