Microservices Engine:Advanced usage of MSE Ingress

Examples:

• If the request header is mse:always, requests are sent to the canary version demo-service-canary. In other cases, requests are sent to the base version demo-service. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-by-header: "mse"
    name: demo-canary
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - backend:
                service:
                  name: demo-service-canary
                  port: 
                    number: 80
              path: /hello
              pathType: Exact
  ---
  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /hello
              pathType: Exact          

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-by-header: "mse"
    name: demo-canary
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - path: /hello
              backend:
                serviceName: demo-service-canary
                servicePort: 80
  ---
  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - path: /hello
              backend:
                serviceName: demo-service
                servicePort: 80

• If the request header is mse:v1, requests are sent to the canary version demo-service-canary-v1. If the request header is mse:v2, requests are sent to the canary version demo-service-canary-v2. In other cases, requests are sent to the base version demo-service. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-by-header: "mse"
      nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
    name: demo-canary-v1
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - backend:
                service:
                  name: demo-service-canary-v1
                  port: 
                    number: 80
              path: /hello
              pathType: Exact
  ---
  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-by-header: "mse"
      nginx.ingress.kubernetes.io/canary-by-header-value: "v2"
    name: demo-canary-v2
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - backend:
                service:
                  name: demo-service-canary-v2
                  port: 
                    number: 80
              path: /hello
              pathType: Exact
  ---
  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /hello
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-by-header: "mse"
      nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
    name: demo-canary-v1
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - path: /hello
              backend:
                serviceName: demo-service-canary-v1
                servicePort: 80
  ---
  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-by-header: "mse"
      nginx.ingress.kubernetes.io/canary-by-header-value: "v2"
    name: demo-canary-v2
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - path: /hello
              backend:
                serviceName: demo-service-canary-v2
                servicePort: 80
  ---
  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - path: /hello
              backend:
                serviceName: demo-service
                servicePort: 80

You can perform a rewrite operation to modify the original paths and hosts in requests before the requests are forwarded to a destination backend service.

1. Before the example.com/test request is forwarded to the backend service, rewrite example.com/test as example.com/dev. Sample configurations:

   Clusters that run Kubernetes V1.19 or later

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     annotations:
       nginx.ingress.kubernetes.io/rewrite-target: "/dev"
     name: demo
   spec:
     ingressClassName: mse
     rules:
       - host: example.com
         http:
           paths:
             - backend:
                 service:
                   name: demo-service
                   port: 
                     number: 80
               path: /test
               pathType: Exact

   Clusters that run Kubernetes versions earlier than V1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     annotations:
       nginx.ingress.kubernetes.io/rewrite-target: "/dev"
     name: demo
   spec:
     ingressClassName: mse
     rules:
       - http:
           paths:
             - path: /test
               pathType: Exact
               backend:
                 serviceName: demo-service
                 servicePort: 80

2. Before the example.com/v1/xxx request is forwarded to the backend service, remove the prefix /v1 and rewrite the request as example.com/xxx. Sample configurations:

   Clusters that run Kubernetes V1.19 or later

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     annotations:
       nginx.ingress.kubernetes.io/rewrite-target: "/$1"
     name: demo
   spec:
     ingressClassName: mse
     rules:
       - host: example.com
         http:
           paths:
             - backend:
                 service:
                   name: demo-service
                   port: 
                     number: 80
               path: /v1/(.*)
               pathType: Prefix

   Clusters that run Kubernetes versions earlier than V1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     annotations:
       nginx.ingress.kubernetes.io/rewrite-target: "/$1"
     name: demo
   spec:
     ingressClassName: mse
     rules:
       - http:
           paths:
             - path: /v1/(.*) 
             	pathType: Prefix
               backend:
                 serviceName: demo-service
                 servicePort: 80

3. Before the example.com/v1/xxx request is forwarded to the backend service, change the prefix /v1 to /v2 and rewrite the request as example.com/v2/xxx. Sample configurations:

   Clusters that run Kubernetes V1.19 or later

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     annotations:
       nginx.ingress.kubernetes.io/rewrite-target: "/v2/$1"
     name: demo
   spec:
     ingressClassName: mse
     rules:
       - host: example.com
         http:
           paths:
             - backend:
                 service:
                   name: demo-service
                   port: 
                     number: 80
               path: /v1/(.*)
               pathType: Prefix

   Clusters that run Kubernetes versions earlier than V1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     annotations:
       nginx.ingress.kubernetes.io/rewrite-target: "/v2/$1"
     name: demo
   spec:
     ingressClassName: mse
     rules:
       - http:
           paths:
             - path: /v1/(.*)
               pathType: Prefix
               backend:
                 serviceName: demo-service
                 servicePort: 80

