コンテンツにスキップ

NGINXベースのWallarm Ingressコントローラーの詳細チューニング

セルフホスト型のWallarm Ingressコントローラーで利用可能な詳細チューニング方法をご紹介します。これにより、Wallarmソリューションを最大限に活用できます。

NGINX Ingress Controllerの公式ドキュメント

Wallarm Ingressコントローラーの詳細チューニングは、公式ドキュメントで説明されているNGINX Ingress Controllerのものと非常に類似しています。Wallarmを使用する場合でも、元のNGINX Ingress Controllerの設定オプションはすべて利用できます。

Additional Settings for Helm Chart

設定はvalues.yamlファイルで定義します。デフォルトでは、以下のとおりです。

controller:
  wallarm:
    enabled: false
    apiHost: api.wallarm.com
    apiPort: 443
    apiSSL: true
    token: ""
    nodeGroup: defaultIngressGroup
    existingSecret:
      enabled: false
      secretKey: token
      secretName: wallarm-api-token
    postanalytics:
      kind: Deployment
      service:
        annotations: {}
      arena: "2.0"
      serviceAddress: "[::]:3313"
      livenessProbe:
        failureThreshold: 3
        initialDelaySeconds: 10
        periodSeconds: 10
        successThreshold: 1
        timeoutSeconds: 1
      tls:
        enabled: false
      #  certFile: "/root/test-tls-certs/server.crt"
      #  keyFile: "/root/test-tls-certs/server.key"
      #  caCertFile: "/root/test-tls-certs/ca.crt"
      #  mutualTLS:
      #    enabled: false
      #    clientCACertFile: "/root/test-tls-certs/ca.crt"
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    wallarm-appstructure:
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    wallarm-antibot:
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    metrics:
      port: 18080
      enabled: false

      service:
        annotations:
          prometheus.io/scrape: "true"
          prometheus.io/path: /wallarm-metrics
          prometheus.io/port: "18080"

        ## stats-exporterサービスを利用可能にするIPアドレスの一覧
        ## 参考: https://kubernetes.io/docs/user-guide/services/#external-ips
        ##
        externalIPs: []

        loadBalancerIP: ""
        loadBalancerSourceRanges: []
        servicePort: 18080
        type: ClusterIP
    init:
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    wcliController:
      logLevel: warn
      commands:
        apispec:
          logLevel: INFO
        blkexp:
          logLevel: INFO
        botexp:
          logLevel: WARN
        cntexp:
          logLevel: ERROR
        cntsync:
          logLevel: INFO
        credstuff:
          logLevel: INFO
        envexp:
          logLevel: INFO
        ipfeed:
          logLevel: INFO
        iplist:
          logLevel: INFO
        jwtexp:
          logLevel: INFO
        metricsexp:
          logLevel: INFO
        mrksync:
          logLevel: INFO
        register:
          logLevel: INFO
        reqexp:
          logLevel: INFO
        syncnode:
          logLevel: INFO
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    wcliPostanalytics:
      logLevel: warn
      commands:
        apispec:
          logLevel: INFO
        blkexp:
          logLevel: INFO
        botexp:
          logLevel: WARN
        cntexp:
          logLevel: ERROR
        cntsync:
          logLevel: INFO
        credstuff:
          logLevel: INFO
        envexp:
          logLevel: INFO
        ipfeed:
          logLevel: INFO
        iplist:
          logLevel: INFO
        jwtexp:
          logLevel: INFO
        metricsexp:
          logLevel: INFO
        mrksync:
          logLevel: INFO
        register:
          logLevel: INFO
        reqexp:
          logLevel: INFO
        syncnode:
          logLevel: INFO
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    apiFirewall:
      enabled: true
      config:
        ...
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
validation:
  enableCel: false
  forbidDangerousAnnotations: false

この設定を変更する場合、Ingressコントローラーのインストール時はhelm installの--setオプション、既存のIngressコントローラーのパラメータを更新する場合はhelm upgradeの--setオプションの使用を推奨します。例:

helm install --set controller.wallarm.enabled=true <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

helm upgrade --reuse-values --set controller.wallarm.enabled=true <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

以下に主なパラメータの説明を示します。その他のパラメータはデフォルト値が設定されており、変更の必要はほとんどありません。

controller.wallarm.enabled

Wallarmの機能を有効化または無効化できます。

デフォルト値: false

controller.wallarm.apiHost

Wallarm APIエンドポイントです。次のいずれかを指定します。

デフォルト値: api.wallarm.com

controller.wallarm.token

フィルタリングノードのトークン値です。Wallarm APIへのアクセスに必要です。

