API Gateway:高度な APIG Ingress の使用方法

例：

• リクエストヘッダーが apig: always の場合、リクエストは `demo-service-canary` カナリーサービスにアクセスします。それ以外の場合、`demo-service` 安定版サービスにアクセスします。以下のように設定します：

  Kubernetes バージョン 1.19 以降のクラスター

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

  Kubernetes バージョン 1.19 より前のクラスター

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

• リクエストヘッダーが apig: v1 の場合、リクエストは `demo-service-canary-v1` カナリーサービスにアクセスします。リクエストヘッダーが apig: v2 の場合、`demo-service-canary-v2` カナリーサービスにアクセスします。それ以外の場合、`demo-service` 安定版サービスにアクセスします。以下のように設定します：

  Kubernetes バージョン 1.19 以降のクラスター

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

  Kubernetes バージョン 1.19 より前のクラスター

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

1. リクエスト example.com/test をバックエンドサービスに転送する前に、example.com/dev に再書き込みします。以下のように設定します：

   Kubernetes 1.19 以降のクラスター

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

   Kubernetes 1.19 より前のクラスター

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

2. /v1/ で始まるプレフィックスを持つリクエスト（例：example.com/v1/xxx）をバックエンドサービスに転送する前に、パスプレフィックス /v1 を削除し、example.com/xxx に再書き込みします。以下のように設定します：

   Kubernetes 1.19 以降のクラスター

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

   Kubernetes 1.19 より前のクラスター

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

3. /v1/ で始まるプレフィックスを持つリクエスト（例：example.com/v1/xxx）をバックエンドサービスに転送する前に、パスプレフィックス /v1 を /v2 に変更し、example.com/v2/xxx に再書き込みします。以下のように設定します：

   Kubernetes 1.19 以降のクラスター

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

   Kubernetes 1.19 より前のクラスター

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

例：

• example.com/test に対するリクエストに、2 つのヘッダー（foo: bar、test: true）を追加します。以下のように設定します：

  Kubernetes 1.19 以降を実行するクラスター

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

  Kubernetes 1.19 より前のバージョンを実行するクラスター

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

• カナリーリリースとヘッダー制御を組み合わせて、カナリー通信をタグ付けします。リクエストヘッダー apig: v1 が存在する場合、トラフィックをカナリーサービス demo-service-canary-v1 にルーティングし、ヘッダー stage: gray を追加します。それ以外のすべてのリクエストでは、トラフィックを本番サービス demo-service にルーティングし、ヘッダー stage: production を追加します。以下のように設定します：

  Kubernetes 1.19 以降を実行するクラスター

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

  Kubernetes 1.19 より前のバージョンを実行するクラスター

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

例：

• クライアント IP アドレス 1.1.X.X のみからの example.com/test へのアクセスを許可するには、以下の構成を使用します：

  バージョン 1.19 以降のクラスター

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

  バージョン 1.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: apig
    rules:
      - host: example.com 
        http:
          paths:
            - path: /test
              backend:
                serviceName: demo-service
                servicePort: 80

• クライアント IP アドレス 2.2.2.2 からの example.com/test へのアクセスを拒否するには、以下の構成を使用します：

  バージョン 1.19 以降のクラスター

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

  バージョン 1.19 より前のクラスター

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

例：

• example.com ドメイン名のすべてのルートへのアクセスを、クライアント IP アドレス 1.1.X.X および 2.2.2.2 のみから許可するには、以下の構成を使用します：

  バージョン 1.19 以降のクラスター

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      higress.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
    name: demo
  spec:
    ingressClassName: apig
    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

  バージョン 1.19 より前のクラスター

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

• ドメインレベルおよびルートレベルの IP アクセス制御を組み合わせます。例として、クライアント IP アドレス 1.1.X.X および 2.2.2.2 からの example.com ドメインのすべてのルートへのアクセスを許可し、クライアント IP アドレス 3.3.X.X からのみ example.com/order ルートへのアクセスを許可するには、以下の構成を使用します：

  バージョン 1.19 以降のクラスター

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      higress.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
    name: demo-domain
  spec:
    ingressClassName: apig
    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: apig
    rules:
      - host: example.com
        http:
          paths:
            - backend:
                service:
                  name: demo-service
                  port: 
                    number: 80
              path: /order
              pathType: Exact

  バージョン 1.19 より前のクラスター

  apiVersion: networking.k8s.io/v1beta1
  kind: Ingress
  metadata:
    annotations:
      higress.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
    name: demo-domain
  spec:
    ingressClassName: apig
    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: apig
    rules:
      - host: example.com
        http:
          paths:
            - path: /order
              backend:
                serviceName: demo-service
                servicePort: 80

例 1: ゲートウェイクラスター全体で example.com/test への同時リクエストの最大数を 1000 に制限します。デフォルトの同時実行制御動作を使用します。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.ingress.kubernetes.io/concurrency-limit: "1000"
  name: demo
spec:
  ingressClassName: apig
  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:
    higress.ingress.kubernetes.io/concurrency-limit: "1000"
  name: demo
spec:
  ingressClassName: apig
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

例 2: ゲートウェイクラスター全体で example.com/test への同時リクエストの最大数を 1000 に制限します。同時実行制御がトリガーされたときに、状態コード 503 と応答本文 server is overloaded を返します。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.ingress.kubernetes.io/concurrency-limit: "1000"
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code: 503
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body: "server is overload"
  name: demo
spec:
  ingressClassName: apig
  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:
    higress.ingress.kubernetes.io/concurrency-limit: "1000"
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code: 503
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body: "server is overload"
  name: demo
spec:
  ingressClassName: apig
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

nginx.ingress.kubernetes.io/load-balance: バックエンドサービスの標準の負荷分散アルゴリズムです。デフォルト値は round_robin です。有効な値は次のとおりです：

• round_robin: ラウンドロビン負荷分散。

• least_conn: 最小接続負荷分散。

• random: ランダム負荷分散。

nginx.ingress.kubernetes.io/upstream-hash-by: コンシステントハッシュ負荷分散アルゴリズムです。クラウドネイティブゲートウェイは、次のハッシュキータイプをサポートしています：

• クラウドネイティブゲートウェイは、選択された NGINX 変数をサポートしています：

  • $request_uri: パスパラメーターを含むリクエストパスがハッシュキーとして使用されます。

  • $host: リクエストホストヘッダーをハッシュキーとして使用します。

  • $remote_addr: クライアント IP アドレスをハッシュキーとして使用します。

• リクエストヘッダーに基づくコンシステントハッシュ。アノテーションを $http_headerName に設定します。

• リクエストパスパラメーターに基づくコンシステントハッシュ。アノテーションを $arg_varName に設定します。

例：

• クライアント IP アドレスをハッシュキーとして使用します。同じクライアント IP からのリクエストは、常に同じノードに転送されます。次のように設定します：

  Kubernetes 1.19 以降を実行するクラスター

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

  Kubernetes 1.19 より前のバージョンを実行するクラスター

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

• x-stage リクエストヘッダーをハッシュキーとして使用します。同じ x-stage ヘッダー値を持つリクエストは、常に同じノードに転送されます。次のように設定します：

  Kubernetes 1.19 以降を実行するクラスター

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

  Kubernetes 1.19 より前のバージョンを実行するクラスター

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

• x-stage パスパラメーターをハッシュキーとして使用します。同じ x-stage パスパラメーター値を持つリクエストは、常に同じノードに転送されます。次のように設定します：

  Kubernetes 1.19 以降を実行するクラスター

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

  Kubernetes 1.19 より前のバージョンを実行するクラスター

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