Wallarmモジュールを統合したEOLのNGINX Ingress controllerのアップグレード¶

本書では、サポート終了（EOL）のWallarm Ingress Controller（バージョン3.6以下）を、Wallarmノード6.xを搭載した新バージョンへアップグレードする手順を説明します。

Wallarm nodes 3.6 and lower are not supported

You are recommended to upgrade the Wallarm nodes 3.6 and lower since these versions are not supported, they are end-of-life.

Node configuration and traffic filtration have been significantly simplified in the Wallarm node of the latest versions. Before upgrading the modules, please carefully review the list of changes and general recommendations. Please note that some settings of the latest node are incompatible with the nodes 3.6 and lower.

アップグレードされるCommunity Ingress NGINX Controllerのバージョン

ノードを3.4以下からアップグレードする場合、Wallarm Ingress controllerのベースとなるCommunity Ingress NGINX Controllerのバージョンが0.26.2から1.11.5に更新されている点にご注意ください。

Community Ingress NGINX Controller 1.11.5では動作が大きく変更されているため、Wallarm Ingress controllerのアップグレード時に、これらの変更に合わせて構成を調整する必要があります。

本書には、変更が必要となる可能性が高いCommunity Ingress NGINX Controllerの設定の一覧が含まれます。ただし、Community Ingress NGINX Controllerのリリースノートに基づき、構成移行の個別計画を必ず策定してください。

要件¶

Kubernetes platform version 1.26-1.30
Helm package manager
Compatibility of your services with the Community Ingress NGINX Controller version 1.11.8
Access to the account with the Administrator role in Wallarm Console for the US Cloud or EU Cloud
Access to https://us1.api.wallarm.com for working with US Wallarm Cloud or to https://api.wallarm.com for working with EU Wallarm Cloud
Access to https://charts.wallarm.com to add the Wallarm Helm charts. Ensure the access is not blocked by a firewall
Access to the Wallarm repositories on Docker Hub https://hub.docker.com/r/wallarm. Make sure the access is not blocked by a firewall
Access to the IP addresses and their corresponding hostnames (if any) listed below. This is needed for downloading updates to attack detection rules and API specifications, as well as retrieving precise IPs for your allowlisted, denylisted, or graylisted countries, regions, or data centers
US CloudEU Cloud
node-data0.us1.wallarm.com - 34.96.64.17 node-data1.us1.wallarm.com - 34.110.183.149 us1.api.wallarm.com - 35.235.66.155 34.102.90.100 34.94.156.115 35.235.115.105
node-data1.eu1.wallarm.com - 34.160.38.183 node-data0.eu1.wallarm.com - 34.144.227.90 api.wallarm.com - 34.90.110.226

手順1: フィルタリングノードモジュールをアップグレードすることをWallarmテクニカルサポートに通知します（ノード2.18以下のアップグレード時のみ）¶

ノード2.18以下からアップグレードする場合、Wallarmテクニカルサポートにフィルタリングノードモジュールを6.xまで更新する旨を連絡し、Wallarmアカウントに対して新しいIPリストロジックの有効化を依頼してください。

新しいIPリストロジックが有効化されたら、Wallarm Consoleを開き、IP listsセクションが利用可能であることを確認してください。

手順2: Threat Replay Testingモジュールを無効化します（ノード2.16以下のアップグレード時のみ）¶

Wallarmノード2.16以下からアップグレードする場合、Wallarm Console → Vulnerabilities → ConfigureでThreat Replay Testingモジュールを無効化してください。

アップグレード中のモジュール動作により誤検知が発生する可能性があります。モジュールを無効化することで、このリスクを最小限に抑えられます。

手順3: APIポートを更新する¶

Starting with version 4.0, the filtering node uploads data to the Cloud using the us1.api.wallarm.com:443 (US Cloud) and api.wallarm.com:443 (EU Cloud) API endpoints instead of us1.api.wallarm.com:444 and api.wallarm.com:444.

If you upgrade the node from the version 3.x or lower and your server with the deployed node has a limited access to the external resources and the access is granted to each resource separately, then after upgrade the synchronization between the filtering node and the Cloud will stop.

To restore the synchronization, in your configuration, change port 444 to 443 for API endpoint for each resource.

手順4: Wallarm Helmチャートリポジトリを更新する¶

Helmリポジトリを使用する場合クローンしたGitHubリポジトリを使用する場合

helm repo update wallarm

すべてのチャートバージョンを含むWallarm Helmリポジトリを以下のコマンドで追加してください。以降のWallarm Ingress controllerの操作には、Helmリポジトリを使用してください。

