wordpress/CLAUDE.md

CLAUDE.md — WordPress Helm Chart

共通ルール（要約） — 詳細は P:\Claude\CLAUDE.md（全体共通）と P:\Claude\HelmChart\CLAUDE.md（Helm チャート共通: リリースフロー・ワークフロー・クラスタ構成）を参照。 作業前に pull ／ 機能変更時は README 更新 ／ 作業単位ごとに commit → push まで ／ コミットに AI クレジットを付けない ／ pull で入った変更を revert しない ／ Helm・PHP はローカル実行不可（Python のみ可）。

リポジトリ概要

Raspberry Pi などのベアメタルで稼働することを想定した、Kubernetes 上で動作する Alpine Nginx + WordPress (PHP-FPM) の Helm チャート。

• Gitea リポジトリ: ssh://git@192.168.9.65/helmchart/wordpress
• Helm リポジトリ: https://git.cafepieters.com/api/packages/helmchart/helm

実行環境について

WordPress本体はイメージ内蔵のもの（docker.io/wordpress:<tag>-fpm-alpine）をemptyDirにコピーして使い捨てで起動し、wp-contentのみPVCで永続化する（bitnami方式）。PHPの実行環境はこのイメージに依存し、本リポジトリにPHPコードは含まれない。

設計上の注意（このチャート固有）

• templates/service.yaml には annotations のテンプレート化が存在しないため、kube-vip 用アノテーションは Helm 管理外で手動付与する運用になっている（クラスタ全体の事情は組織 CLAUDE.md「実運用クラスタ構成」を参照）。
• 実 IP 取得（ingress.yaml / nginx.forwardRealIP）は既存機能で対応済み。Cilium Ingress への移行手順は README に記載。

チャート改修履歴

外部Secret連携（extraEnvFrom / extraEnv / SMTP existingSecret）を追加（2026-09-08, v7.1.0-b）

背景: 別リポジトリの helmchart/secret-manager チャートが各ネームスペースへ配布する cred-<名前> Secret（メールの msmtprc / API キー）を WordPress 側から参照する口が無かった。 phpfpm チャートと同一方針で受け口を追加（ユーザー指定によりパターンを踏襲）。

修正内容:

• values.yaml に extraEnvFrom（envFrom 配列）と extraEnv（生の env エントリ配列）を追加。 稼働中の wordpress コンテナにのみ注入（wordpress-init initContainer には入れない）。
• smtp.auth.existingSecret / existingSecretKey: msmtprc はチャート生成のまま、パスワード ファイルだけ既存 Secret から取得。
• smtp.existingMsmtprcSecret / existingMsmtprcSecretKey: 完成済み msmtprc を持つ既存 Secret を そのまま /etc/smtp-config/msmtprc にマウント。指定時は configmap-smtp を生成せず host/port/auth.* は無視、smtp-secrets ボリュームも張らない。起動ログの echo も出し分け。
• templates/secret-smtp.yaml / templates/configmap-smtp.yaml を上記フラグで出し分け。
• 既定値は全て空 → 既存挙動は不変（helm template の全シナリオで確認済み）。
• 主アプリ（WordPress 7.1.0）は変わらないため手動リリース 7.1.0-b。

対象ファイル: values.yaml, templates/deployment.yaml, templates/configmap-smtp.yaml, templates/secret-smtp.yaml, Chart.yaml, README.md, CLAUDE.md

Hello Dolly等のデフォルトプラグインが削除しても復活する不具合の修正（2026-08-08, v7.1.0-a）

※自動更新ワークフローがこの作業と並行してWordPress 7.1.0への正式リリース（v7.1.0）を実行したため、本修正はそのタグの上に手動リリース 7.1.0-a として適用した。

症状: WP管理画面からHello Dolly（hello.php）を削除しても、Pod再起動のたびに復活する。

