docs: kube-vip環境での実IP喪失原因と共有Ingress Controller移行手順を追記
Helm Chart Release / release-chart (push) Successful in 6s

mikoto-wordpress-nginxの調査で、type: ClusterIP + kube-vipアノテーション
による手動VIP付与構成では、kube-vip自体がTCP接続をプロキシするため
externalTrafficPolicyを設定しても実クライアントIPが失われることが判明。
共有Ingress Controller(Cilium組み込み等)へ移行する場合の具体的な
values設定とhelm upgradeコマンド例をREADMEに追加。
クラスタ構成の調査結果をCLAUDE.mdに記録。
This commit is contained in:
2026-08-09 16:20:40 +09:00
parent 40ca516249
commit 8241812d84
2 changed files with 48 additions and 0 deletions
+38
View File
@@ -191,6 +191,7 @@ helm upgrade --install my-wordpress . \
- **注意**: `Local` にすると、リクエストを受けたノードにPodが存在しない場合はそのノードでの接続が失敗します。MetalLB L2モードなど、Podが存在するノードにのみトラフィックが向く構成と組み合わせて使用してください(複数ノードにPodを分散させることを推奨)。
- `service.type: ClusterIP` の場合、`externalTrafficPolicy` は無視されます(Kubernetes仕様上ClusterIPには適用不可のため)。
- **kube-vipARP方式)でServiceに直接VIPを払い出している場合は要注意**: kube-vipはL2 ARP応答に加えて自前でTCP接続をプロキシする実装のため、`externalTrafficPolicy: Local` を設定してもkube-vipの時点で送信元IPが失われ、効果がありません(`type: ClusterIP` + kube-vipアノテーションによる手動VIP付与構成は特に該当します)。この場合は下記「kube-vip等でグローバルIP/VIPが限られている環境での実IP取得」の共有Ingress Controller構成を参照してください。
`nginx.forwardRealIP` は、Ingress ControllerやCDNCloudflareなど)、外部LBのように **X-Forwarded-For ヘッダーを付与するリバースプロキシを前段に置く場合にのみ**有効にしてください。本チャートのデフォルト構成(Service直下にPodがぶら下がる構成)ではX-Forwarded-Forを付与する層が存在しないため、`forwardRealIP` を有効にしても効果はなく、`service.externalTrafficPolicy: Local` のみで実IPが取得できます。
@@ -354,6 +355,43 @@ ingress:
EOF
```
### kube-vip等でグローバルIP/VIPが限られている環境での実IP取得(共有Ingress Controller構成)
kube-vip(ARP方式)でVIPを払い出す構成の場合、各Serviceを個別に `type: LoadBalancer`(またはClusterIP+kube-vipアノテーションの手動払い出し)にすると、kube-vipが自前でTCP接続をプロキシする関係上、Nginxに到達する時点で送信元IPが失われ、`nginx.forwardRealIP` を有効にしても実IPは取得できません(kube-vipはL2 ARP+自前プロキシであり、X-Forwarded-Forを付与するリバースプロキシではないため)。
これを避けつつ、限られたIP/VIPプールの消費も抑えたい場合は、**Ingress Controllerを1つだけLoadBalancer公開し、各WordPress/PHPFPMリリースはClusterIPのままIngress経由でぶら下げる**構成を推奨します。外部消費IPはIngress Controllerの1個のみに集約され、Ingress ControllerがX-Forwarded-Forを正しく付与するため、本チャート既存の `nginx.forwardRealIP` がそのまま機能します。
**Ingress Controllerの選択**: 既にCilium CNIを使用している場合(`cilium-envoy` Podが動作している環境)は、追加コンポーネントなしでCilium組み込みのIngress Controllerを有効化できます。
```bash
# Cilium組み込みIngress Controllerが有効か確認
kubectl get cm -n kube-system cilium-config -o yaml | grep -i ingress-controller-enabled
# 未設定の場合、Ciliumをupgradeして有効化(既存のCilium Helm valuesに追加)
helm upgrade cilium cilium/cilium -n kube-system --reuse-values \
--set ingressController.enabled=true \
--set ingressController.loadbalancerMode=shared \
--set ingressController.service.type=LoadBalancer \
--set ingressController.service.externalTrafficPolicy=Local
```
Cilium Ingressを使わない場合は `ingress-nginx` 等の一般的なIngress Controllerでも構いません。その場合もController自体のServiceに `externalTrafficPolicy: Local` を設定し、kube-vipでVIPを1つだけ払い出してください。
**各リリースの移行例**`mikoto-wordpress-nginx` の場合):
```bash
helm upgrade mikoto . -n website \
--set service.type=ClusterIP \
--set ingress.enabled=true \
--set ingress.className=cilium \
--set ingress.hostname=mikoto.example.com \
--set nginx.forwardRealIP.enabled=true
```
移行後は、これまで手動で付与していた `kube-vip.io/loadbalancerIPs` 等のServiceアノテーションは不要になります(Helm管理外のアノテーションのため、`kubectl annotate <svc> kube-vip.io/loadbalancerIPs- kube-vip.io/vipHost-` 等で削除してください)。DNS(またはルーターの名前解決)側で各ホスト名をIngress ControllerのVIP 1個に向ける設定も必要です。
`nginx.forwardRealIP.trustedProxies` のデフォルトには `10.0.0.0/8` が含まれているため、Cilium/Flannel等のPod CIDRがこの範囲内であれば追加設定は不要です。異なるPod CIDRを使用している場合は values.yaml で調整してください。
### リソース制限のカスタマイズ
```bash