統合Wallarmモジュール付きのEOL NGINX Ingress Controllerのアップグレード¶

これらの手順は、展開済みのサポート終了となったWallarm Ingress Controller（バージョン3.6以下）をWallarm node 5.0搭載の新バージョンへアップグレードするための手順を説明します。

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

nodeをバージョン3.4以下からアップグレードする場合、Wallarm Ingress Controllerの基盤となるCommunity Ingress NGINX Controllerのバージョンが0.26.2から1.11.3にアップグレードされたことにご留意ください。

Community Ingress NGINX Controller 1.11.3の動作が大幅に変更されているため、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.5
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 below 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
34.96.64.17 34.110.183.149 35.235.66.155 34.102.90.100 34.94.156.115 35.235.115.105
34.160.38.183 34.144.227.90 34.90.110.226

ステップ 1: Wallarmテクニカルサポートへ、フィルタリングnodeモジュールのアップグレードを実施する旨を通知する（node 2.18以下の場合のみ）¶

node 2.18以下からアップグレードする場合、Wallarmテクニカルサポートへ、フィルタリングnodeモジュールを5.0まで更新していることを通知し、Wallarmアカウントに対して新しいIPリストロジックを有効にするよう依頼してください。

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

ステップ 2: Threat Replay Testingモジュールを無効化する（node 2.16以下の場合のみ）¶

Wallarm node 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 repositoryを追加してください。今後のWallarm Ingress Controllerの操作にはHelmリポジトリをご利用ください。

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

ステップ 5: `values.yaml`構成の更新¶

Wallarm Ingress Controller 5.0へ移行するため、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"
```
IngressClassesの構成。新しいIngress Controllerでは使用するKubernetes APIのバージョンがアップグレードされ、IngressClassesは.controller.ingressClass、.controller.ingressClassResource、および.controller.watchIngressWithoutClassパラメータを介して構成する必要があります。
```
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 node 3.xでIPリストのコアロジックが大幅に変更されたため、IPリスト構成を適切に調整する必要があります。
Deployロール用のAPIトークンを生成し、その値をcontroller.wallarm.tokenパラメータに渡してください。
以下に記載された設定の期待される動作が、offおよびmonitoringフィルトレーションモードの変更されたロジックに対応していることを確認してください:
期待される動作と変更後のフィルトレーションモードロジックが一致しない場合は、Ingress annotationsやその他の設定を変更後の内容に合わせて調整してください。
明示的に設定されたモニタリングサービス構成を削除してください。新しいWallarm Ingress Controllerバージョンでは、モニタリングサービスはデフォルトで有効化され、追加の構成は不要です。
```
controller:
wallarm:
  enabled: true
  tarantool:
    resources: {}
-  metrics:
-    enabled: true
-    service:
-      annotations: {}
```
ConfigMap経由で設定された&/usr/share/nginx/html/wallarm_blocked.htmlページがブロックされたリクエストに返される場合、構成を調整して変更内容に合わせてください。

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