トークンは次の種類のいずれかです。

  • API token（推奨） - UIの編成のためにノードグループを動的に追加/削除したい場合や、セキュリティ向上のためにトークンのライフサイクルを管理したい場合に最適です。API tokenを作成するには:

    API tokenを作成するには:

    1. Wallarm Console → Settings → API tokens（US CloudまたはEU Cloud）に移動します。
    2. 使用タイプにNode deployment/Deploymentを選択してAPI tokenを作成します。
    3. ノードのデプロイ時に作成したトークンを使用し、controller.wallarm.nodeGroupパラメータでグループ名を指定します。異なるAPI tokenを使用して複数のノードを同一グループに追加できます。

  • Node token - 使用するノードグループがすでに決まっている場合に適しています。

    Node tokenを作成するには:

    1. Wallarm Console → Nodes（US CloudまたはEU Cloud）に移動します。
    2. ノードを作成し、ノードグループ名を設定します。
    3. そのグループに含めたい各ノードのデプロイ時に、グループのトークンを使用します。

controller.wallarm.existingSecret.enabled: trueの場合、このパラメータは無視されます。

デフォルト値: not specified

controller.wallarm.nodeGroup

Helmチャートバージョン4.6.8以降、新規デプロイするノードを追加するフィルタリングノードグループの名前を指定します。この方法でのノードのグループ化は、使用タイプにNode deployment/Deploymentを持つAPI token（その値をcontroller.wallarm.tokenに渡します）でノードを作成してWallarm Cloudに接続する場合にのみ利用できます。

デフォルト値: defaultIngressGroup

controller.wallarm.existingSecret

Helmチャートバージョン4.4.1以降、Kubernetes SecretからWallarmノードトークン値を取得するためにこの設定ブロックを使用できます。外部のシークレット管理（例: external secrets operatorを使用）を行う環境で有用です。

ノードトークンをK8s Secretに保存し、Helmチャートへ渡すには:

  1. Wallarmノードトークンを格納するKubernetes Secretを作成します:

    kubectl -n <KUBERNETES_NAMESPACE> create secret generic wallarm-api-token --from-literal=token=<WALLARM_NODE_TOKEN>
    • <KUBERNETES_NAMESPACE>は、Wallarm IngressコントローラーのHelmリリース用に作成したKubernetesのNamespaceです
    • wallarm-api-tokenはKubernetes Secret名です
    • <WALLARM_NODE_TOKEN>はWallarm ConsoleのUIからコピーしたWallarmノードトークン値です

    外部のSecretオペレーターを使用する場合は、該当ドキュメントに従ってSecretを作成してください。

  2. values.yamlに以下の設定を行います:

    controller:
  wallarm:
    token: ""
    existingSecret:
      enabled: true
      secretKey: token
      secretName: wallarm-api-token

デフォルト値: existingSecret.enabled: false（Helmチャートはcontroller.wallarm.tokenからWallarmノードトークンを取得します）

controller.wallarm.postanalytics.arena

postanalyticsサービスに割り当てるメモリ量を指定します。直近5〜15分のリクエストデータを保持できる十分な値を設定することを推奨します。

デフォルト値: 2.0

NGINX Node 5.x以前では、このパラメータ名はcontroller.wallarm.tarantool.arenaでした。アップグレード時には名称変更が必要です。

controller.wallarm.postanalytics.serviceAddress

wstoreが受信接続を受け付けるアドレスとポートを指定します。

リリース6.3.0以降でサポートされています。

デフォルト値: [::]:3313（IPv4およびIPv6のすべてのインターフェースでポート3313をリッスン）。これは6.3.0以前のバージョンにおけるデフォルト動作でもあります。

controller.wallarm.postanalytics.tls

postanalyticsモジュールへの安全な接続を可能にするTLSおよび相互TLS（mTLS）の設定を行います（任意）:

controller:
  wallarm:
    postanalytics:
      tls:
        enabled: false
      #  certFile: "/root/test-tls-certs/server.crt"
      #  keyFile: "/root/test-tls-certs/server.key"
      #  caCertFile: "/root/test-tls-certs/ca.crt"
      #  mutualTLS:
      #    enabled: false
      #    clientCACertFile: "/root/test-tls-certs/ca.crt"

リリース6.2.0以降でサポートされています。

