Use an ASM gateway as an Ingress controller to expose services in a cluster - Alibaba Cloud Service Mesh

Kubernetes clusters often need a way to route external HTTP and HTTPS traffic to internal services. Instead of deploying a separate Ingress controller, you can use an ASM gateway to handle Ingress resources directly. This combines standard Kubernetes Ingress routing with service mesh capabilities: autoscaling, TLS acceleration, dynamic certificate loading, graceful shutdown, and observability.

The kubernetes.io/ingress.class annotation is deprecated in Kubernetes. Use the ingressClassName field instead. Both methods are documented below for backward compatibility, but ingressClassName is the recommended approach.

How it works

An Ingress defines HTTP and HTTPS routing rules for external access to cluster services. When an ASM gateway serves as the Ingress controller, it processes these rules and routes incoming traffic accordingly.

Ingress does not support custom listening ports. The ASM gateway uses port 80 for HTTP and port 443 for HTTPS by default. Make sure both ports are enabled on the gateway before you create Ingress resources.

Capability	Description
Autoscaling	Scales gateway pods based on traffic load
TLS acceleration	Offloads TLS processing at the gateway
Dynamic certificate loading	Updates private keys, server certificates, and root certificates without restarting the gateway pod
Graceful shutdown	Drains connections before terminating the Server Load Balancer (SLB) instance
Observability and security	Inherits the full observability and security feature set of ASM

Prerequisites

Before you begin, ensure that you have:

An ACK cluster added to an ASM instance of v1.16 or later. For more information, see Add a cluster to an ASM instance
An ingress gateway with ports 80 and 443 exposed. For more information, see Create an ingress gateway service
The httpbin application deployed in the cluster (exposure on the gateway is not required). For more information, see Deploy the httpbin application

Limits

Limit	Description
`defaultBackend` not supported	The Ingress `defaultBackend` field is not supported with an ASM gateway Ingress controller. For more information, see Ingress.
Ingress API V1 only	Only `networking.k8s.io/v1` is supported. Verify that the data plane supports Ingress API V1 before proceeding.

Step 1: Enable Ingress API access on the ASM gateway

Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of the target ASM instance. In the left-side navigation pane, choose ASM Gateways > Ingress Gateway.
In the Advanced features section, click Enable Ingress API access. In the confirmation dialog, click OK.

Step 2: Create an Ingress resource

Use one of the following methods to specify the ASM gateway as the Ingress controller.

Method 1: Use the ingressClassName field (recommended)

This method uses the standard Kubernetes IngressClass mechanism.

Create a file named ingress.yaml:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress
   spec:
     ingressClassName: istio
     rules:
     - host: httpbin.aliyun.com
       http:
         paths:
         - path: /
           pathType: Prefix
           backend:
             service:
               name: httpbin
               port:
                 number: 8000

Connect to the ACK cluster with kubectl and apply the Ingress:
```
   kubectl apply -f ingress.yaml
```

Method 2: Use the annotation (deprecated)

This method uses the legacy kubernetes.io/ingress.class annotation.

Create a file named ingress.yaml:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     annotations:
       kubernetes.io/ingress.class: istio
     name: ingress
   spec:
     rules:
     - host: httpbin.aliyun.com
       http:
         paths:
         - path: /status
           pathType: Prefix
           backend:
             service:
               name: httpbin
               port:
                 number: 8000

Connect to the ACK cluster with kubectl and apply the Ingress:
```
   kubectl apply -f ingress.yaml
```

Step 3: Verify HTTP access

Run the following command to access the httpbin service:

curl -H 'Host: httpbin.aliyun.com' http://${IP address of the ASM gateway}/status/418

Expected output:

    -=[ teapot ]=-

       _...._
     .'  _ _ `.
    | ."` ^ `". _,
    \_;`"---"`|//
      |       ;/
      \_     _/

The teapot response confirms that the Ingress routes traffic to the httpbin service through the ASM gateway.

Step 4: Configure TLS for HTTPS access

ASM allows you to configure TLS for an Ingress. The ASM gateway runs in the istio-system namespace, so the TLS Secret must also reside in istio-system.

The gateway supports dynamic certificate loading. You can update private keys, server certificates, and root certificates without restarting the gateway pod. You can also mount multiple Secrets to load different certificates. To load multiple certificates, create a separate Secret for each and reference them in the Ingress TLS configuration.

Prepare a server certificate and private key

A domain name is accessible only after it has obtained an Internet Content Provider (ICP) filing. The following example uses aliyun.com as the domain.

If you already have a certificate and private key for aliyun.com, name them aliyun.com.crt and aliyun.com.key, then skip to Create the TLS Secret.

If you need to generate a self-signed certificate, run the following openssl commands:

Create a root certificate and private key:

   openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \
     -subj '/O=myexample Inc./CN=aliyun.com' \
     -keyout aliyun.root.key -out aliyun.root.crt

Generate a server certificate and private key for aliyun.com:

   openssl req -out aliyun.com.csr -newkey rsa:2048 -nodes \
     -keyout aliyun.com.key -subj "/CN=aliyun.com/O=myexample organization"

   openssl x509 -req -days 365 -CA aliyun.root.crt -CAkey aliyun.root.key \
     -set_serial 0 -in aliyun.com.csr -out aliyun.com.crt

Create the TLS Secret

Connect to the cluster where the ingress gateway pod runs and create a Secret in the istio-system namespace:

kubectl create -n istio-system secret tls myexample-credential \
  --key=aliyun.com.key --cert=aliyun.com.crt

Create an Ingress with TLS

Create a file named ingress-https.yaml:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress
     annotations:
       kubernetes.io/ingress.class: istio
   spec:
     rules:
     - host: httpbin.aliyun.com
       http:
         paths:
         - path: /status
           pathType: Prefix
           backend:
             service:
               name: httpbin
               port:
                 number: 8000
     tls:
     - hosts:
       - httpbin.aliyun.com
       secretName: myexample-credential

Note If you create an Ingress in the ACK console, the Secret selection is limited to the namespace of the Ingress. For example, if the Ingress is in the default namespace, copy the myexample-credential Secret to the default namespace so that it appears in the ACK console.

Apply the Ingress:
```
   kubectl apply -f ingress-https.yaml
```

Verify HTTPS access

Send an HTTPS request to the httpbin service through the gateway:

curl -H 'Host: httpbin.aliyun.com' \
  --resolve httpbin.aliyun.com:443:${IP address of the ASM gateway} \
  https://httpbin.aliyun.com:443/status/418 -k

Expected output:

    -=[ teapot ]=-

       _...._
     .'  _ _ `.
    | ."` ^ `". _,
    \_;`"---"`|//
      |       ;/
      \_     _/

The teapot response confirms that HTTPS traffic is routed through the ASM gateway with TLS termination.

Cleanup

To remove the resources created in this tutorial:

kubectl delete ingress ingress
kubectl delete -n istio-system secret myexample-credential