helmchart/phpfpm
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity
Files
c7397b3c9de596da580bc6541858103907f77c06
phpfpm/CLAUDE.md
T
claude c7397b3c9d
Helm Chart Release / release-chart (push) Successful in 6s
Details
feat: ingress.tls[].secretNameをhostから自動導出できるように変更 
ingress.hosts[].hostは既にYAMLアンカー(&appDomain)でingress.tls[].hosts
と値を共有できていたが、secretNameは独立した文字列指定が必須で、
ドメイン変更時に別途書き換えが必要だった。

secretNameを省略可能にし、未指定時はそのエントリの最初のhostから
自動生成する(.を-に置換して-tlsを付与。例: example.tld → example-tld-tls)。
明示的に指定した場合はそちらが優先されるため既存挙動は変わらない。

手動リリース 8.5.10-d。
2026-09-27 15:28:15 +09:00

162 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md — phpfpm Helm Chart
> **共通ルール（要約）** — 詳細は `P:\Claude\CLAUDE.md`（全体共通）と `P:\Claude\HelmChart\CLAUDE.md`（Helm チャート共通: リリースフロー・ワークフロー・Gitea Secrets・クラスタ構成）を参照。
> 作業前に pull ／ 機能変更時は README 更新 ／ 作業単位ごとに commit → push まで ／ コミットに AI クレジットを付けない ／ pull で入った変更を revert しない ／ Helm・PHP はローカル実行不可（Python のみ可）。
## リポジトリ概要
Raspberry Pi などのベアメタルで稼働することを想定した、Kubernetes 上で動作する Nginx + PHP-FPM の Helm チャート。
Websites 組織の各サイト（e-learn.jp / fcdomain.com / hotels / tskholding.com など）はこのチャートでデプロイされる。
- **Gitea リポジトリ**: `ssh://git@192.168.9.65/helmchart/phpfpm`
- **Helm リポジトリ**: `https://git.cafepieters.com/api/packages/helmchart/helm`
- **主アプリ**: PHP（`docker.io/php:<tag>-fpm-alpine`）。サブアプリ: nginx
## 実行環境について
**PHP の実行環境（インタープリタ）はこのリポジトリには含まれていない。**
チャートは `docker.io/php:<tag>-fpm-alpine` の公式イメージを Kubernetes 上で起動するものであり、PHP コードそのものは PVC（`/var/www/html`）に別途配置する必要がある。
## 設計上の注意（既知の落とし穴）
- `templates/configmap.yaml` が実際に使われている nginx 設定。`templates/configmap-nginx.yaml` は `.Values.nginx.enabled` が values.yaml に存在せず常に未出力の**死んだファイル**なので注意。
- PVC はルートを `/var/www` にマウントする（`html/` が公開フォルダ、それ以外は非公開）。`/composer` は Pod 再起動ごとにクリーン再構築される使い捨て領域。
- `uploadMaxSize` 1箇所で nginx `client_max_body_size`・PHP `upload_max_filesize`/`post_max_size`・Ingress `proxy-body-size` の3箇所が連動する。
- Secret / ConfigMap をファイルとして PHP-FPM ワーカー（`www-data`）から読ませる場合、権限は `0644` にする（`0600` だと読めない）。
- Selenium（`selenium.enabled: true`）は v8.5.10-b 以降、nginx/php-fpm と別の Deployment/Service（`<release>-phpfpm-selenium`）。同一 Pod のサイドカーには**しない**（Selenium 単体の不調でメインの Pod が Service の Endpoints から外れ、静的ページ配信まで巻き込んで全断する設計だったため分離した）。
## チャート改修履歴
### ingress.tls[].secretNameをhostから自動導出可能に（2026-09-27, v8.5.10-d）
- **背景**: `ingress.hosts[].host` は既にYAMLアンカー（`&appDomain`）で `ingress.tls[].hosts` と値を共有できるようになっていたが、`ingress.tls[].secretName` は独立した文字列指定が必須で、ドメイン変更時に別途書き換えが必要だった。
- **修正内容**: `templates/ingress.yaml` で `secretName` を省略可能にし、未指定時はそのエントリの最初のhostから自動生成する（`.`を`-`に置換して`-tls`を付与。例: `example.tld` → `example-tld-tls`）。明示的に指定した場合はそちらが優先される（後方互換）。デフォルトの`values.yaml`も自動導出を使う例に更新。
- **対象ファイル**: `templates/ingress.yaml`, `values.yaml`, `README.md`, `Chart.yaml`
### v8.5.10-bのDeployment.spec.selector変更が既存リリースのアップグレードを壊す不具合を修正（2026-09-26, v8.5.10-c）
v8.5.10-bでnginx/php-fpm Deploymentのspec.selector.matchLabelsに`app.kubernetes.io/component: web`を追加したが、Deployment.spec.selectorは作成後immutableのため既存リリースの`helm upgrade`が「field is immutable」で失敗する不具合を確認・修正した。既存Deploymentのselectorは元の内容（name+instanceのみ）に戻し、Selenium側はcomponentラベルではなく`app.kubernetes.io/name`自体を`<chart名>-selenium`という別名にする方式（新ヘルパー`phpfpm.selenium.name`/`phpfpm.selenium.selectorLabels`）に変更した。componentラベルだけを足す設計だと、SeleniumのPodもnginx/php-fpm側Deploymentのselector（name+instance）に一致してしまい2つのDeployment(ReplicaSet)が同じPod集合を取り合う選択重複を起こすため、name自体をvariantにして構造的に防止する。v8.5.10-bは未適用ならスキップしてv8.5.10-c以降を直接使うこと。
**対象ファイル**: `templates/_helpers.tpl`, `templates/deployment.yaml`, `templates/deployment-selenium.yaml`, `templates/service-selenium.yaml`, `Chart.yaml`, `CHANGELOG-8.5.10-c.md`
### Selenium を独立Deployment/Serviceに分離 + resources死んだ設定を修正（2026-09-26, v8.5.10-b）
`selenium.enabled: true` 構成で断続的な php-fpm CrashLoopBackOff とサイト完全停止が続いた件の調査で、2つの設計上の欠陥を確認した。(1) `resources` values キーがテンプレート側で全く参照されておらず、nginx/php-fpm/selenium いずれのコンテナにも requests/limits が反映されない死んだ設定だった（全コンテナが QoS Class: BestEffort → ノードのメモリ逼迫時に OOM Kill の対象になりやすい）。(2) nginx・php-fpm・Selenium が同一 Pod のコンテナで、Kubernetes の Pod Ready 判定は全コンテナの AND のため、Selenium だけが不調（起動失敗・OOM 等）でも Pod 全体が Service の Endpoints から外れ、Selenium を使わない静的ページ配信まで巻き込まれてサービス全体が停止していた。対応: Selenium を独立した Deployment(`<release>-phpfpm-selenium`)/Service に分離（`app.kubernetes.io/component: web`/`selenium` ラベルでセレクタを分離、php-fpm の `SELENIUM_URL` は新Serviceを指すよう自動注入）。`resources` を `resources.nginx`/`resources.phpfpm`/`selenium.resources` に構造化し実際にコンテナへ反映されるよう修正。既存 `selenium.enabled: true` 利用者は `selenium.mountHtml`（PVC html サブパスへの依存があれば true + `persistence.accessMode: ReadWriteMany`）を確認する必要がある。OOM Kill が実際のクラッシュトリガーだったかは本リリース時点では未確認（要検証）だが、上記2点はコード上確認済みの確定した欠陥のため先行修正した。
**対象ファイル**: `templates/deployment.yaml`, `templates/deployment-selenium.yaml`(新規), `templates/service.yaml`, `templates/service-selenium.yaml`(新規), `values.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.10-b.md`
### 外部Secret連携（extraEnvFrom / extraEnv / SMTP existingSecret）を追加（2026-09-08, v8.5.10-a）
**背景**: 別リポジトリの `helmchart/secret-manager` チャートが各ネームスペースへ配布する
`cred-<名前>` Secret（メールの msmtprc / API キー）を、phpfpm 側から参照する口が無かった
（`phpEnv` は直書きのみ、SMTP パスワードは `smtp.auth.password` 直書き＋自作 Secret のみ）。
**修正内容**:
- `values.yaml` に `extraEnvFrom`（`envFrom` 配列）と `extraEnv`（生の env エントリ配列）を追加。
php-fpm コンテナに既存 Secret/ConfigMap をまるごと env 注入できる。
- `smtp.auth.existingSecret` / `existingSecretKey` を追加。チャートで msmtprc を生成しつつ
パスワードファイルだけ既存 Secret から取る。
- `smtp.existingMsmtprcSecret` / `existingMsmtprcSecretKey` を追加。完成済み msmtprc を持つ
既存 Secret をそのまま `/etc/smtp-config/msmtprc` としてマウント（secret-manager が生成する
`msmtprc` キーを想定）。指定時は `configmap-smtp` を生成せず host/port/auth.* は無視、
`smtp-secrets` ボリュームも張らない（msmtprc にパスワードが内包されるため）。
- `templates/secret-smtp.yaml` / `templates/configmap-smtp.yaml` を上記フラグで出し分け。
- 既定値は全て空 → 既存挙動は不変（`helm template` の全シナリオで確認済み）。
- 主アプリ（PHP 8.5.10）は変わらないため手動リリース `8.5.10-a`。
**対象ファイル**: `values.yaml`, `templates/deployment.yaml`, `templates/configmap-smtp.yaml`,
`templates/secret-smtp.yaml`, `Chart.yaml`, `README.md`, `CLAUDE.md`
### php-fpm を `exec php-fpm -F` で起動しCrashLoopBackOffを修正（2026-09-06, v8.5.9-d）
setup シェル末尾の `php-fpm`（シェルの子プロセス）を **`exec php-fpm -F`** に変更。selenium 有効構成（hotels）で php-fpm が `unable to bind ... '9000': Address in use` を出して永続 CrashLoopBackOff になり、nginx が非FastCGI応答を受けて全リクエスト502（`unsupported FastCGI protocol version: 60`）になる障害の修正。原因は php-fpm が setup シェルの子で、コンテナ PID1 のシェルが `SIGTERM` を子へ転送しないため、コンテナ再起動時に旧 php-fpm が残存し 9000 を握ったまま次回起動が二重 bind で失敗する自己増殖ループ。`exec` で php-fpm を PID1 にしてシグナルを直接受けさせ（停止時に 9000 を確実解放）、`-F` で `daemonize` 設定に依存せず必ずフォアグラウンド起動にした。全サイト共通で安全（コンテナで php-fpm を動かす定石）。復旧には `helm upgrade` に加え、残存プロセスを持つ既存 pod の削除が必要な場合がある。
**対象ファイル**: `templates/deployment.yaml`, `Chart.yaml`, `README.md`, `CLAUDE.md`, `CHANGELOG-8.5.9-d.md`
### Ingressのproxy-body-sizeもuploadMaxSizeに連動（2026-08-06, v8.5.9-c）
v8.5.9-bのフォローアップ。`templates/ingress.yaml` で `merge (deepCopy .Values.ingress.annotations) (dict "nginx.ingress.kubernetes.io/proxy-body-size" .Values.uploadMaxSize)` を使い、ユーザーが明示指定していなければ `uploadMaxSize` をIngressの `proxy-body-size` にも自動反映。明示指定があればそちらが優先（sprigのmergeはdst=ユーザー指定annotationsが優先、srcのデフォルト値は不足分のみ補う）。これで `uploadMaxSize` 1箇所でnginx・PHP・Ingressの3箇所すべてが揃う。
**対象ファイル**: `templates/ingress.yaml`, `values.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.9-c.md`
### uploadMaxSize の追加（2026-08-06, v8.5.9-b）
nginxの `client_max_body_size` とPHPの `upload_max_filesize`/`post_max_size` を1つの `uploadMaxSize`（デフォルト `"100m"`）で連動させるパラメータを追加。片方だけ上げてももう片方の上限でアップロードが無言で失敗する問題への対応。PHP側は起動時に `/usr/local/etc/php/conf.d/99-uploads.ini` を常時生成（他機能の有効/無効に依存しない）。memory_limitは対象外（別途必要なら将来検討）。
**対象ファイル**: `values.yaml`, `templates/configmap.yaml`, `templates/deployment.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.9-b.md`
### sitemap.xml のContent-Type明示（2026-08-06, v8.5.9-a）
`templates/configmap.yaml` に `location = /sitemap.xml { types { } default_type "application/xml; charset=utf-8"; ... }` を追加。標準mime.typesでは `.xml` が `text/xml` 扱いでcharset無しになる問題への対応。静的ファイルの場合のみ有効、PHP動的生成には効かない（PHP側でheader()指定が必要）。設定不要・常時有効。
**対象ファイル**: `templates/configmap.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.9-a.md`
### Python導入オプションの追加（2026-07-19, v8.5.8-a）
`python` セクションを新設し、`values.yaml` の設定だけでPython仮想環境(venv)を導入可能にした。Composerと同じ設計方針（デフォルト導入先 `/venv` はPVC非マウントの使い捨て領域、`packages`/`useRequirementsTxt`の二択、`additionalApkPackages`でネイティブ拡張ビルド対応）。requirements.txtの展開は `trim | nindent 14`（v8.5.6-dのバグ修正と同じ手法）。PHPからは `exec('/venv/bin/python3 script.py')` で呼び出す。
なお、この改修中に自動更新ワークフローがPHP 8.5.8へのフルリリース（v8.5.8）を実行したため、本機能はそのタグの上に手動リリース `8.5.8-a` として適用した。
**対象ファイル**: `values.yaml`, `templates/deployment.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.8-a.md`
### /etc/msmtprc の権限を0600→0644に修正（2026-07-19, v8.5.6-g）
v8.5.6-f のフォローアップ。`/etc/smtp-secrets/password` の権限修正だけでは不十分で、起動スクリプトが `cp` 後に `chmod 600` していた `/etc/msmtprc` 自体もrootのみ読み取り可のままだった（msmtp: account default not found, exit:78）。`chmod 644` に変更。msmtprcには平文パスワードは含まれない（passwordeval経由で別ファイル参照）ため実害なし。
**対象ファイル**: `templates/deployment.yaml`, `Chart.yaml`, `CHANGELOG-8.5.6-g.md`
### SMTPパスワードSecretの権限を0600→0644に修正（2026-07-19, v8.5.6-f）
`smtp-secrets` ボリュームの `mode: 0600` が原因で、rootではなく `www-data`（PHP-FPMワーカー）として動く msmtp が `/etc/smtp-secrets/password` を読めず、SMTP認証に失敗する不具合を修正。`0644` に変更（Pod内にしか存在しないファイルのため許容範囲）。
**対象ファイル**: `templates/deployment.yaml`, `Chart.yaml`, `CHANGELOG-8.5.6-f.md`
### PVCルートを /var/www にマウント + /composer を使い捨て化（2026-07-19, v8.5.6-e）
php-fpm コンテナのマウントを「`html` サブパスのみ」から「PVCルート → `/var/www`」に変更。`html/` は公開フォルダ、それ以外（`/var/www/<任意>`）は非公開ファイルの格納先として使える。nginx は `html` サブパスのみマウントするため非公開分は公開されない。あわせて `/composer` のPVC永続化マウントを廃止し、Pod再起動ごとにクリーン再構築される使い捨て領域とした（マルウェア混入対策、ユーザー要望）。永続化したい場合は `workingDir` に `/var/www/composer` 等を指定。
**対象ファイル**: `templates/deployment.yaml`, `values.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.6-e.md`
### useComposerJson の YAML parse error 修正（2026-07-19, v8.5.6-d）
`useComposerJson: true` 指定時、heredoc 内の `{{ .Values.composer.composerJson }}` がインデント無しで展開され、複数行JSONの2行目以降がブロックスカラーを破壊して YAML parse error になる潜在バグを修正。`trim | nindent 14` で展開するよう変更（`composerLock` も同様）。
**対象ファイル**: `templates/deployment.yaml`, `Chart.yaml`, `CHANGELOG-8.5.6-d.md`
### Composerデフォルト導入先を /composer に変更（2026-07-19, v8.5.6-c）
`/var/www` はWebルート `/var/www/html` の親のため、ネストマウントでPVCの `composer` サブパス内に空の `html/` が生成されていた。デフォルトをWebルートと親子関係にない `/composer` に変更してネストを解消。autoloadは `require_once '/composer/vendor/autoload.php';`（values.yaml のコメントにも明記）。
**対象ファイル**: `values.yaml`, `templates/deployment.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.6-c.md`
### 旧composer.jsonの自動移行 + mbstring依存の自動追加（2026-07-19, v8.5.6-b）
v8.5.6-a のフォローアップ。起動時に `workingDir` に `composer.json` が無く旧Webルート `/var/www/html` にある場合、`composer.json` / `composer.lock` / `vendor/` を自動移行する。また `additionalPhpExtensions` に `mbstring` 指定時、ビルドに必要な `oniguruma-dev` を自動追加（GDと同じ仕組み）。
なお、PVC上の `composer/html/`（空ディレクトリ）はネストマウントのマウントポイント作成による正常な副産物で、実害なし。
**対象ファイル**: `templates/deployment.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.6-b.md`
### composer.workingDir — Composer導入先のWebルート外への変更（2026-07-19, v8.5.6-a）
Composerの導入先をWebルート `/var/www/html` からWebルート外の `/var/www` に変更し、`vendor/` や `composer.json` がWeb経由で公開されないようにした。`values.yaml` の `composer.workingDir` で導入先を変更可能（旧動作に戻すには `"/var/www/html"` を指定）。導入先がWebルート以外の場合、PVCの `composer` サブパスをマウントして永続化する。
PHP側の読み込みは `require_once '/var/www/vendor/autoload.php';`。
**対象ファイル**: `values.yaml`, `templates/deployment.yaml`, `README.md`, `Chart.yaml`, `CHANGELOG-8.5.6-a.md`
### phpEnv — 汎用 PHP 環境変数サポート（2026-04-17）
`values.yaml` に `phpEnv` セクションを追加し、DB 接続情報と同様に任意のキーと値を PHP-FPM コンテナの環境変数として渡せるようにした。
```yaml
phpEnv:
API_KEY: "your-api-key"
STRIPE_SECRET: "sk_live_..."
REDIS_URL: "redis://localhost:6379"
```
PHP 側では `$_ENV['API_KEY']` または `getenv('API_KEY')` で取得できる。
**対象ファイル**: `values.yaml`, `templates/deployment.yaml`, `README.md`
Reference in New Issue View Git Blame Copy Permalink