パラメータ 説明 必須か
enabled postanalyticsモジュールへの接続に対するSSL/TLSを有効化/無効化します。デフォルトはfalse（無効）です。 はい
certFile Filtering NodeがpostanalyticsモジュールへのSSL/TLS接続を確立する際に自身を認証するために使用するクライアント証明書のパスを指定します。 mutualTLS.enabledがtrueの場合は必須
keyFile certFileで指定したクライアント証明書に対応する秘密鍵のパスを指定します。 mutualTLS.enabledがtrueの場合は必須
caCertFile postanalyticsモジュールが提示するTLS証明書を検証するために使用する信頼された認証局（CA）証明書のパスを指定します。 カスタムCAを使用する場合は必須
mutualTLS.enabled Filtering Nodeとpostanalyticsモジュールの双方が証明書で相互にアイデンティティを検証する相互TLS（mTLS）を有効にします。デフォルトはfalse（無効）です。 いいえ
mutualTLS.clientCACertFile Filtering Nodeが提示するTLS証明書を検証するために使用する信頼された認証局（CA）証明書のパスを指定します。 カスタムCAを使用する場合は必須

controller.wallarm.metrics.enabled

情報およびメトリクス収集を切り替えます。KubernetesクラスターにPrometheusがインストールされている場合、追加の設定は不要です。

デフォルト値: false

controller.wallarm.apifirewall

リリース4.10以降で利用可能なAPI Specification Enforcementの設定を制御します。デフォルトでは有効で、以下のとおり設定されています。この機能を使用している場合、これらの値は変更しないことを推奨します。

controller:
  wallarm:
    apiFirewall:
      ### API Firewall機能の有効化/無効化（true|false）
      ###
      enabled: true
      readBufferSize: 8192
      writeBufferSize: 8192
      maxRequestBodySize: 4194304
      disableKeepalive: false
      maxConnectionsPerIp: 0
      maxRequestsPerConnection: 0
      config:
        mainPort: 18081
        healthPort: 18082
        specificationUpdatePeriod: 1m
        unknownParametersDetection: true
        #### TRACE|DEBUG|INFO|WARNING|ERROR
        logLevel: DEBUG
        ### TEXT|JSON
        logFormat: TEXT
      ...

Node 5.1.0以降では、次の設定項目が提供されています（デフォルト値は上記例を参照）。

設定 説明
readBufferSize リクエスト読み取り用の接続ごとのバッファサイズです。これは最大ヘッダーサイズの上限にもなります。クライアントが数KBのRequestURIや数KBのヘッダー（例: 大きなCookie）を送信する場合は、このバッファを増やしてください。
writeBufferSize レスポンス書き込み用の接続ごとのバッファサイズです。
maxRequestBodySize リクエストボディの最大サイズです。サーバーはこの上限を超えるボディを持つリクエストを拒否します。
disableKeepalive keep-alive接続を無効にします。このオプションがtrueの場合、サーバーはクライアントに最初のレスポンスを送信した後にすべての受信接続を閉じます。
maxConnectionsPerIp IPアドレスごとに許可される同時クライアント接続の最大数です。0は無制限です。
maxRequestsPerConnection 接続1本あたりで処理するリクエストの最大数です。サーバーは最後のリクエスト処理後に接続を閉じ、最後のレスポンスにConnection: closeヘッダーを追加します。0は無制限です。

controller.wallarm.container_name.extraEnvs

ソリューションで使用するDockerコンテナに渡す追加の環境変数です。リリース4.10.6以降でサポートされています。

以下は、https_proxyとno_proxy環境変数をDockerコンテナに渡す例です。この構成により、送信HTTPSトラフィックは指定したプロキシを経由し、ローカルトラフィックはプロキシをバイパスします。Wallarm APIとの通信など外部通信をセキュリティ上の理由でプロキシ経由にする必要がある環境で重要です。

controller:
  wallarm:
    apiHost: api.wallarm.com
    enabled: "true"
    token:  <API_TOKEN>
    init:
      extraEnvs:
        - name: https_proxy
          value: https://1.1.1.1:3128

validation.enableCel

Validating Admission Policiesを使用してIngressリソースを検証できるようにします。

この機能には以下が必要です。

  • Kubernetes v1.30以上

  • Wallarm Helmチャート 5.3.14+（5.x系）または6.0.2+

trueに設定すると、Helmチャートは次をデプロイします。

  • すべてのIngressリソース（networking.k8s.io/v1）に対するCELルールを定義するValidatingAdmissionPolicy ingress-safety-net

  • それらのルールをcluster-wideにDenyアクションで実行するValidatingAdmissionPolicyBinding ingress-safety-net-binding