Examples:

• Add the headers foo: bar and test: true to the request example.com/test. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/request-header-control-add: |
        foo bar
        test true
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/request-header-control-add: |
        foo bar
        test true
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com 
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

• Header control can be used with canary releases to identify the requests that are sent to the canary version. If the request header is mse: v1, the request is sent to the canary version demo-service-canary-v1 and the header stage: gray is added to the request. In other cases, the request is sent to the base version demo-service and the header stage: production is added to the request. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-by-header: "mse"
      nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
      mse.ingress.kubernetes.io/request-header-control-add: "stage gray"
    name: demo-canary-v1
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - backend:
                service:
                  name: demo-service-canary-v1
                  port: 
                    number: 80
              path: /hello
              pathType: Exact
  ---
  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/request-header-control-add: "stage production"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /hello
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-by-header: "mse"
      nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
      mse.ingress.kubernetes.io/request-header-control-add: "stage gray"
    name: demo-canary-v1
  spec:
    ingressClassName: mse
    rules:
      - http:
          paths:
            - path: /hello
              backend:
                serviceName: demo-service-canary-v1
                servicePort: 80
  ---
  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/request-header-control-add: |
        foo bar
        test true
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com 
        http:
          paths:
            - path: /hello
              backend:
                serviceName: demo-service
                servicePort: 80

Examples:

• Allow access to example.com/test from the client IP address 1.1.xx.xx. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/whitelist-source-range: 1.1.X.X
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/whitelist-source-range: 1.1.X.X
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com 
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

• Deny access to example.com/test from the client IP address 2.2.xx.xx. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/blacklist-source-range: 2.2.2.2
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/blacklist-source-range: 2.2.2.2
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

Examples:

• Allow access to all routes of the domain name example.com from the client IP addresses 1.1.xx.xx and 2.2.xx.xx. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact
           - backend:
                service:
                  name: app-service
                  port: 
                    number: 80
              path: /app
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80
            - path: /app
              backend:
                serviceName: app-service
                servicePort: 80

• Use IP address whitelists and blacklists at the domain name level with IP address whitelists and blacklists at the route level. Allow access to all routes of the example.com domain name from the client IP addresses 1.1.xx.xx and 2.2.xx.xx, and allow access to the example.com/order route only from the client IP address 3.3.xx.xx. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
    name: demo-domain
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact
           - backend:
                service:
                  name: app-service
                  port: 
                    number: 80
              path: /app
              pathType: Exact
  ---
  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/whitelist-source-range: 3.3.X.X
    name: demo-route
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /order
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
    name: demo-domain
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80
            - path: /app
              backend:
                serviceName: app-service
                servicePort: 80
  ---
  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/whitelist-source-range: 3.3.X.X
    name: demo-route
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /order
              backend:
                serviceName: demo-service
                servicePort: 80

Examples:

• For the example.com/test request, set the maximum number of RPM to 100 and the burst limit for the maximum number of RPM to 200. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/route-limit-rpm: "100"
      mse.ingress.kubernetes.io/route-limit-burst-multiplier: "2"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/route-limit-rpm: "100"
      mse.ingress.kubernetes.io/route-limit-burst-multiplier: "2"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

• For the example.com/test request, set the maximum number of RPS to 10 and the burst limit for the maximum number of RPS to 50. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/route-limit-rps: "10"
      # The default value is 5.
      # mse.ingress.kubernetes.io/route-limit-burst-multiplier: "5"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      mse.ingress.kubernetes.io/route-limit-rps: "10"
      # The default value is 5.
      # mse.ingress.kubernetes.io/route-limit-burst-multiplier: "5"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

Example 1: Set the maximum number of example.com/test requests processed on a gateway cluster to 1000 and retain the default concurrency control behavior. Sample configurations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

Example 2: Set the maximum number of requests from example.com/test that are processed on a gateway cluster to 1,000 and set the response code to 503 and response body to server is overloaded when concurrency control is triggered.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code: 503
    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body: "server is overload"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code: 503
    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body: "server is overload"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

Examples:

• Use HTTPS to forward the example/test request to a backend service. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