ステップ 6: directivesからルールへの`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を使用して、展開済みIngress Controllerバージョンと新バージョンのK8sマニフェスト間の違いを確認してください。

プラグインのインストールおよび実行手順は以下の通りです:

プラグインのインストール:

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

プラグインの実行:
```
helm diff upgrade <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 5.3.0 -f <PATH_TO_VALUES>
```
- <RELEASE_NAME>: Ingress ControllerチャートのHelmリリース名
- <NAMESPACE>: Ingress Controllerが展開されているnamespace
- <PATH_TO_VALUES>: Ingress Controller 5.0設定を定義しているvalues.yamlファイルへのパス
変更が実行中のサービスの安定性に影響を与えないことを確認し、stdoutからのエラー内容を十分に検証してください。

stdoutが空の場合、values.yamlファイルが有効であることを確認してください。

以下の構成変更にご留意ください:

DeploymentやStatefulSetのselectorなどのイミュータブルフィールド

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のアップグレード¶

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

一時的なIngress Controllerの展開
通常のIngress Controllerリリースの再作成
ロードバランサに影響を与えないIngress Controllerリリースの再作成

staging environmentまたはminikubeを使用している場合

Wallarm Ingress Controllerがstaging environmentに展開されている場合、まずこちらでアップグレードを実施することを推奨します。すべてのサービスが正常に動作していることを確認後、本番環境でアップグレード手順を進めてください。

minikube等の他のサービスを用いて、更新された構成でWallarm Ingress Controller 5.0をデプロイすることも推奨されます。すべてのサービスが期待通りに動作していることを確認した後、本番環境でIngress Controllerのアップグレードを実施してください。

この手法は本番環境でのサービスのダウンタイムを回避するのに役立ちます。

方法 1: 一時的なIngress Controllerの展開¶

この方法を使用すると、環境内にIngress Controller 5.0を追加のエンティティとして展開し、徐々にトラフィックを切り替えていくことが可能です。これにより、一時的なサービス停止を回避し、安全な移行が実現できます。

以前のバージョンのvalues.yamlファイルからIngressClassの構成を、Ingress Controller 5.0用のvalues.yamlファイルへコピーしてください。

この構成により、Ingress ControllerはIngressオブジェクトを認識しますが、そのトラフィックを処理しません。
Ingress Controller 5.0を展開します:
```
helm install <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 5.3.0 -f <PATH_TO_VALUES>
```
- <RELEASE_NAME>: Ingress ControllerチャートのHelmリリース名
- <NAMESPACE>: Ingress Controllerを展開するnamespace
- <PATH_TO_VALUES>: Ingress Controller 5.0設定を定義しているvalues.yamlファイルへのパス
すべてのサービスが正常に動作していることを確認してください。
新しいIngress Controllerへ徐々にトラフィックを切り替えてください。

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

ロードバランサとIngress Controllerが同一Helmチャートで記述されていない場合は、単にHelmリリースを再作成できます。この処理には数分かかり、その間Ingress Controllerは利用できなくなります。

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

もしHelmチャートでIngress Controllerと合わせてロードバランサの構成が設定されている場合、リリースの再作成は長時間にわたるロードバランサのダウンタイムを引き起こす可能性があります（クラウドプロバイダーによります）。一定のIPアドレスが割り当てられていない場合、アップグレード後にロードバランサのIPアドレスが変更される可能性があります。

この手法を使用する場合は、あらゆるリスクを十分に検証してください。

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

Helm CLITerraform CLI

以前のリリースを削除します:
```
helm delete <RELEASE_NAME> -n <NAMESPACE>
```
- <RELEASE_NAME>: Ingress ControllerチャートのHelmリリース名
- <NAMESPACE>: Ingress Controllerが展開されているnamespace
コマンド実行時に--waitオプションは使用しないでください。アップグレード時間が延びる可能性があります。
Ingress Controller 5.0で新たにリリースを作成します:
```
helm install <RELEASE_NAME> -n <NAMESPACE> wallarm/wallarm-ingress --version 5.3.0 -f <PATH_TO_VALUES>
```
- <RELEASE_NAME>: Ingress ControllerチャートのHelmリリース名
- <NAMESPACE>: Ingress Controllerを展開するnamespace
- <PATH_TO_VALUES>: Ingress Controller 5.0設定を定義しているvalues.yamlファイルへのパス

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

+ wait = false

  ...
}
```
以前のリリースを削除します:
```
terraform taint helm_release.release
```
Ingress Controller 5.0で新たにリリースを作成します:
```
terraform apply -target=helm_release.release
```

方法 3: ロードバランサに影響を与えない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 5.3.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 5.0設定を定義しているvalues.yamlファイルへのパス

ステップ 9: アップグレードしたIngress Controllerのテスト¶

Helmチャートのバージョンが更新されているか確認してください:
```
helm ls
```
チャートバージョンはwallarm-ingress-5.3.0である必要があります。

<INGRESS_CONTROLLER_NAME>にWallarm Ingress Controllerの名前を指定して、Podリストを取得してください:

kubectl get pods -l release=<INGRESS_CONTROLLER_NAME>

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

NAME                                                              READY     STATUS    RESTARTS   AGE
ingress-controller-nginx-ingress-controller-675c68d46d-cfck8      3/3       Running   0          5m
ingress-controller-nginx-ingress-controller-wallarm-tarantljj8g   4/4       Running   0          5m

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

ステップ 10: リリースされた変更内容に応じてIngress annotationsを調整する¶

以下のIngress annotationsをIngress Controller 5.0でリリースされた変更に合わせて調整してください:

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

アノテーションの名前のみが変更され、ロジックは同じです。旧名称のアノテーションはまもなく廃止されるため、早めに名称を変更することを推奨します。
Ingress annotationsで設定された&/usr/share/nginx/html/wallarm_blocked.htmlページがブロックされたリクエストに返される場合、構成を調整してリリース内容に合わせてください。

新しいnodeバージョンでは、Wallarmブロッキングページはロゴがなく、デフォルトで指定されたサポートメールもない更新されたUIになっています。

ステップ 11: Threat Replay Testingモジュールを再有効化する（node 2.16以下の場合のみ）¶

Threat Replay Testingモジュールの設定についての推奨事項を確認し、必要に応じて再度有効化してください。

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