claude
2b17088fae
Helm Chart Release / release-chart (push) Successful in 7s
phpfpm の smtp.existingMsmtprcSecret が「references non-existent secret key: msmtprc」でマウント失敗する件の対処。renderMsmtprc が opt-in で忘れやすかった。 - renderMsmtprc を既定 true に（明示 false のときだけ抑止） - smtp.tlsVerify（既定 true）を追加。false で msmtprc に tls_certcheck off values.schema.json の smtp にも tlsVerify を追加 - 派生キー SMTP_TLS / SMTP_SSL / SMTP_TLS_VERIFY / SMTP_AUTH を Secret に追加 - from 未設定時に msmtprc へ空の from 行を出さないよう修正 - values.yaml / examples / README を更新。0.1.2。
162 lines
11 KiB
Markdown
162 lines
11 KiB
Markdown
# CLAUDE.md — secret-manager Helm Chart
|
||
|
||
> **共通ルール（要約）** — 詳細は `P:\Claude\CLAUDE.md`（全体共通）と `P:\Claude\HelmChart\CLAUDE.md`（Helm チャート共通: リリースフロー・ワークフロー・Gitea Secrets）を参照。
|
||
> 作業前に pull ／ 機能変更時は README 更新 ／ 作業単位ごとに commit → push まで ／ コミットに AI クレジットを付けない ／ pull で入った変更を revert しない ／ Helm はローカル実行不可（Python のみ可）。
|
||
|
||
## リポジトリ概要
|
||
|
||
クラスター内の複数プロジェクトで横断的に使う「認証情報」を 1 つの Helm チャートで
|
||
一元管理する。外部メールの SMTP/IMAP 設定・API キー・汎用資格情報を定義し、
|
||
指定した複数ネームスペースへ同一の Kubernetes Secret として配布する。
|
||
|
||
**設計目標**: 認証情報の変更が発生したら、このチャートの values を更新して
|
||
`helm upgrade` するだけで、クラスター上の全プロジェクトに反映される。
|
||
|
||
- **Gitea リポジトリ**: `ssh://git@192.168.9.65/helmchart/secret-manager`
|
||
- **Helm リポジトリ**: `https://git.cafepieters.com/api/packages/helmchart/helm`
|
||
|
||
## バージョン方針（組織ルールの例外）
|
||
|
||
- このチャートには「主アプリ」となる外部プロダクトが存在しない（チャート自身がアプリ）。
|
||
そのため `Chart.yaml` の `version` / `appVersion` は **チャート独自に SemVer で採番**する。
|
||
（組織ルール「主アプリのバージョンと同一」は適用対象外）
|
||
- 破壊的変更 = メジャー、機能追加 = マイナー、修正 = パッチ。
|
||
|
||
## リリースフロー（組織ルールとの差分）
|
||
|
||
新バージョンを出す手順は「`Chart.yaml` の `version` / `appVersion` を上げて `main` に push」だけ。
|
||
以降は CI が処理する。
|
||
|
||
### `.gitea/workflows/helm-release.yaml`（push トリガ）
|
||
- `main` への push（`Chart.yaml` / `values.yaml` / `values.schema.json` / `templates/**` 変更時）
|
||
および手動実行で発火。
|
||
- `helm lint --strict` → **現在の `version` が Package Registry に未公開のときだけ**
|
||
リリースする（`helm search repo --version` で存在確認）。
|
||
- 他リポジトリの「毎 push で無条件公開」する共通版とは意図的に異なる。README・examples
|
||
だけの変更で push してもリリースは発生しない。
|
||
- リリース内容 = Package Registry 発行 + Git タグ `v<version>` + Gitea リリース（`.tgz` 添付）。
|
||
タグ・リリースは既存なら skip（冪等）。
|
||
|
||
### `.gitea/workflows/image-update-and-release.yaml` は持たない（組織ルールの例外）
|
||
- 組織共通の「各リポジトリ共通の2本」構成の例外。このチャートは Secret を生成するだけで
|
||
**追従対象の上流イメージが存在しない**ため、週次の自動更新ワークフロー自体を置かない。
|
||
- バージョンは常に手動で `Chart.yaml` の `version` / `appVersion` を更新して判断する。
|
||
- 将来サブチャート等の追従対象ができた場合は、このワークフローを新設して対応する。
|
||
|
||
### 手動リリース（臨時）
|
||
- 改修作業で臨時リリースが必要なら `version` 末尾にアルファベットを付与（例: `0.2.0` → `0.2.0-a`）。
|
||
|
||
## アーキテクチャ要点
|
||
|
||
- `templates/_helpers.tpl` の `secret-manager.secret` が中核。
|
||
1 論理 Secret を受け取り、実効ネームスペースごとに複製した Secret マニフェストを出力する。
|
||
- 配布先の決定順:
|
||
1. エントリの `namespacesOverride`（非空ならそれを使用）
|
||
2. `distribution.reflector.enabled` が true → リリース先ネームスペースのみに作成し reflector アノテーション付与
|
||
3. それ以外 → `distribution.namespaces` (+ `includeReleaseNamespace`) を重複排除した一覧
|
||
- Helm はリリースマニフェストに含まれる別ネームスペースの Secret も追跡するため、
|
||
`namespaces` からネームスペースを外して `helm upgrade` するとそのコピーは削除される。
|
||
- 資格情報は `stringData` で書き込む（テンプレート側で全値を文字列へ強制）。
|
||
- 平文の資格情報を含む values（`secrets.values.yaml` 等）は `.gitignore` 済み。絶対にコミットしない。
|
||
|
||
## チャート改修履歴
|
||
|
||
### renderMsmtprc を既定 true 化 + SMTP メタ項目の拡充（2026-09-08, v0.1.2）
|
||
|
||
**症状**: phpfpm 側で `smtp.existingMsmtprcSecret: cred-<名前>` を指定したら
|
||
`MountVolume.SetUp failed ... references non-existent secret key: msmtprc`。
|
||
配布された `cred-*` Secret に `msmtprc` キーが無かった。
|
||
|
||
**原因**: `mail.providers.<名前>.renderMsmtprc` が opt-in（既定で出力しない）で、
|
||
`values.yaml` 上もコメント例にしか無かったため、指定を忘れると `msmtprc` キーが
|
||
生成されない。`mail` カテゴリは「完成済み msmtprc も含めて一元管理する」のが目的なので
|
||
opt-out にすべきだった。
|
||
|
||
**修正内容**（`templates/mail-secrets.yaml`）:
|
||
- `renderMsmtprc` を既定 `true` に（`hasKey` で明示 `false` のときだけ抑止）。
|
||
- `smtp.tlsVerify`（既定 `true`）を追加。`false` で `msmtprc` に `tls_certcheck off` を挿入。
|
||
`values.schema.json` の `smtp`（`additionalProperties: false`）にも `tlsVerify` を追加。
|
||
- 派生キーを Secret に追加: `SMTP_TLS`（starttls か）/ `SMTP_SSL`（暗黙TLSか）/
|
||
`SMTP_TLS_VERIFY` / `SMTP_AUTH`（username 有無）。すべて `"true"`/`"false"` の文字列。
|
||
`smtp.env` にもこれらが入る（msmtprc 生成より前に env を組み立てているため）。
|
||
- `values.yaml` のキー一覧コメント / プロバイダ例、`examples/mail-providers.values.yaml`
|
||
（`tlsVerify: false` の社内リレー例を追加）、README を更新。
|
||
|
||
**対象ファイル**: `templates/mail-secrets.yaml`, `values.schema.json`, `values.yaml`,
|
||
`examples/mail-providers.values.yaml`, `Chart.yaml`, `README.md`, `CLAUDE.md`
|
||
|
||
### helm-release.yaml のリリース判定を3系統に分離 + v0.1.0 タグ補完（2026-09-08）
|
||
|
||
**症状**: Git タグ `v0.1.0` がリモートに存在しなかった（Registry には
|
||
`secret-manager-0.1.0.tgz` は発行済み）。
|
||
|
||
**原因**: 初回リリース（run #1 / `f374cd2`）時点の `helm-release.yaml` は
|
||
共通版のコピー（タグ作成ステップ無し）だった。タグ作成ステップを持つ現行版に
|
||
差し替えたのは run #2 だが、その時点で `0.1.0` は既に Registry 登録済みのため
|
||
`release_needed=false` となり、タグ作成を含む全ステップがスキップされていた。
|
||
= 「Registry 発行済み」と「タグ/リリース作成」が同一フラグに束ねられており、
|
||
一方だけ欠けた状態を回復できない構造だった。
|
||
|
||
**修正内容**:
|
||
- `helm-release.yaml` の判定を `registry_needed` / `tag_needed` / `release_needed`
|
||
の3独立フラグに分離。各成果物を個別に冪等チェックし、不足分だけを作る。
|
||
途中のステップだけ失敗しても次の push で自己修復する。
|
||
- タグ有無は `git ls-remote --tags` でリモート基準に確認。
|
||
- 欠けていた `v0.1.0` タグを `f374cd2`（Registry の 0.1.0 tgz と同じツリー）に
|
||
対して手動で作成・push（過去分の履歴補完。Gitea リリースは 0.1.0 が既知不具合
|
||
バージョンのため作らない）。
|
||
|
||
**対象ファイル**: `.gitea/workflows/helm-release.yaml`, `README.md`, `CLAUDE.md`
|
||
（+ リモートタグ `v0.1.0` を追加）
|
||
|
||
### values.schema.json の $schema 行を削除（2026-09-08, v0.1.1）
|
||
|
||
**症状**: 一部のデプロイ環境（新しめの JSON Schema バリデータを内蔵する Helm / Argo CD /
|
||
Flux 等）で `An error occurred: no schema with key or ref "https://json-schema.org/draft-07/schema#"`
|
||
が出てデプロイできない。
|
||
|
||
**原因**: `values.schema.json` の `"$schema": "https://json-schema.org/draft-07/schema#"` を
|
||
メタスキーマとして解決しようとし、オフライン環境で失敗していた。`santhosh-tekuri/jsonschema`
|
||
系のバリデータは `https://` 版の draft-07 メタスキーマ URL をバンドルしていない。
|
||
|
||
**修正内容**: `$schema` 行を削除。Helm は `$schema` を必須としておらず、本スキーマは
|
||
ドラフト非依存のキーワード（`type` / `properties` / `required` / `enum` / `additionalProperties` /
|
||
`minLength` / `minimum` / `maximum` / `minProperties` / 単一スキーマの `items`）しか使って
|
||
いないため、`helm lint --strict` の検証（未知キーの検出など）は従来どおり機能する。
|
||
|
||
**修正リリース**: `0.1.0` は登録済みのため（同一バージョンは再発行されない）、`0.1.1` として発行。
|
||
|
||
**対象ファイル**: `values.schema.json`, `Chart.yaml`, `README.md`, `CLAUDE.md`
|
||
|
||
### 週次ワークフローの削除（2026-09-05）
|
||
|
||
`image-update-and-release.yaml`（週次セーフティネット）を削除。追従すべき上流イメージが
|
||
無いチャートに「更新チェック」ワークフローを持たせる意味が無いと判断。リリースは
|
||
`helm-release.yaml`（push トリガ・未公開バージョンのみリリース）の1本のみに一本化。
|
||
組織共通の「各リポジトリ共通の2本」構成の例外として本ファイルに明記。
|
||
|
||
**対象ファイル**: `.gitea/workflows/image-update-and-release.yaml`（削除）, `README.md`, `CLAUDE.md`
|
||
|
||
### 自動更新・リリースワークフローの整備（2026-09-03, v0.1.0）
|
||
|
||
`.gitea/workflows/` を 2 本体制に。`helm-release.yaml` を「無条件公開」から
|
||
「未公開バージョンのみリリース」に変更（`helm search repo --version` で存在確認し、
|
||
未公開時のみ Package Registry 発行 + Git タグ + Gitea リリース）。`paths` フィルタで
|
||
`Chart.yaml`/`values.yaml`/`values.schema.json`/`templates/**` の変更時のみ発火。
|
||
`image-update-and-release.yaml` を新設（週次）。上流イメージが無いチャートのため
|
||
バージョン自動採番はせず、push 側の取りこぼし対策（未公開バージョンの週次リリース）
|
||
として動作。将来の追従対象追加用コメントブロックを同梱。
|
||
|
||
**対象ファイル**: `.gitea/workflows/helm-release.yaml`,
|
||
`.gitea/workflows/image-update-and-release.yaml`, `README.md`, `CLAUDE.md`
|
||
|
||
### 初版設計・実装（2026-08-31, v0.1.0）
|
||
|
||
空リポジトリから初期実装。`distribution`（namespaces 複製 / reflector / reloader）、
|
||
`common`（namePrefix・labels・annotations・immutable）、`mail.providers`（SMTP/IMAP/POP3 +
|
||
`smtp.env` + 任意の `msmtprc`）、`api.credentials`、`generic.secrets`（任意 type）を実装。
|
||
`values.schema.json`、`examples/`、`.gitea/workflows/helm-release.yaml` を追加。
|
||
|
||
**対象ファイル**: `Chart.yaml`, `values.yaml`, `values.schema.json`, `templates/*`,
|
||
`examples/*`, `.gitea/workflows/helm-release.yaml`, `README.md`, `.gitignore`, `CLAUDE.md`
|