helm repo add wallarm https://charts.wallarm.com
helm repo update wallarm

手順5: `values.yaml`設定を更新する¶

Wallarm Ingress controller 6.xへ移行するには、values.yamlファイルで指定している以下の構成を更新します。

Community Ingress NGINX Controllerの標準構成
Wallarmモジュールの構成

Community Ingress NGINX Controllerの標準構成¶

Community Ingress NGINX Controllerのリリースノート（0.27.0以上）を確認し、values.yamlで変更が必要な設定を特定します。
特定した設定をvalues.yamlで更新します。

変更が必要となる可能性がある設定は次のとおりです。

リクエストがロードバランサを経由してWallarm Ingress controllerに送信される場合の、エンドユーザ公開IPアドレスの正確な報告。
```
controller:
  config:
-    use-forwarded-headers: "true"
+    enable-real-ip: "true"
+    forwarded-for-header: "X-Forwarded-For"
```
IngressClassの構成。新しいIngress controllerでは使用するKubernetes APIのバージョンが更新されており、.controller.ingressClass、.controller.ingressClassResource、.controller.watchIngressWithoutClassパラメータでIngressClassを構成する必要があります。
```
controller:
+  ingressClass: waf-ingress
+  ingressClassResource:
+    name: waf-ingress
+    default: true
+  watchIngressWithoutClass: true
```

ConfigMap（.controller.config）のパラメータセット。例:

controller:
config:
+  allow-backend-server-header: "false"
  enable-brotli: "true"
  gzip-level: "3"
  hide-headers: Server
  server-snippet: |
    proxy_request_buffering on;
    wallarm_enable_libdetection on;

"admission webhook"によるIngress構文の検証がデフォルトで有効になりました。
```
controller:
+  admissionWebhooks:
+    enabled: true
```
Ingress構文検証の無効化

Ingressオブジェクトの動作を不安定にする場合に限り、Ingress構文検証を無効化することを推奨します。

ラベル形式。values.yamlでPodアフィニティルールを設定している場合、以下のようにラベル形式を変更してください。

controller:
  affinity:
    podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - podAffinityTerm:
        labelSelector:
            matchExpressions:
-            - key: app
+            - key: app.kubernetes.io/name
            operator: In
            values:
            - waf-ingress
-            - key: component
+            - key: app.kubernetes.io/component
            operator: In
            values:
-              - waf-ingress
+              - controller
-            - key: release
+            - key: app.kubernetes.io/instance
            operator: In
            values:
            - waf-ingress-ingress
        topologyKey: kubernetes.io/hostname
        weight: 100

Wallarmモジュールの構成¶

values.yamlで設定しているWallarmモジュールの構成を次のとおり変更します。

バージョン2.18以下からアップグレードする場合、IPリスト構成を移行してください。values.yamlから削除される可能性があるパラメータは次のとおりです。
```
controller:
  wallarm:
    enabled: true
    - acl:
    -  enabled: true
    resources: {}
```
Wallarmノード3.xではIPリストの中核ロジックが大幅に変更されているため、IPリスト構成をそれに合わせて調整する必要があります。
Tarantoolからwstoreへの移行に伴い、Helmの値名がcontroller.wallarm.tarantool → controller.wallarm.postanalyticsに変更されました。ポストアナリティクス用メモリを明示的に割り当てている場合は、values.yamlにこの変更を適用してください。
Node deployment/Deployment用途のAPIトークンを生成し、その値をcontroller.wallarm.tokenパラメータに設定してください。
以下の設定で期待する挙動が、offおよびmonitoringフィルタリングモードの変更後のロジックと一致していることを確認してください。
期待する挙動が変更後のフィルタリングモードロジックと一致しない場合は、Ingressアノテーションやその他の設定を変更点に合わせて調整してください。
明示的な監視サービスの構成は不要です。新しいWallarm Ingress controllerでは監視サービスがデフォルトで有効化され、追加設定は不要です。
```
controller:
wallarm:
  enabled: true
-  tarantool:
+  wstore:
    resources: {}
-  metrics:
-    enabled: true
-    service:
-      annotations: {}
```
ConfigMapで設定したページ&/usr/share/nginx/html/wallarm_blocked.htmlがブロック時のレスポンスとして返される場合、提供された変更に合わせて設定を調整してください。

