Alibaba Cloud Service Mesh (ASM) provides a custom resource definition (CRD) with kind set to IstioGateway and apiVersion set to istio.alibabacloud.com/v1beta1. ASM also provides a corresponding controller. By listening for changes to this CRD resource, the controller synchronizes the associated Kubernetes Service, Deployment, ServiceAccount, and other related resources in the cluster. This topic describes configuration examples and field definitions for the ASM gateway CRD.
Configuration examples
Prerequisites
Create all new ASM gateways in the istio-system namespace to ensure they can access required configuration information. In Istio 1.6 and later versions, deploying a gateway in any other namespace prevents it from accessing necessary configurations, causing the ASM gateway to fail to start.
Example 1: Manage an ingress gateway using the Kubernetes API
-
Log on to the ASM console. In the left-side navigation pane, choose .
-
On the Mesh Management page, click the name of the ASM instance. In the left-side navigation pane, choose .
On the Ingress Gateway page, click Create from YAML.
On the Create page, enter a Name for the gateway, select Namespaces as istio-system, configure the following YAML, and then click Create.
For details about each field, see CRD field reference.
NoteIf you want to manage the ingress gateway using the Kubernetes client, see Gateway Go struct implementation.
View the service information of the ingress gateway.
Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click .
At the top of the Services page, select istio-system from the Namespace drop-down list.
In the services list, click the name of your target service to view its ingress gateway information.
View the pod information of the ingress gateway.
Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click .
At the top of the Pods page, select istio-system from the Namespace drop-down list.
In the pods list, click the name of your target pod to view its ingress gateway information.
Example 2: Manage an egress gateway using the Kubernetes API
ASM provides an egress gateway service that offers a unified traffic exit point for applications within the mesh.
-
Log on to the ASM console. In the left-side navigation pane, choose .
-
On the Mesh Management page, click the name of the ASM instance. In the left-side navigation pane, choose .
On the Egress Gateway page, click Create from YAML.
On the Create page, enter a Name for the egress gateway, select Namespaces as istio-system, configure the following YAML, and then click Create.
For details about each field, see CRD field reference.
View the service information of the egress gateway.
Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click .
On the Services page, select istio-system from the Namespace drop-down list.
In the services list, click the name of your target service to view its egress gateway information.
View the pod information of the egress gateway.
Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click .
On the Pods page, select istio-system from the Namespace drop-down list.
In the pods list, click the name of your target pod to view its egress gateway information.
CRD field reference
Field | Description | Default |
metadata.name | Name. The generated Kubernetes Service and Deployment names are istio-{this value}. | None |
metadata.namespace | Namespace where the generated Kubernetes Service and Deployment reside. Important To maintain compatibility with Istio 1.6 and later versions, this namespace must be istio-system. | istio-system |
clusterIds | Array type. IDs of clusters where the gateway will be deployed. These clusters belong to the current mesh instance. | None |
env | Array type. Environment variables for the gateway pod. | None |
externalTrafficPolicy | Specifies whether external traffic should route to node-local or cluster-wide endpoints. Valid values are Cluster or Local. Note This field applies only to ingress gateways. | Cluster |
ports | Array type. List of ports and protocols defined for the gateway pod. Examples:
Note In versions earlier than 1.9.7.107, the protocol field is not explicitly declared. You must declare it uniformly as TCP. | None |
gatewayType | Gateway type. Valid values are ingress or egress.
| ingress |
replicaCount | Number of replicas. | 1 |
configVolumes | ConfigMap volumes mounted to the gateway pod. Example: | None |
resources | Resource configuration for the gateway pod. |
|
secretVolumes | Secret volumes mounted to the gateway pod. Example: | None |
serviceType | Service type for the gateway. Valid values are LoadBalancer, NodePort, or ClusterIP. Egress gateways are typically set to ClusterIP. Important If your data plane cluster is a registered cluster and you set this field to LoadBalancer, ensure the cluster supports LoadBalancer-type Services to avoid ASM gateway creation failures. | LoadBalancer |
loadBalancerClass | Specifies the loadBalancerClass for the gateway service. This field takes effect only when serviceType is LoadBalancer. This field is supported starting from ASM version 1.18. For more information, see Use Network Load Balancer (NLB) with ASM ingress gateways. | None |
serviceAnnotations | Annotations for the gateway service. Example: Note This field applies only to gateways with serviceType set to LoadBalancer. Egress gateways typically do not use this field. | None |
serviceLabels | Labels for the gateway service. | None |
podLabels | Labels for the gateway pod. | None |
podAnnotations | Annotations for the gateway pod. | None |
rollingMaxSurge | Maximum number of pods that can exist above the desired number during a rolling update. This value can be an absolute number or a percentage. | "100%" |
rollingMaxUnavailable | Maximum number of unavailable pods during a rolling update. This value can be an absolute number or a percentage. | "25%" |
overrides | When clusterIds specifies two or more clusters, you can define cluster-specific configurations that differ from the general parameters above. The value is a map type. Note
| None |
kernel.enabled | Are custom kernel parameters enabled? | false |
kernel.parameters | Kernel parameter settings. The following kernel parameters are currently supported:
Note Depending on the host kernel version, some kernel parameters may not be supported. If this occurs, the mesh pod may report errors. Use the All kernel parameter values must be strings. Because YAML syntax parses plain numbers as numeric types, wrap your values in double quotes (""), for example: net.core.somaxconn: "65535". | None |
compression.enabled | Enables compression capability for the ingress gateway. Note Fields related to compression apply only to ingress gateways. | false |
compression.content_type | List of ContentTypes to compress. Examples:
| None |
compression.disable_on_etag_header |
| false |
compression.min_content_length | Triggers compression when ContentLength is greater than or equal to this value. | 30 |
compression.remove_accept_encoding_header |
| false |
compression.gzip | Only gzip compression is currently supported. To enable compression, you must include this field. Even if all parameters use their defaults, include an empty structure, for example: | None |
compression.gzip.memory_level | Memory usage level for zlib internals. Valid values are 1–9. Higher values use more memory but provide faster compression speeds and better compression ratios. | 5 |
compression.gzip.compression_level | Compression level for zlib. Valid values:
Note BEST_COMPRESSION provides the highest compression quality. BEST_SPEED provides the fastest compression speed. Specifically:
| DEFAULT_COMPRESSION |
compression.gzip.compression_strategy | Compression strategy for zlib. Valid values:
Note DEFAULT_STRATEGY The default compression strategy uses underlying default behavior and produces satisfactory results in most cases. FILTERED Prioritizes filter-layer compression algorithms for scenarios with mostly repetitive data. Offers high compression ratios for text and artificially generated data. HUFFMAN_ONLY Uses only Huffman coding without other compression algorithms. Typically used for static data that requires fast decompression. RLE Uses run-length encoding, which efficiently compresses sequences of identical data, such as bitmaps. FIXED Uses predefined encoding trees for Huffman coding instead of dynamically generating them based on input data. Enables fast compression and decompression but generally yields lower compression ratios. | DEFAULT_STRATEGY |
compression.gzip.window_bits | Window size for zlib. Valid values are 9–15. | 12 |
compression.gzip.chunk_size | Output buffer size for zlib. | 4096 |
hostNetwork | Host networking.
| false |
dnsPolicy | DNS policy. For more information about dnsPolicy, see DNS for Services and Pods. | ClusterFirst |
cpu.targetAverageUtilization | CPU target utilization when HPA is enabled. Valid values are 1–100. If utilization exceeds this value, replicas increase. If it falls below, replicas decrease. | None |
memory.targetAverageUtilization | Memory target utilization when HPA is enabled. Valid values are 1–100. If utilization exceeds this value, replicas increase. If it falls below, replicas decrease. | None |
maxReplicas | Maximum number of replicas adjusted by HPA. Must be a positive integer. | None |
minReplicas | Minimum number of replicas adjusted by HPA. Must be a positive integer with a minimum value of 1. | None |
nodeSelector | Specifies the node where the gateway pod runs. Define custom key-value pairs under this field. Example: | None |
affinity | Specifies the node for the gateway pod using node affinity. For more information, see Affinity and anti-affinity. | None |
tolerations | Used together with node taints. For more information, see Taints and tolerations. | None |
Fields that trigger a rolling restart
Changing the following fields triggers a rolling restart of the gateway. Proceed with caution.
env
ports (triggers a restart in ASM versions earlier than 1.16; no restart in 1.16 and later)
configVolumes
resources
secretVolumes
podLabels
podAnnotations
kernel.enabled
kernel.parameters
hostNetwork
dnsPolicy
nodeSelector (depends on scheduling)
affinity (depends on scheduling)
tolerations (depends on scheduling)