デフォルトルールは、通常nginx -tで検出される一般的な誤設定を検出します。

  • ワイルドカードホストの禁止（例: *.example.com）

  • Ingress内のすべてのhost値が一意であることの確認

  • 各HTTPパスにサービス名とポートが含まれていることの検証

  • すべてのパスが/で始まることの要求

  • 一般的なサイズ/時間/真偽値アノテーション（proxy-buffer-size、proxy-read-timeout、ssl-redirect）のフォーマット検証

検証はIngressの作成または更新時に行われ、不適切に設定されたリソースは拒否されます。

この仕組みは、CVE-2025-1974により現在上流のNGINX Ingress Controllerで無効化されているテンプレートテストを置き換えるものです。

デフォルト値: false

検証ルールのカスタマイズ

Common Expression Language（CEL）を使用して、デフォルトのルールセットを拡張または変更できます。

  1. 必要なバージョンのWallarm Helmチャートをダウンロードします。

  2. templates/ingress-safety-vap.yamlファイル内のルールを修正します。

  3. 標準のデプロイ手順に従い、修正したディレクトリからチャートをデプロイします。

validation.forbidDangerousAnnotations

明示的に危険なNGINX Ingressのアノテーションserver-snippetおよびconfiguration-snippetをブロックする追加のCELルールを有効にします。

すべてのsnippet系アノテーションを許可すると攻撃面が広がります。Ingressの作成や更新権限を持つ任意のユーザーが、安全でない、または不安定な動作を導入できてしまうためです。

この機能には以下が必要です。

  • Kubernetes v1.30以上

  • Wallarm Helmチャート 6.3.0+

  • validation.enableCelがtrueに設定されていること

Node 6.2.0以前の挙動

Node 6.2.0以前では、validation.enableCelがtrueの場合、明示的に危険なserver-snippetおよびconfiguration-snippetはデフォルトでブロックされます。

デフォルト値: false（server-snippetとconfiguration-snippetの明示的に危険なアノテーションのブロックは無効）

グローバルコントローラー設定

ConfigMapで実装します。

標準のものに加えて、以下の追加パラメータをサポートします。

Ingressアノテーション

これらのアノテーションは、個々のIngressインスタンスの処理パラメータを設定するために使用します。

標準のアノテーションに加えて、以下の追加アノテーションをサポートします。

Ingressリソースへのアノテーション適用

Ingressに設定を適用するには、次のコマンドを使用します。

kubectl annotate --overwrite ingress <YOUR_INGRESS_NAME> -n <YOUR_INGRESS_NAMESPACE> <ANNOTATION_NAME>=<VALUE>

  • <YOUR_INGRESS_NAME>は対象のIngress名です

  • <YOUR_INGRESS_NAMESPACE>は対象のIngressのNamespaceです

  • <ANNOTATION_NAME>は上記一覧のアノテーション名です

  • <VALUE>は上記一覧のアノテーション値です

アノテーション例

ブロックページとエラーコードの設定

nginx.ingress.kubernetes.io/wallarm-block-pageアノテーションは、次の理由でブロックされたリクエストへのレスポンスとして返すブロックページとエラーコードを設定するために使用します。

例えば、ブロックされた任意のリクエストに対してデフォルトのWallarmブロックページとエラーコード445を返すには次のとおりです。

kubectl annotate ingress <YOUR_INGRESS_NAME> -n <YOUR_INGRESS_NAMESPACE> nginx.ingress.kubernetes.io/wallarm-block-page="&/usr/share/nginx/html/wallarm_blocked.html response_code=445 type=attack,acl_ip,acl_source"

ブロックページとエラーコードの設定方法の詳細 →

libdetectionモードの管理

libdetectionのデフォルトモード

libdetectionライブラリのデフォルトモードはon（有効）です。

libdetectionのモードは次のいずれかの方法で制御できます。

  • 次のnginx.ingress.kubernetes.io/server-snippetアノテーションをIngressリソースに適用します:

    kubectl annotate --overwrite ingress <YOUR_INGRESS_NAME> -n <YOUR_INGRESS_NAMESPACE> nginx.ingress.kubernetes.io/server-snippet="wallarm_enable_libdetection off;"

    wallarm_enable_libdetectionの有効な値はon/offです。

  • controller.config.server-snippetパラメータをHelmチャートに渡します:

    helm install --set controller.config.server-snippet='wallarm_enable_libdetection off;' <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

    正しくIngressコントローラーをインストールするには他にもパラメータが必要です。これらも--setオプションで指定してください。

    helm upgrade --reuse-values --set controller.config.server-snippet='wallarm_enable_libdetection off;' <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

    wallarm_enable_libdetectionの有効な値はon/offです。