• Use gRPC to forward the example/test request to a backend service. The following methods can be used:

  • Method 1: Use annotations. Sample configurations:

    Clusters that run Kubernetes V1.19 or later

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      annotations:
        nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
      name: demo
    spec:
      ingressClassName: mse
      rules:
        - host: example.com
          http:
            paths:
              - backend:
                  service:
                    name: demo-service
                    port: 
                      number: 80
                path: /test
                pathType: Exact

    Clusters that run Kubernetes versions earlier than V1.19

    apiVersion: networking.k8s.io/v1beta1
    kind: Ingress
    metadata:
      annotations:
        nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
      name: demo
    spec:
      ingressClassName: mse
      rules:
        - host: example.com
          http:
            paths:
              - path: /test
                backend:
                  serviceName: demo-service
                  servicePort: 80

  • Method 2: Use spec > ports > name in Ingress resource configurations. Sample configurations:

    Clusters that run Kubernetes V1.19 or later

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: demo
    spec:
      ingressClassName: mse
      rules:
        - host: example.com
          http:
            paths:
              - backend:
                  service:
                    name: demo-service
                    port: 
                      number: 80
                path: /order
                pathType: Exact
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: demo-service
    spec:
      ports:
        - name: grpc
          port: 80
          protocol: TCP
      selector:
        app: demo-service

    Clusters that run Kubernetes versions earlier than V1.19

    apiVersion: networking.k8s.io/v1beta1
    kind: Ingress
    metadata:
      name: demo
    spec:
      ingressClassName: mse
      rules:
        - host: example.com
          http:
            paths:
              - path: /test
                backend:
                  serviceName: demo-service
                  servicePort: 80
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: demo-service
    spec:
      ports:
        - name: grpc
          port: 80
          protocol: TCP
      selector:
        app: demo-service

nginx.ingress.kubernetes.io/load-balance: specifies the common load balancing algorithm that is used by a backend service. Default value: round_robin. Valid values:

• round_robin: load balancing based on round robin.

• least_conn: load balancing based on least connections.

• random: randomized load balancing.

nginx.ingress.kubernetes.io/upstream-hash-by: specifies the load balancing algorithm based on consistent hashing. Cloud-native gateways support the following types of consistent hashing:

• Consistent hashing based on NGINX variables:

  • $request_uri: the request path, which is used as the hash key. Path parameters are included.

  • $host: the request host, which is used as the hash key.

  • $remote_addr: the client IP address, which is used as the hash key.

• Consistent hashing based on request headers. You need only to configure $http_headerName.

• Consistent hashing based on request path parameters. You need only to configure $arg_varName.

Examples:

• Use a client IP address for requests as the hash key. Requests from the client IP address are always distributed to the same node. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

• Use the request header X-Stage as the hash key, and distribute requests with the same value of the request header X-Stage to the same node. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/upstream-hash-by: "$http_x-stage"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/upstream-hash-by: "$http_x-stage"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

• Use the request path parameter X-Stage as the hash key, and distribute requests with the same value of the request path parameter X-Stage to the same node. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_x-stage"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_x-stage"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

Examples:

• Enable cookie affinity and use the default configuration of MSE Ingress. Set the cookie name to INGRESSCOOKIE, set the path to /, and configure the lifecycle of the cookie at the session level. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/affinity: "cookie"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/affinity: "cookie"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

• Enable cookie affinity and set the cookie name to test, the path to /, and the expiration time of the cookie to 10s. Sample configurations:

  Clusters that run Kubernetes V1.19 or later

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/affinity: "cookie"
      nginx.ingress.kubernetes.io/session-cookie-name: "test"
      nginx.ingress.kubernetes.io/session-cookie-max-age: "10"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /test
              pathType: Exact

  Clusters that run Kubernetes versions earlier than V1.19

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      nginx.ingress.kubernetes.io/affinity: "cookie"
      nginx.ingress.kubernetes.io/session-cookie-name: "test"
      nginx.ingress.kubernetes.io/session-cookie-max-age: "10"
    name: demo
  spec:
    ingressClassName: mse
    rules:
      - host: example.com
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

The default earliest TLS version that is supported by MSE Ingress is TLSv1.0. The default latest TLS version is TLSv1.3. By default, the following cipher suites are used:

• ECDHE-ECDSA-AES128-GCM-SHA256

• ECDHE-RSA-AES128-GCM-SHA256

• ECDHE-ECDSA-AES128-SHA

• ECDHE-RSA-AES128-SHA

• AES128-GCM-SHA256

• AES128-SHA

• ECDHE-ECDSA-AES256-GCM-SHA384

• ECDHE-RSA-AES256-GCM-SHA384

• ECDHE-ECDSA-AES256-SHA

• ECDHE-RSA-AES256-SHA

• AES256-GCM-SHA384

• AES256-SHA

The following table describes the annotations that can be used to specify the earliest or latest TLS version and cipher suites for a specific domain name.