新しいノードバージョンでは、Wallarmのサンプルブロッキングページは新しいブロッキングページに示すとおり、デフォルトでロゴとサポートメールが表示されない更新UIになりました。
wallarm_process_time_limitおよびwallarm_process_time_limit_blockというNGINXディレクティブでoverlimit_res攻撃検出をカスタマイズしている場合は、この設定をルールへ移行し、values.yamlから削除してください。

手順6: `overlimit_res`攻撃検出の設定をディレクティブからルールへ移行する¶

Starting from the version 3.6, you can fine-tune the overlimit_res attack detection using the rule in Wallarm Console.

Earlier, the wallarm_process_time_limit and wallarm_process_time_limit_block NGINX directives have been used. The listed directives are considered to be deprecated with the new rule release and will be deleted in future releases.

If the overlimit_res attack detection settings are customized via the listed directives, it is recommended to transfer them to the rule as follows:

Open Wallarm Console → Rules and proceed to the Limit request processing time rule setup.
Configure the rule as done via the NGINX directives:
- The rule condition should match the NGINX configuration block with the wallarm_process_time_limit and wallarm_process_time_limit_block directives specified.
- The time limit for the node to process a single request (milliseconds): the value of wallarm_process_time_limit.
  
  Risk of running out of system memory
  
  The high time limit and/or continuation of request processing after the limit is exceeded can trigger memory exhaustion or out-of-time request processing.
- The node will either block or pass the overlimit_res attack depending on the node filtration mode:
  - In the monitoring mode, the node forwards the original request to the application address. The application has the risk to be exploited by the attacks included in both processed and unprocessed request parts.
  - In the safe blocking mode, the node blocks the request if it is originated from the graylisted IP address. Otherwise, the node forwards the original request to the application address. The application has the risk to be exploited by the attacks included in both processed and unprocessed request parts.
  - In the block mode, the node blocks the request.
Delete the wallarm_process_time_limit and wallarm_process_time_limit_block NGINX directives from the values.yaml configuration file.

If the overlimit_res attack detection is fine-tuned using both the directives and the rule, the node will process requests as the rule sets.

手順7: 反映されるK8sマニフェストの変更をすべて確認する¶

Ingress controllerの挙動が予期せず変化しないよう、Helm Diff Pluginを使用して、反映予定のK8sマニフェスト差分を確認してください。このプラグインは、現在デプロイ中のIngress controllerバージョンと新バージョンのK8sマニフェストの差分を出力します。

プラグインのインストールと実行:

プラグインをインストールします。

helm plugin install https://github.com/databus23/helm-diff

プラグインを実行します。
```
helm diff upgrade <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 6.4.0 -f <PATH_TO_VALUES>
```
- <RELEASE_NAME>: Ingress controllerチャートのHelmリリース名
- <NAMESPACE>: Ingress controllerをデプロイしているNamespace
- <PATH_TO_VALUES>: Ingress controller 6.xの設定を定義するvalues.yamlファイルのパス
変更が稼働中サービスの安定性に影響しないことを確認し、stdoutに出力されたエラーを慎重に確認してください。

stdoutが空の場合は、values.yamlが正しいことを確認してください。

以下の構成の変更に注意してください。

変更不可能なフィールド（例: DeploymentやStatefulSetのセレクタ）。

Podラベル。以下のような変更により、NetworkPolicyの動作が停止する可能性があります。

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
spec:
  egress:
  - to:
    - namespaceSelector:
        matchExpressions:
        - key: name
          operator: In
          values:
          - kube-system # ${NAMESPACE}
      podSelector:
        matchLabels: # RELEASE_NAME=waf-ingress
-         app: waf-ingress
+         app.kubernetes.io/component: "controller"
+         app.kubernetes.io/instance: "waf-ingress"
+         app.kubernetes.io/name: "waf-ingress"
-         component: waf-ingress

Prometheusの新しいラベルでの構成。例:

 - job_name: 'kubernetes-ingress'
   kubernetes_sd_configs:
   - role: pod
     namespaces:
       names:
         - kube-system # ${NAMESPACE}
   relabel_configs: # RELEASE_NAME=waf-ingress
     # セレクタ
-    - source_labels: [__meta_kubernetes_pod_label_app]
+    - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
       action: keep
       regex: waf-ingress
-    - source_labels: [__meta_kubernetes_pod_label_release]
+    - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_instance]
       action: keep
       regex: waf-ingress
-    - source_labels: [__meta_kubernetes_pod_label_component]
+    - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_component]
       action: keep
