Service Mesh (ASM) uses a CustomResourceDefinition (CRD) called IstioGateway (apiVersion: istio.alibabacloud.com/v1beta1) to declaratively manage ingress and egress gateways. When you create or update an IstioGateway resource, a controller automatically provisions the corresponding Kubernetes Service, Deployment, and ServiceAccount in the target clusters.
Prerequisites
-
Add at least one Container Service for Kubernetes (ACK) cluster to your ASM instance. For details, see Add a cluster to an ASM instance.
Deploy ASM gateways in the istio-system namespace. In Istio 1.6 and later, gateways deployed to other namespaces fail to start because they cannot retrieve the gateway configuration.
Configuration examples
Ingress gateway
-
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 in the Name field, select istio-system from the Namespace drop-down list, paste the following YAML, and then click Create.
apiVersion: istio.alibabacloud.com/v1beta1 kind: IstioGateway metadata: name: "myexample-customingressgateway" namespace: "istio-system" spec: clusterIds: - "<cluster-id-1>" - "<cluster-id-2>" # Deploy to multiple clusters cpu: targetAverageUtilization: 80 env: - name: "envname1" value: "envvalue1" externalTrafficPolicy: Local gatewayType: ingress podLabels: key1: value1 ports: - name: status-port port: 15020 targetPort: 15020 - name: http2 port: 80 targetPort: 80 - name: https port: 443 targetPort: 0 - name: tls port: 15443 targetPort: 15443 replicaCount: 1 resources: limits: cpu: '2' memory: 2G requests: cpu: 200m memory: 256Mi # Mount a ConfigMap volume (optional): # configVolumes: # - name: config-volume-lua # configMapName: lua-libs # mountPath: /var/lib/lua # Mount a Secret volume (optional): # secretVolumes: # - name: myexample-customingressgateway-certs # secretName: istio-myexample-customingressgateway-certs # mountPath: /etc/istio/myexample-customingressgateway-certs serviceType: LoadBalancer serviceAnnotations: service.beta.kubernetes.io/alicloud-loadbalancer-address-type: internet serviceLabels: serviceLabelKey1: "serviceLabelValue1" podAnnotations: podAnnotationsKey1: "podAnnotationsValue1" rollingMaxSurge: "100%" rollingMaxUnavailable: "25%" overrides: # Per-cluster overrides <cluster-id-1>: replicaCount: 1 resources: limits: cpu: '2' memory: 2G requests: cpu: 200m memory: 256Mi serviceAnnotations: service.beta.kubernetes.io/alicloud-loadbalancer-address-type: internet service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec: "slb.s1.small" <cluster-id-2>: replicaCount: 2 resources: limits: cpu: '4' memory: 4G requests: cpu: 400m memory: 512Mi serviceAnnotations: service.beta.kubernetes.io/alicloud-loadbalancer-address-type: internet service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec: "slb.s2.small"Replace the following placeholders with actual values:
Placeholder
Description
Example
<cluster-id-1>ID of the first target cluster
c8a4b2xxxxxx<cluster-id-2>ID of the second target cluster
c9f3e7xxxxxxNoteTo manage the ingress gateway with the Go client for Kubernetes, see Go struct definitions.
-
Verify the gateway Service:
Log on to the ACK console. In the left navigation pane, click Clusters.
-
Find the target cluster and click its name.
-
Select istio-system from the Namespace drop-down list.
-
Click the service name of the ingress gateway to view its details.
-
Verify the gateway pods:
Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, find the cluster you want and click its name. In the left navigation pane, choose .
-
Select istio-system from the Namespace drop-down list.
-
Click a pod name of the ingress gateway to view its details.
Egress gateway
An egress gateway routes all outbound traffic in the mesh through a controlled exit point.
-
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 in the Name field, select istio-system from the Namespace drop-down list, paste the following YAML, and then click Create.
apiVersion: istio.alibabacloud.com/v1beta1 kind: IstioGateway metadata: name: egressgateway namespace: istio-system spec: autoCreateGatewayYaml: false clusterIds: - <cluster-id> disableContainerPortExposed: true dnsPolicy: ClusterFirst gatewayType: egress hostNetwork: false podLabels: security.istio.io/tlsMode: istio ports: - name: http-0 port: 80 protocol: HTTP targetPort: 80 - name: https-1 port: 443 protocol: HTTPS targetPort: 443 readinessProbe: {} replicaCount: 1 resources: limits: cpu: '2' memory: 4G requests: cpu: 200m memory: 256Mi rollingMaxSurge: 25% rollingMaxUnavailable: 25% runAsRoot: true serviceType: ClusterIP -
Verify the gateway Service:
Log on to the ACK console. In the left navigation pane, click Clusters.
-
Find the target cluster and click its name.
-
Select istio-system from the Namespace drop-down list.
-
Click the service name of the egress gateway to view its details.
-
Verify the gateway pods:
Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, find the cluster you want and click its name. In the left navigation pane, choose .
-
Select istio-system from the Namespace drop-down list.
-
Click a pod name of the egress gateway to view its details.
CRD field reference
Metadata
|
Field |
Type |
Description |
Default |
|
metadata.name |
|
Gateway name. The generated Kubernetes Service and Deployment are both named |
None |
|
metadata.namespace |
|
Namespace for the gateway. The generated Service and Deployment reside in this namespace. Must be |
|
Gateway type and clusters
|
Field |
Type |
Description |
Default |
|
gatewayType |
|
Gateway type. Valid values: ingress (routes inbound traffic), egress (routes outbound traffic). |
|
|
clusterIds |
|
IDs of the clusters where the gateway is deployed. All clusters must be managed by the current ASM instance. |
None |
Networking
|
Field |
Type |
Description |
Default |
|
ports |
|
Ports and protocols for the gateway. Example: |
None |
|
serviceType |
|
Kubernetes Service type. Valid values: LoadBalancer, NodePort, and ClusterIP. For egress gateways, typically set to |
|
|
loadBalancerClass |
|
Load balancer class for the gateway Service. Applies only when serviceType is |
None |
|
externalTrafficPolicy |
|
Routing scope for inbound traffic. Cluster routes to cluster-wide endpoints; Local routes to node-local endpoints only. Applies to ingress gateways only. |
|
|
serviceAnnotations |
|
Annotations on the gateway Service. Applies only when serviceType is |
None |
|
serviceLabels |
|
Labels on the gateway Service. |
None |
|
hostNetwork |
|
Grants the gateway pod access to the host network namespace. |
|
|
dnsPolicy |
|
DNS policy for the gateway pod. For details, see DNS for Services and Pods. |
|
Pod configuration
|
Field |
Type |
Description |
Default |
|
env |
|
Environment variables for the gateway pod. |
None |
|
podLabels |
|
Labels on the gateway pod. |
None |
|
podAnnotations |
|
Annotations on the gateway pod. |
None |
|
nodeSelector |
|
Node label selector for pod scheduling. Example: |
None |
|
affinity |
|
Affinity rules for pod scheduling. For details, see Affinity and anti-affinity. |
None |
|
tolerations |
|
Tolerations that allow the pod to schedule onto nodes with matching taints. For details, see Taints and Tolerations. |
None |
Resources and scaling
|
Field |
Type |
Description |
Default |
|
replicaCount |
|
Number of pod replicas. |
|
|
resources |
|
CPU and memory requests and limits for the gateway pod. |
limits: cpu |
|
rollingMaxSurge |
|
Maximum number of pods (absolute or percentage) that can exceed the desired replica count during a rolling update. |
|
|
rollingMaxUnavailable |
|
Maximum number of pods (absolute or percentage) that can be unavailable during a rolling update. |
|
Horizontal Pod Autoscaling (HPA)
|
Field |
Type |
Description |
Default |
|
cpu.targetAverageUtilization |
|
Target CPU utilization percentage (1--100) for HPA. When utilization exceeds this threshold, the replica count increases. |
None |
|
memory.targetAverageUtilization |
|
Target memory utilization percentage (1--100) for HPA. When utilization exceeds this threshold, the replica count increases. |
None |
|
maxReplicas |
|
Maximum replica count for HPA. Must be a positive integer. |
None |
|
minReplicas |
|
Minimum replica count for HPA. Must be a positive integer (minimum |
None |
Volumes
|
Field |
Type |
Description |
Default |
|
configVolumes |
|
ConfigMap volumes mounted to the gateway pod. Each entry requires name, configMapName, and mountPath. |
None |
|
secretVolumes |
|
Secret volumes mounted to the gateway pod. Each entry requires name, secretName, and mountPath. |
None |
ConfigMap volume example:
configVolumes:
- name: config-volume-lua
configMapName: lua-libs
mountPath: /var/lib/lua
Secret volume example:
secretVolumes:
- name: myexample-customingressgateway-certs
secretName: istio-myexample-customingressgateway-certs
mountPath: /etc/istio/myexample-customingressgateway-certs
Kernel tuning
|
Field |
Type |
Description |
Default |
|
kernel.enabled |
|
Enables custom kernel parameter tuning for the gateway pod. |
|
|
kernel.parameters |
|
Kernel sysctl parameters to apply. All values must be strings enclosed in double quotes because YAML interprets unquoted numbers as numeric values. Example: |
None |
Supported kernel parameters:
|
Parameter |
Parameter |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Some kernel parameters may not be supported by the host kernel version, which causes the gateway pod to report errors. Run kubectl describe pod to view error details. Remove invalid parameters to allow the containers to start normally.
Compression (ingress gateways only)
|
Field |
Type |
Description |
Default |
|
compression.enabled |
|
Enables response compression on the ingress gateway. |
|
|
compression.content_type |
|
Content types eligible for compression, identified by the |
None |
|
compression.min_content_length |
|
Minimum response body size (in bytes, based on |
|
|
compression.disable_on_etag_header |
|
Disables compression for responses that include an |
|
|
compression.remove_accept_encoding_header |
|
Strips the |
|
|
compression.gzip |
|
Gzip compression settings. Required to enable compression. To accept all defaults, set to |
None |
Gzip settings
|
Field |
Type |
Description |
Default |
|
compression.gzip.memory_level |
|
zlib memory usage level (1--9). Higher values use more memory but compress faster with better quality. |
|
|
compression.gzip.compression_level |
|
zlib compression level. Valid values: COMPRESSION_LEVEL_1 through COMPRESSION_LEVEL_9, DEFAULT_COMPRESSION, BEST_COMPRESSION, BEST_SPEED. See details below. |
|
|
compression.gzip.compression_strategy |
|
zlib compression strategy. Valid values: DEFAULT_STRATEGY, FILTERED, FIXED, HUFFMAN_ONLY, RLE. See details below. |
|
|
compression.gzip.window_bits |
|
zlib sliding window size (9--15). |
|
|
compression.gzip.chunk_size |
|
zlib output buffer size in bytes. |
|
Compression levels:
|
Level |
Equivalent |
Behavior |
|
COMPRESSION_LEVEL_1 |
BEST_SPEED |
Fastest compression, lowest ratio |
|
COMPRESSION_LEVEL_2 to COMPRESSION_LEVEL_6 |
Medium |
Balanced speed and ratio |
|
COMPRESSION_LEVEL_6 |
DEFAULT_COMPRESSION |
Default balance of speed and ratio |
|
COMPRESSION_LEVEL_7 to COMPRESSION_LEVEL_9 |
High |
Highest ratio, slowest speed |
|
COMPRESSION_LEVEL_9 |
BEST_COMPRESSION |
Maximum compression ratio |
Compression strategies:
|
Strategy |
Use case |
|
DEFAULT_STRATEGY |
General-purpose. Produces good results in most cases. |
|
FILTERED |
Optimized for data with repeated patterns. Achieves higher ratios for text and generated data. |
|
HUFFMAN_ONLY |
Uses only Huffman coding. Best for static data that needs fast decompression. |
|
RLE |
Run-length encoding. Effective for repetitive sequences such as bitmap data. |
|
FIXED |
Uses a predefined coding tree instead of dynamically generated trees. Fast but low compression ratio. |
Per-cluster overrides
Use overrides to configure distinct settings for specific clusters when clusterIds contains two or more entries. Each key is a cluster ID from the clusterIds array.
|
Field |
Type |
Description |
Default |
|
overrides |
|
Per-cluster configuration overrides. |
None |
Configurable override fields:
-
serviceAnnotations
-
podAnnotations
-
resources
-
replicaCount
-
HPA-related fields (ASM v1.16 or later)
-
serviceType (ASM v1.16 or later)
Example:
overrides:
<cluster-id-1>:
replicaCount: 2
resources:
limits:
cpu: '4'
memory: 4G
requests:
cpu: 400m
memory: 512Mi
serviceAnnotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec: "slb.s2.small"
Fields that trigger rolling restarts
Changing the following fields causes a rolling restart of the gateway pods. Review these changes carefully before applying them to production environments.
|
Field |
Notes |
|
env |
|
|
ports |
In ASM v1.16 and later, changes to ports no longer trigger a rolling restart. |
|
configVolumes |
|
|
resources |
|
|
secretVolumes |
|
|
podLabels |
|
|
podAnnotations |
|
|
kernel.enabled |
|
|
kernel.parameters |
|
|
hostNetwork |
|
|
dnsPolicy |
|
|
nodeSelector |
Subject to pod scheduling constraints. |
|
affinity |
Subject to pod scheduling constraints. |
|
tolerations |
Subject to pod scheduling constraints. |
Go struct definitions
Use the following Go type definitions to manage IstioGateway resources programmatically with a Go client for Kubernetes.