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
オプションの使用を推奨します。例:
以下に主なパラメータの説明を示します。その他のパラメータはデフォルト値が設定されており、変更の必要はほとんどありません。
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を作成するには:
-
Node token - 使用するノードグループがすでに決まっている場合に適しています。
Node tokenを作成するには:
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チャートへ渡すには:
-
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を作成してください。
-
values.yaml
に以下の設定を行います:
デフォルト値: 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)を使用して、デフォルトのルールセットを拡張または変更できます。
-
必要なバージョンのWallarm Helmチャートをダウンロードします。
-
templates/ingress-safety-vap.yaml
ファイル内のルールを修正します。 -
標準のデプロイ手順に従い、修正したディレクトリからチャートをデプロイします。
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インスタンスの処理パラメータを設定するために使用します。
標準のアノテーションに加えて、以下の追加アノテーションをサポートします。
-
nginx.ingress.kubernetes.io/wallarm-mode、デフォルト:
"off"
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
アノテーションは、次の理由でブロックされたリクエストへのレスポンスとして返すブロックページとエラーコードを設定するために使用します。
-
リクエストに次の種類の悪意あるペイロードが含まれている: 入力検証攻撃、vpatch攻撃、正規表現に基づいて検出された攻撃
-
上記の悪意あるペイロードを含むリクエストがgraylisted IPアドレスからのもので、かつノードがsafe blocking modeでリクエストをフィルタリングしている
-
リクエストがdenylisted IPアドレスからのものである
例えば、ブロックされた任意のリクエストに対してデフォルトの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
オプションで指定してください。wallarm_enable_libdetection
の有効な値はon
/off
です。