-      regex: waf-ingress
+      regex: controller
     - source_labels: [__meta_kubernetes_pod_container_port_number]
       action: keep
       regex: "10254|18080"
       # 置換
     - action: replace
       target_label: __metrics_path__
       regex: /metrics
     - action: labelmap
       regex: __meta_kubernetes_pod_label_(.+)
     - source_labels: [__meta_kubernetes_namespace]
       action: replace
       target_label: kubernetes_namespace
     - source_labels: [__meta_kubernetes_pod_name]
       action: replace
       target_label: kubernetes_pod_name
     - source_labels: [__meta_kubernetes_pod_name]
       regex: (.*)
       action: replace
       target_label: instance
       replacement: "$1"

その他の変更も分析してください。

手順8: Ingress controllerをアップグレードする¶

Wallarm Ingress controllerのアップグレード方法は3通りあります。環境にロードバランサがあるかどうかに応じて、以下から選択してください。

一時的なIngress controllerのデプロイ
Ingress controllerリリースの通常の再作成
ロードバランサに影響を与えないIngress controllerリリースの再作成

ステージング環境またはminikubeの利用

Wallarm Ingress controllerがステージング環境にデプロイされている場合は、まずステージングをアップグレードすることを推奨します。ステージング環境で全サービスが正しく動作することを確認できたら、本番環境のアップグレードに進んでください。

そうでなければ、先にminikubeや他のサービスを用いて、更新済み構成でWallarm Ingress controller 6.xをデプロイすることを推奨します。すべてのサービスが期待どおり動作することを確認してから、本番環境のIngress controllerをアップグレードしてください。

このアプローチにより、本番環境のダウンタイムを回避しやすくなります。

方法1: 一時的なIngress controllerのデプロイ¶

この方法では、環境にIngress Controller 6.xを追加でデプロイし、トラフィックを段階的に切り替えられます。サービスの一時的な停止も避けられ、安全に移行できます。

旧バージョンのvalues.yamlからIngressClassの構成を、Ingress controller 6.x用のvalues.yamlにコピーします。

この構成により、Ingress controllerはIngressオブジェクトを認識しますが、そのトラフィックは処理しません。
Ingress controller 6.xをデプロイします。
```
helm install <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 6.4.0 -f <PATH_TO_VALUES>
```
- <RELEASE_NAME>: Ingress controllerチャートのHelmリリース名
- <NAMESPACE>: Ingress controllerをデプロイするNamespace
- <PATH_TO_VALUES>: Ingress controller 6.xの設定を定義するvalues.yamlファイルのパス
すべてのサービスが正しく動作することを確認します。
新しいIngress controllerへ段階的に負荷を切り替えます。

方法2: Ingress controllerリリースの通常の再作成¶

ロードバランサとIngress controllerが同一のHelmチャートで定義されていない場合は、Helmリリースを再作成するだけで構いません。数分かかり、その間Ingress controllerは利用できません。

Helmチャートでロードバランサの構成も設定している場合

HelmチャートでロードバランサとIngress controllerを併せて構成している場合、リリースの再作成によりロードバランサが長時間ダウンする可能性があります（クラウドプロバイダに依存）。固定アドレスを割り当てていない場合、アップグレード後にロードバランサのIPアドレスが変更される可能性もあります。

この方法を選択する場合は、想定される全リスクを分析してください。

Ingress controllerリリースを再作成するには:

Helm CLITerraform CLI

旧リリースを削除します。
```
helm delete <RELEASE_NAME> -n <NAMESPACE>
```
- <RELEASE_NAME>: Ingress controllerチャートのHelmリリース名
- <NAMESPACE>: Ingress controllerをデプロイしているNamespace
実行時に--waitオプションは使用しないでください。アップグレード時間が延びる可能性があります。
Ingress controller 6.xで新しいリリースを作成します。
```
helm install <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 6.4.0 -f <PATH_TO_VALUES>
```
- <RELEASE_NAME>: Ingress controllerチャートのHelmリリース名
- <NAMESPACE>: Ingress controllerをデプロイするNamespace
- <PATH_TO_VALUES>: Ingress controller 6.xの設定を定義するvalues.yamlファイルのパス

アップグレード時間を短縮するため、Terraform構成でwait = falseオプションを設定します。
```
resource "helm_release" "release" {
  ...

+ wait = false

  ...
}
```
旧リリースを削除します。
```
terraform taint helm_release.release
```
Ingress controller 6.xで新しいリリースを作成します。
```
terraform apply -target=helm_release.release
```

方法3: ロードバランサに影響を与えないIngress controllerリリースの再作成¶

