An Application Load Balancer (ALB) Ingress is an API object that provides Layer 7 load balancing to manage external access to Services in a Kubernetes cluster. This topic describes how to use ALB Ingresses to forward requests to backend server groups based on domain names and URL paths, redirect HTTP requests to HTTPS, and implement canary releases.
Prerequisites
- An ACK cluster is created. For more information, see Create an ACK managed cluster.
- A kubectl client is connected to the cluster. For more information, see Connect to ACK clusters by using kubectl.
- An AlbConfig object is created. For more information, see Create an AlbConfig object.
Table of contents
This topic describes the following advanced ALB Ingress configurations:
- Forward requests based on domain names
- Forward requests based on URL paths
- Configure health checks
- Configure automatic certificate discovery
- Redirect HTTP requests to HTTPS
- Configure the HTTPS or gRPC protocol
- Configure rewrite rules
- Configure custom listening ports
- Configure forwarding rule priorities
- Use annotations to perform phased releases
- Configure session persistence by using annotations
Forward requests based on domain names
Perform the following steps to create an Ingress with a domain name and an Ingress without a domain name, and then use the Ingresses to forward requests.
- Create an Ingress with a domain name.
- Use the following template to create a Deployment, a Service, and an Ingress. Requests
to the domain name of the Ingress are forwarded to the Service.
apiVersion: v1 kind: Service metadata: name: demo-service namespace: default spec: ports: - name: port1 port: 80 protocol: TCP targetPort: 8080 selector: app: demo sessionAffinity: None type: NodePort --- apiVersion: apps/v1 kind: Deployment metadata: name: demo namespace: default spec: replicas: 1 selector: matchLabels: app: demo template: metadata: labels: app: demo spec: containers: - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1 imagePullPolicy: IfNotPresent name: demo ports: - containerPort: 8080 protocol: TCP --- apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: demo namespace: default spec: ingressClassName: alb rules: - host: demo.domain.ingress.top http: paths: - backend: serviceName: demo-service servicePort: 80 path: /hello pathType: ImplementationSpecific
apiVersion: v1 kind: Service metadata: name: demo-service namespace: default spec: ports: - name: port1 port: 80 protocol: TCP targetPort: 8080 selector: app: demo sessionAffinity: None type: NodePort --- apiVersion: apps/v1 kind: Deployment metadata: name: demo namespace: default spec: replicas: 1 selector: matchLabels: app: demo template: metadata: labels: app: demo spec: containers: - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1 imagePullPolicy: IfNotPresent name: demo ports: - containerPort: 8080 protocol: TCP --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: demo namespace: default spec: ingressClassName: alb rules: - host: demo.domain.ingress.top http: paths: - backend: service: name: demo-service port: number: 80 path: /hello pathType: ImplementationSpecific
- Run the following command to access the application by using the specified domain
name.
Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the
kubectl get ing
command.curl -H "host: demo.domain.ingress.top" <ADDRESS>/hello
Expected output.{"hello":"coffee"}
- Use the following template to create a Deployment, a Service, and an Ingress. Requests
to the domain name of the Ingress are forwarded to the Service.
- Create an Ingress without a domain name.
- The following template shows the configuration of the Ingress:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: demo namespace: default spec: ingressClassName: alb rules: - host: "" http: paths: - backend: serviceName: demo-service servicePort: 80 path: /hello pathType: ImplementationSpecific
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: demo namespace: default spec: ingressClassName: alb rules: - host: "" http: paths: - backend: service: name: demo-service port: number: 80 path: /hello
- Run the following command to access the application without using a domain name.
Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the
kubectl get ing
command.curl <ADDRESS>/hello
Expected output.{"hello":"coffee"}
- The following template shows the configuration of the Ingress:
Forward requests based on URL paths
ALB Ingresses can forward requests based on URL paths. You can use the pathType
parameter to configure different URL match policies. The valid values of pathType
are Exact, ImplementationSpecific, and Prefix.
You can perform the following steps to configure different URL match policies.
- Exact: matches the entire URL path with case sensitivity.
- The following template shows the configuration of the Ingress:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: demo-path namespace: default spec: ingressClassName: alb rules: - http: paths: - path: /hello backend: serviceName: demo-service servicePort: 80 pathType: Exact
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: demo-path namespace: default spec: ingressClassName: alb rules: - http: paths: - path: /hello backend: service: name: demo-service port: number: 80 pathType: Exact
- Run the following command to access the application.
Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the
kubectl get ing
command.curl <ADDRESS>/hello
Expected output.{"hello":"coffee"}
- The following template shows the configuration of the Ingress:
- ImplementationSpecific: the default match policy. For ALB Ingresses, the ImplementationSpecific
policy has the same effect as the
Exact
policy. However, the controllers of Ingresses with the ImplementationSpecific policy and the controllers of Ingresses with the Exact policy are implemented in different ways.-
The following template shows the configuration of the Ingress:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: demo-path namespace: default spec: ingressClassName: alb rules: - http: paths: - path: /hello backend: serviceName: demo-service servicePort: 80 pathType: ImplementationSpecific
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: demo-path namespace: default spec: ingressClassName: alb rules: - http: paths: - path: /hello backend: service: name: demo-service port: number: 80 pathType: ImplementationSpecific
- Run the following command to access the application.
Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the
kubectl get ing
command.curl <ADDRESS>/hello
Expected output.{"hello":"coffee"}
-
- Prefix: matches a specified prefix against URL paths. The elements in URL paths are
separated by forward slashes (
/
). The prefix is case-sensitive and matched against each element of the path.- The following template shows the configuration of the Ingress:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: demo-path-prefix namespace: default spec: ingressClassName: alb rules: - http: paths: - path: / backend: serviceName: demo-service servicePort: 80 pathType: Prefix
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: demo-path-prefix namespace: default spec: ingressClassName: alb rules: - http: paths: - path: / backend: service: name: demo-service port: number: 80 pathType: Prefix
- Run the following command to access the application.
Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the
kubectl get ing
command.curl <ADDRESS>/hello
Expected output.{"hello":"coffee"}
- The following template shows the configuration of the Ingress:
Configure health checks
You can configure health checks for ALB Ingresses by using the following annotations.
The following YAML template provides an example on how to create an Ingress that has health check enabled:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/healthcheck-enabled: "true" alb.ingress.kubernetes.io/healthcheck-path: "/" alb.ingress.kubernetes.io/healthcheck-protocol: "HTTP" alb.ingress.kubernetes.io/healthcheck-method: "HEAD" alb.ingress.kubernetes.io/healthcheck-httpcode: "http_2xx" alb.ingress.kubernetes.io/healthcheck-timeout-seconds: "5" alb.ingress.kubernetes.io/healthcheck-interval-seconds: "2" alb.ingress.kubernetes.io/healthy-threshold-count: "3" alb.ingress.kubernetes.io/unhealthy-threshold-count: "3" spec: ingressClassName: alb rules: - http: paths: # Configure a context path. - path: /tea backend: serviceName: tea-svc servicePort: 80 # Configure a context path. - path: /coffee backend: serviceName: coffee-svc servicePort: 80
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/healthcheck-enabled: "true" alb.ingress.kubernetes.io/healthcheck-path: "/" alb.ingress.kubernetes.io/healthcheck-protocol: "HTTP" alb.ingress.kubernetes.io/healthcheck-method: "HEAD" alb.ingress.kubernetes.io/healthcheck-httpcode: "http_2xx" alb.ingress.kubernetes.io/healthcheck-timeout-seconds: "5" alb.ingress.kubernetes.io/healthcheck-interval-seconds: "2" alb.ingress.kubernetes.io/healthy-threshold-count: "3" alb.ingress.kubernetes.io/unhealthy-threshold-count: "3" spec: ingressClassName: alb rules: - http: paths: # Configure a context path. - path: /tea backend: service: name: tea-svc port: number: 80 # Configure a context path. - path: /coffee backend: service: name: coffee-svc port: number: 80
Parameter | Description |
---|---|
alb.ingress.kubernetes.io/healthcheck-enabled | Optional. Specifies whether to enable health check. Default value: true. |
alb.ingress.kubernetes.io/healthcheck-path | Optional. The URL path based on which health checks are performed. Default value:
/.
|
alb.ingress.kubernetes.io/healthcheck-protocol | Optional. The protocol that is used for health checks.
|
alb.ingress.kubernetes.io/healthcheck-method | Optional. The request method that is used for health checks.
|
alb.ingress.kubernetes.io/healthcheck-httpcode | The status codes that are returned when backend servers pass health checks.
|
alb.ingress.kubernetes.io/healthcheck-timeout-seconds | The timeout period of a health check. If a backend server does not respond within the specified timeout period, the server fails to pass the health check. Valid values: 1 to 300. Default value: 5. Unit: seconds. |
alb.ingress.kubernetes.io/healthcheck-interval-seconds | The interval between two consecutive health checks. Unit: seconds. Valid values: 1 to 50. Default value: 2. Unit: seconds. |
alb.ingress.kubernetes.io/healthy-threshold-count | The number of times that an unhealthy backend server must consecutively pass health checks before the server is considered healthy. Valid values: 2 to 10. Default value: 3. |
alb.ingress.kubernetes.io/unhealthy-threshold-count | The number of times that a healthy backend server must consecutively fail health checks before the server is considered unhealthy. Valid values: 2 to 10. Default value: 3. |
Configure automatic certificate discovery
The ALB Ingress controller supports automatic certificate discovery. You must first create a certificate in the SSL Certificates console. Then, specify the domain name of the certificate in the Transport Layer Security (TLS) configurations of the Ingress. This way, the ALB Ingress controller can automatically discover and match the certificate based on the TLS configurations of the Ingress.
Redirect HTTP requests to HTTPS
You can configure an ALB Ingress to redirect HTTP requests to HTTPS port 443 by adding
the alb.ingress.kubernetes.io/ssl-redirect: "true"
annotation.
Example:
apiVersion: v1 kind: Service metadata: name: demo-service-ssl namespace: default spec: ports: - name: port1 port: 80 protocol: TCP targetPort: 8080 selector: app: demo-ssl sessionAffinity: None type: NodePort --- apiVersion: apps/v1 kind: Deployment metadata: name: demo-ssl namespace: default spec: replicas: 1 selector: matchLabels: app: demo-ssl template: metadata: labels: app: demo-ssl spec: containers: - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1 imagePullPolicy: IfNotPresent name: demo-ssl ports: - containerPort: 8080 protocol: TCP --- apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/ssl-redirect: "true" name: demo-ssl namespace: default spec: ingressClassName: alb tls: - hosts: - ssl.alb.ingress.top rules: - host: ssl.alb.ingress.top http: paths: - backend: serviceName: demo-service-ssl servicePort: 80 path: / pathType: Prefix
apiVersion: v1 kind: Service metadata: name: demo-service-ssl namespace: default spec: ports: - name: port1 port: 80 protocol: TCP targetPort: 8080 selector: app: demo-ssl sessionAffinity: None type: NodePort --- apiVersion: apps/v1 kind: Deployment metadata: name: demo-ssl namespace: default spec: replicas: 1 selector: matchLabels: app: demo-ssl template: metadata: labels: app: demo-ssl spec: containers: - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1 imagePullPolicy: IfNotPresent name: demo-ssl ports: - containerPort: 8080 protocol: TCP --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/ssl-redirect: "true" name: demo-ssl namespace: default spec: ingressClassName: alb tls: - hosts: - ssl.alb.ingress.top rules: - host: ssl.alb.ingress.top http: paths: - backend: service: name: demo-service-ssl port: number: 80 path: / pathType: Prefix
Configure the HTTPS or gRPC protocol
ALB Ingresses support the HTTPS or gRPC protocol. To configure HTTPS or gRPC, add
the alb.ingress.kubernetes.io/backend-protocol: "grpc"
or alb.ingress.kubernetes.io/backend-protocol: "https"
annotation. If you want to use an Ingress to distribute requests to a gRPC service,
you must configure an SSL certificate for the gRPC service and use the TLS protocol
to communicate with the gRPC service. Example:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/backend-protocol: "grpc" name: lxd-grpc-ingress spec: ingressClassName: alb tls: - hosts: - demo.alb.ingress.top rules: - host: demo.alb.ingress.top http: paths: - backend: serviceName: grpc-demo-svc servicePort: 9080 path: / pathType: Prefix
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/backend-protocol: "grpc" name: lxd-grpc-ingress spec: ingressClassName: alb tls: - hosts: - demo.alb.ingress.top rules: - host: demo.alb.ingress.top http: paths: - path: / pathType: Prefix backend: service: name: grpc-demo-svc port: number: 9080
Configure rewrite rules
ALB Ingresses support rewrite rules. To configure rewrite rules, add the alb.ingress.kubernetes.io/rewrite-target: /path/${2}
annotation.
- In the
rewrite-target
annotation, you must set the type of thepath
parameter to Prefix for a capturing group of the${number}
type. - By default, the
path
parameter does not support characters that are supported by regular expressions, such as asterisks (*
) and question marks (?
). To specify characters that are supported by regular expressions in the path parameter, you must add therewrite-target
annotation. - The value of the
path
parameter must start with a forward slash (/
).
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/rewrite-target: /path/${2} name: rewrite-ingress spec: ingressClassName: alb rules: - host: demo.alb.ingress.top http: paths: - backend: serviceName: rewrite-svc servicePort: 9080 path: /something(/|$)(.*) pathType: Prefix
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/rewrite-target: /path/${2} name: rewrite-ingress spec: ingressClassName: alb rules: - host: demo.alb.ingress.top http: paths: - path: /something(/|$)(.*) pathType: Prefix backend: service: name: rewrite-svc port: number: 9080
Configure custom listening ports
ALB Ingresses allow you to configure custom listening ports. This allows you to expose port 80 and port 443 for a Service at the same time. Example:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]' name: cafe-ingress spec: ingressClassName: alb tls: - hosts: - demo.alb.ingress.top rules: - host: demo.alb.ingress.top http: paths: - backend: serviceName: tea-svc servicePort: 80 path: /tea-svc pathType: ImplementationSpecific
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]' spec: ingressClassName: alb tls: - hosts: - demo.alb.ingress.top rules: - host: demo.alb.ingress.top http: paths: - path: /tea pathType: ImplementationSpecific backend: service: name: tea-svc port: number: 80
Configure forwarding rule priorities
You can add an annotation to the configuration of an Ingress to configure the priorities of the forwarding rules of the Ingress.
alb.ingress.kubernetes.io/order
annotation to specify the priorities of the forwarding rules of an Ingress. Valid
values: 1 to 1000. A lower value indicates a higher priority.
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/order: "2" name: cafe-ingress spec: ingressClassName: alb rules: - host: demo.alb.ingress.top http: paths: - backend: serviceName: tea-svc servicePort: 80 path: /tea-svc pathType: ImplementationSpecific
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/order: "2" spec: ingressClassName: alb rules: - host: demo.alb.ingress.top http: paths: - path: /tea pathType: ImplementationSpecific backend: service: name: tea-svc port: number: 80
Use annotations to perform phased releases
ALB allows you to configure phased releases based on request headers, cookies, and
weights to handle complex traffic routing. You can add the alb.ingress.kubernetes.io/canary: "true"
annotation to enable the phased release feature. Then, you can use the following
annotations to configure different phased release rules.
alb.ingress.kubernetes.io/canary-by-header
andalb.ingress.kubernetes.io/canary-by-header-value
: This rule matches the headers and header values of requests. You must add both annotations if you want to use this rule.- If the
header
andheader value
of a request match the rule, the request is routed to the new application version. - If the
header
of a request fails to match theheader
-based rule, the request is matched against other types of rules based on the priorities of the rules.
location: hz
, requests that match the rule are routed to the new application version. Requests that fail to match the rule are routed based on weight-based rules. Example:apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/order: "1" alb.ingress.kubernetes.io/canary: "true" alb.ingress.kubernetes.io/canary-by-header: "location" alb.ingress.kubernetes.io/canary-by-header-value: "hz" name: demo-canary namespace: default spec: ingressClassName: alb rules: - http: paths: - backend: serviceName:demo-service-hello servicePort: 80 path: /hello pathType: ImplementationSpecific
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/order: "1" alb.ingress.kubernetes.io/canary: "true" alb.ingress.kubernetes.io/canary-by-header: "location" alb.ingress.kubernetes.io/canary-by-header-value: "hz" name: demo-canary namespace: default spec: ingressClassName: alb rules: - http: paths: - backend: service: name: demo-service-hello port: number: 80 path: /hello pathType: ImplementationSpecific
- If the
alb.ingress.kubernetes.io/canary-by-cookie
: This rule matches the cookies of requests.- If you set
cookie
toalways
, requests that match the rule are routed to the new application version. - If you set
cookie
tonever
, requests that match the rule are routed to the old application version.
Note Cookie-based phased release rules do not support other settings. The cookie value must bealways
ornever
.demo=always
cookie are routed to the new application version. Example:apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/order: "2" alb.ingress.kubernetes.io/canary: "true" alb.ingress.kubernetes.io/canary-by-cookie: "demo" name: demo-canary-cookie namespace: default spec: ingressClassName: alb rules: - http: paths: - backend: serviceName:demo-service-hello servicePort: 80 path: /hello pathType: ImplementationSpecific
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/order: "2" alb.ingress.kubernetes.io/canary: "true" alb.ingress.kubernetes.io/canary-by-cookie: "demo" name: demo-canary-cookie namespace: default spec: ingressClassName: alb rules: - http: paths: - backend: service: name: demo-service-hello port: number: 80 path: /hello pathType: ImplementationSpecific
- If you set
alb.ingress.kubernetes.io/canary-weight
: This rule allows you to set the percentage of requests that are sent to a specified Service. You can enter an integer from 0 to 100.In the following example, the percentage of requests that are routed to the new application version is set to 50%:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/order: "3" alb.ingress.kubernetes.io/canary: "true" alb.ingress.kubernetes.io/canary-weight: "50" name: demo-canary-weight namespace: default spec: ingressClassName: alb rules: - http: paths: - backend: serviceName: demo-service-hello servicePort: 80 path: /hello pathType: ImplementationSpecific
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/order: "3" alb.ingress.kubernetes.io/canary: "true" alb.ingress.kubernetes.io/canary-weight: "50" name: demo-canary-weight namespace: default spec: ingressClassName: alb rules: - http: paths: - backend: service: name: demo-service-hello port: number: 80 path: /hello pathType: ImplementationSpecific
Configure session persistence by using annotations
alb.ingress.kubernetes.io/sticky-session
: specifies whether to enable session persistence. Valid values:true
andfalse
. Default value:false
.alb.ingress.kubernetes.io/sticky-session-type
: the method that is used to handle a cookie. Valid values:Insert
andServer
. Default value:Insert
.Insert
: inserts a cookie. ALB inserts a cookie (SERVERID) into the first HTTP or HTTPS response packet that is sent to a client. The next request from the client contains this cookie and the listener distributes this request to the recorded backend server.Server
: rewrites a cookie. When CLB detects a user-defined cookie, it overwrites the original cookie with the user-defined cookie. The next request from the client will contain the user-defined cookie, and the listener will distribute this request to the recorded backend server.
Note This parameter takes effect when theStickySessionEnabled
parameter is set totrue
for the server group.alb.ingress.kubernetes.io/cookie-timeout
: specifies the timeout period of cookies. Valid values: 1 to 86400. Default value:1000
. Unit: seconds.
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: cafe-ingress-v3 annotations: alb.ingress.kubernetes.io/sticky-session: "true" alb.ingress.kubernetes.io/sticky-session-type: "Insert" alb.ingress.kubernetes.io/cookie-timeout: "1800" spec: ingressClassName: alb rules: - http: paths: # Configure a context path. - path: /tea2 backend: serviceName: tea-svc servicePort: 80 # Configure a context path. - path: /coffee2 backend: serviceName: coffee-svc servicePort: 80
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress-v3 annotations: alb.ingress.kubernetes.io/sticky-session: "true" alb.ingress.kubernetes.io/sticky-session-type: "Insert" alb.ingress.kubernetes.io/cookie-timeout: "1800" spec: ingressClassName: alb rules: - http: paths: # Configure a context path. - path: /tea2 backend: service: name: tea-svc port: number: 80 # Configure a context path. - path: /coffee2 backend: service: name: coffee-svc port: number: 80