原因: templates/deployment.yaml の wordpress-init initContainerで、WordPressコアファイルをemptyDirにコピーする処理が cp -r /usr/src/wordpress/* /var/www/html/ という実装になっており、wp-content を除外していなかった。/var/www/html/wp-content はPVCマウントの別ボリュームだが、cp -r はワイルドカード展開で wp-content ディレクトリ自体も対象に含めてしまうため、イメージ同梱のデフォルトwp-content（hello.php、akismet/、デフォルトテーマ群）がPod再起動のたびにPVC上の既存wp-contentへ無条件に上書きマージされていた。直後にある「PVCが空の場合のみ初期化する」条件分岐（if [ ! -d /var/www/html/wp-content/themes ]）は、この最初の cp -r の副作用までは防げていなかった。

対象: Hello Dolly（hello.php）だけでなく、Akismet（wp-content/plugins/akismet/）も同じ理由で同様に復活する。本チャート自身が明示的にwp plugin install等でプラグインを追加している箇所は存在しない（該当するのはWordPressコア配布物に同梱されているこの2つのみ）。

修正内容: コアファイルのコピーを /usr/src/wordpress/ 直下を1件ずつ列挙し、wp-content をスキップするループに変更。これによりPVC上のwp-contentは、新規インストール時（PVCが空＝wp-content/themes が存在しない場合）以外は一切触れなくなった。

対象ファイル: templates/deployment.yaml, README.md, Chart.yaml

実IP取得の修正 + SMTP経由メール送信の追加（2026-08-08, v7.0.2-a）

背景: ルーター（グローバルIP）配下の 192.168.9.x セグメントにコントロールプレーン/ワーカーノードがあり、その上のPodでWordPressが稼働する構成において、(1) 訪問者の実IPアドレスが正しく取得できない、(2) wp_mail() によるメール送信が失敗する、という2つの不具合が報告された。

(1) 実IPアドレス取得の不具合

原因は2つ複合していた:

• Service（LoadBalancer/MetalLB想定）はデフォルトの externalTrafficPolicy: Cluster のため、kube-proxyが送信元IPをノード内部IPにSNATしてしまい、Nginxの $remote_addr が実IPではなくノードIPになっていた。
• 本チャートの nginx.forwardRealIP（X-Forwarded-Forを信頼するreal_ipモジュール設定）は、Ingress ControllerやCDNなどXFFヘッダーを付与するリバースプロキシが前段にある場合にのみ機能する設計だが、このベアメタル構成ではService直下にPodがぶら下がるだけでXFFを付与する層が存在せず、機能していなかった（trustedProxies に 192.168.0.0/16 が含まれるためSNAT後のノードIPを「信頼済みプロキシ」とみなしてしまうが、そのIPがXFFを付与するわけではないので $real_ip は結局SNAT後のIPのままになる）。

さらに、wp-config.php 生成テンプレート内でPHP側が生のX-Forwarded-Forヘッダーを無条件に信頼してREMOTE_ADDRを上書きする処理があり、Nginxのreal_ip信頼境界を迂回してクライアントがIPを詐称できる状態だった（副次的なセキュリティ上の問題）。

修正内容:

• values.yaml: service.externalTrafficPolicy: Local をデフォルト追加（SNATを回避し実IPをそのまま透過させる。MetalLB L2モード等と組み合わせる想定。ClusterIPでは無視される）。
• templates/service.yaml: externalTrafficPolicy を条件付きで出力するよう変更。
• templates/deployment.yaml: wp-config.php 内のPHP側REMOTE_ADDR再判定処理を削除（NginxのfastcgiパラメータでREMOTE_ADDRは既に正しく渡っているため不要かつ危険だった）。
• values.yaml/README.md: nginx.forwardRealIP は本当にXFFを付与するリバースプロキシが前段にある場合のみ有効化する旨を明記。

(2) メール送信の不具合

原因: 使用しているAlpineベースのWordPressイメージには、PHPの mail()（wp_mail() が内部的に利用）を実際に配送するMTA（sendmail相当）が同梱されておらず、sendmail_path の送信先が存在しなかった。

修正内容（helmchart/phpfpm チャートと同一の手法を採用。ユーザー指定によりphpfpmの実装パターンをそのまま踏襲）:

• values.yaml に smtp.* セクションを追加（enabled/host/protocol/port/auth.*/from/tls.*）。
• templates/configmap-smtp.yaml（新規）: /etc/msmtprc を生成するConfigMap。
• templates/secret-smtp.yaml（新規）: SMTPパスワードを格納するSecret。
• templates/deployment.yaml: smtp.enabled: true の場合のみ、wordpress コンテナの起動コマンドをシェルラッパーに変更し、apk add msmtp ca-certificates → /etc/msmtprc 配置（chmod 644、www-dataから読めるように） → PHPの sendmail_path を msmtp -t に向ける 99-smtp.ini を生成 → exec php-fpm という順で起動する。
  • apk add にrootが必要なため、SMTP有効時のみ既存の securityContext: runAsUser/runAsGroup: 82 を外している（PHP-FPMワーカー自体はイメージ標準の www.conf によりuid82で動作するため、実際のPHPコード実行権限は変わらない）。smtp.enabled: false（デフォルト）では従来どおり非rootで起動する。
  • msmtpのパスワードはmsmtprcに直書きせず passwordeval "cat /etc/smtp-secrets/password" で別ファイル参照（phpfpmの CHANGELOG-8.5.6-f/g.md で判明した「Secret/ConfigMapの権限が0600だとwww-dataから読めない」問題を踏まえ、最初から 0644 で実装済み）。
• WordPress本体は wp_mail() が自動的に mail()/sendmail_path を経由するため、phpfpmと異なりPHPコード側の変更（ヘルパークラスの読み込み等）は不要。

対象ファイル: values.yaml, templates/service.yaml, templates/deployment.yaml, templates/configmap-smtp.yaml（新規）, templates/secret-smtp.yaml（新規）, README.md, Chart.yaml