クラウドプロバイダが構成したロードバランサを使用している場合は、ロードバランサに影響を与えないこの方法でIngress controllerをアップグレードすることを推奨します。

リリースの再作成には数分かかり、その間Ingress controllerは利用できません。

（ロードバランサを除く）削除対象のオブジェクトを取得します。
```
helm get manifest <RELEASE_NAME> -n <NAMESPACE> | yq -r '. | select(.spec.type != "LoadBalancer") | .kind + "/" + .metadata.name' | tr 'A-Z' 'a-z' > objects-to-remove.txt
```
ユーティリティyqのインストールは、こちらの手順を参照してください。

削除対象オブジェクトはobjects-to-remove.txtファイルに出力されます。

列挙したオブジェクトを削除し、リリースを再作成します。

cat objects-to-remove.txt | xargs kubectl delete --wait=false -n <NAMESPACE>    && \
helm upgrade <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 6.4.0 -f `<PATH_TO_VALUES>`

サービスのダウンタイムを短縮するため、コマンドは別々に実行しないことを推奨します。

すべてのオブジェクトが作成されたことを確認します。
```
helm get manifest <RELEASE_NAME> -n <NAMESPACE> | kubectl create -f -
```
すべてのオブジェクトが既に存在する旨の出力が表示されるはずです。

上記のコマンドで使用するパラメータは次のとおりです。

<RELEASE_NAME>: Ingress controllerチャートのHelmリリース名
<NAMESPACE>: Ingress controllerをデプロイしているNamespace
<PATH_TO_VALUES>: Ingress controller 6.xの設定を定義するvalues.yamlファイルのパス

手順9: アップグレード済みIngress controllerをテストする¶

Helmチャートのバージョンが更新されたことを確認します。
```
helm ls
```
チャートバージョンはwallarm-ingress-6.4.0である必要があります。

WallarmのPodを取得します。

kubectl get pods -n <NAMESPACE> -l app.kubernetes.io/name=wallarm-ingress

PodのステータスはSTATUS: Runningで、READY: N/Nである必要があります。

NAME                                                                  READY   STATUS    RESTARTS   AGE
ingress-controller-wallarm-ingress-controller-6d659bd79b-952gl        3/3     Running   0          8m7s
ingress-controller-wallarm-ingress-controller-wallarm-wstore-7ddmgbfm 3/3     Running   0          8m7s

テスト用のPath Traversal攻撃をWallarm Ingress controllerのアドレスに送信します。
```
curl http://<INGRESS_CONTROLLER_IP>/etc/passwd
```
フィルタリングノードがblockモードで動作している場合、レスポンスとして403 Forbiddenコードが返り、攻撃はWallarm Console → Attacksに表示されます。

手順10: リリースされた変更に合わせてIngressアノテーションを調整する¶

Ingress controller 6.xでリリースされた変更に合わせ、以下のIngressアノテーションを調整してください。

バージョン2.18以下からアップグレードする場合、IPリスト構成を移行してください。Wallarmノード3.xではIPリストの中核ロジックが大幅に変更されているため、（適用している場合は）Ingressアノテーションの変更により、IPリスト構成を適切に調整する必要があります。
以下の設定で期待する挙動が、offおよびmonitoringフィルタリングモードの変更後のロジックと一致していることを確認してください。
期待する挙動が変更後のフィルタリングモードロジックと一致しない場合は、Ingressアノテーションを変更点に合わせて調整してください。
Ingressにnginx.ingress.kubernetes.io/wallarm-instanceアノテーションを付与している場合は、このアノテーション名をnginx.ingress.kubernetes.io/wallarm-applicationに変更してください。

変更されたのはアノテーション名のみで、ロジックは同じです。旧名のアノテーションはまもなく非推奨となるため、事前に名称を変更することを推奨します。
Ingressアノテーションで設定したページ&/usr/share/nginx/html/wallarm_blocked.htmlがブロック時のレスポンスとして返される場合、提供された変更に合わせて設定を調整してください。

新しいノードバージョンでは、Wallarmのブロッキングページは新しいブロッキングページに示すとおり、デフォルトでロゴとサポートメールが表示されない更新UIになりました。

手順11: Threat Replay Testingモジュールを再有効化します（ノード2.16以下のアップグレード時のみ）¶

Threat Replay Testingモジュールのセットアップに関する推奨事項を確認し、必要に応じて再有効化してください。

しばらくしてから、モジュールの動作が誤検知を引き起こしていないことを確認してください。誤検知が発生する場合は、Wallarmテクニカルサポートまでご連絡ください。