helm-validator

Helm チャート検証・分析ツールキット

概要

このスキルは、Helm 標準の lint、テンプレートのレンダリング、YAML 検証、スキーマ検証、CRD ドキュメントの検索、セキュリティのベストプラクティスの確認を組み合わせた、Helm チャートの包括的な検証・分析ワークフローを提供します。

重要：このバリデーターはデフォルトで読み取り専用です。 チャートを分析し、改善案を提案します。ユーザーから修正の適用を明示的に依頼された場合にのみ、ファイルを変更してください。

起動条件

次の主な条件のいずれかに該当する場合、このスキルを使用してください。

• ユーザーが Helm チャートの検証、lint、確認、テスト、トラブルシューティングを依頼した場合
• Helm テンプレートのレンダリングや lint に失敗する、または有効な Kubernetes YAML が生成されない場合
• デプロイ前の品質ゲート（スキーマ、ドライラン、セキュリティチェック）が必要な場合
• CRD リソースが含まれており、その spec フィールドをドキュメントに照らして確認する必要がある場合
• ユーザーが、重大度に基づく検証レポートと修正案を求めている場合

起動フレーズの例：

• 「リリース前にこの Helm チャートを検証してください」
• 「helm template が失敗するのはなぜですか？」
• 「このチャートに Kubernetes とセキュリティの問題がないか確認してください」

デフォルトで対象外：

• 新しいチャートのひな形作成や大規模なチャート生成（helm-generator を使用してください）

役割の境界

• このスキルは検証と報告を行い、ユーザーファイルを黙って書き換えることはありません。
• 具体的なパッチを提案できますが、適用するのはユーザーから修正の依頼を明示的に受けた場合に限ります。
• 実行上の制約によってあるステージを実行できない場合でも、実行可能なステージを続行し、スキップした理由を記録する必要があります。

実行モデル

1. ステージを順番に（1 から 10 まで）実行します。
2. ステージレベルの失敗があっても、すべての検出結果を収集するため続行します。ただし、レンダリングに失敗し、マニフェストが存在しない場合を除きます。
3. ステージ 4 でマニフェストが生成されない場合は、ステージ 5 から 9 をブロック扱いとし、ステージ 10 のレポートに進みます。
4. ステージ 8 は環境に依存する任意のステージとして扱い、ステージ 9 と 10 はマニフェストが存在する場合に必須とします。
5. スキップしたすべてのステージについて、正確なツールまたは環境上の理由を最終サマリー表に記録します。

クイック実行モード

モード A：ローカル検証（クラスター不要）

bash scripts/setup_tools.sh
bash scripts/validate_chart_structure.sh <chart-directory>
helm lint <chart-directory> --strict
helm template <release-name> <chart-directory> --values <values-file> --debug --output-dir ./rendered
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec yamllint -c assets/.yamllint {} +
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec kubeconform -summary -verbose {} +

モード B：完全検証（クラスターを利用可能）

モード A に加え、このドキュメントのステージ 8 のドライランコマンドを実行します。

検証・テストのワークフロー

次の順序で検証ワークフローを実行します。各ステージで、異なる種類の問題を検出します。

ステージ 1：ツールの確認

検証を開始する前に、必要なツールがインストールされていることを確認します。

bash scripts/setup_tools.sh

必要なツール：

• helm：Kubernetes 用 Helm パッケージマネージャー（v3 以降）
• yamllint：YAML 構文とスタイルの lint ツール
• kubeconform：CRD をサポートする Kubernetes スキーマ検証ツール
• kubectl：クラスターのドライランテスト用（任意ですが推奨）

ツールが利用できない場合、または環境上の制約がある場合のフォールバック方針：

条件	対応	ステージの状態
helm が見つからない	ステージ 2 のみを実行し、その後ステージ 3 から 9 をスキップ／ブロックとして報告	⚠️ 警告
yamllint が見つからない	利用可能であれば yq で構文を確認し、そうでなければステージ 5 をスキップ	⚠️ 警告
kubeconform が見つからない	ステージ 7 をスキップし、ステージ 6 の CRD／手動確認に依拠	⚠️ 警告
kubectl が見つからない、または kube-context がない	ステージ 8 をスキップし、残りのステージを続行	⚠️ 警告
CRD ドキュメントを参照するインターネット接続がない	ローカルの CRD マニフェストと kubeconform の出力を使用し、ドキュメント検索が未完了であることを記録	⚠️ 警告

ツールが見つからない場合は、scripts/setup_tools.sh の出力からインストール手順を提示し、上記のフォールバック手順に従って続行してください。

ステージ 2：Helm チャート構造の検証

チャートが標準の Helm ディレクトリ構造に従っていることを確認します。

bash scripts/validate_chart_structure.sh <chart-directory>

想定される構造：

mychart/
  Chart.yaml          # Chart metadata (required)
  values.yaml         # Default values (required)
  values.schema.json  # JSON Schema for values validation (optional)
  templates/          # Template directory (required)
    _helpers.tpl      # Template helpers (recommended)
    NOTES.txt         # Post-install notes (recommended)
    *.yaml            # Kubernetes manifest templates
  charts/             # Chart dependencies (optional)
  crds/               # Custom Resource Definitions (optional)
  .helmignore         # Files to ignore during packaging (optional)

検出できる一般的な問題：

• 必須ファイル（Chart.yaml、values.yaml、templates/）がない
• Chart.yaml の構文が無効、または必須フィールドがない
• values.schema.json の形式が不正
• ファイルのアクセス権限が不適切

ステージ 3：Helm の Lint

Helm に組み込まれているリンターを実行して、チャート固有の問題を検出します。

helm lint <chart-directory> --strict

省略可能なフラグ：

• --values <values-file>：指定した値でテストします
• --set key=value：特定の値を上書きします
• --debug：詳細なエラー情報を表示します

よく検出される問題：

• Chart.yaml のメタデータが無効
• テンプレートの構文エラー
• 値の欠落または未定義
• Kubernetes API バージョンの非推奨化
• チャートのベストプラクティスへの違反

自動修正の方法：

• テンプレートエラーの場合は、問題のあるテンプレートファイルを特定します
• 問題の原因となっている具体的な行をユーザーに示します
• 修正用のパッチ／差分を提案します
• ユーザーから明示的に依頼された場合にのみ修正を適用します
• 修正を適用した後、helm lint を再実行します

ステージ 4：テンプレートのレンダリング

テンプレートをローカルでレンダリングし、有効な YAML が生成されることを確認します。

helm template <release-name> <chart-directory> \
  --values <values-file> \
  --debug \
  --output-dir ./rendered

検討するオプション：

• --values values.yaml：指定した値ファイルを使用します
• --set key=value：個別の値を上書きします
• --show-only templates/deployment.yaml：特定のテンプレートをレンダリングします
• --validate：Kubernetes OpenAPI スキーマに対して検証します
• --include-crds：レンダリングされた出力に CRD を含めます
• --is-upgrade：アップグレードのシナリオをシミュレートします
• --kube-version 1.28.0：特定の Kubernetes バージョンを対象にします

よく検出される問題：

• テンプレートの構文エラー（Go テンプレートの問題）
• 未定義の変数または値
• 型の不一致（文字列と整数など）
• 必須値の欠落
• 条件分岐やループのロジックエラー
• 入れ子になったテンプレートのインデントの誤り

テンプレートエラーの場合：

• テンプレートファイルと行番号を特定します
• values.yaml で値が適切に定義されているか確認します
• テンプレート関数（quote、required、default、include など）の使用方法を確認します
• さまざまな値の組み合わせでテストします

ステージ 5：YAML 構文の検証

レンダリングされたテンプレートの YAML 構文と書式を検証します。

find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec yamllint -c assets/.yamllint {} +

よく検出される問題：

• インデントの誤り（タブとスペースの混在）
• 末尾の空白
• 行の長さの違反
• 構文エラー
• キーの重複
• ドキュメントの開始／終了マーカー

自動修正の方法：

• 単純な問題（インデント、末尾の空白）の場合は、Edit ツールを使用した修正を提案します
• テンプレートの生成に起因する問題は、レンダリングされた出力ではなく、元のテンプレートを修正します
• 修正を適用する前に、変更内容を必ずユーザーに提示します

ステージ 6：CRD の検出とドキュメントの検索

スキーマ検証の前に、チャートにカスタムリソース定義が含まれているか、レンダリングによって生成されるかを検出します。

# Check crds/ directory
if [ -d <chart-directory>/crds ]; then
  find <chart-directory>/crds -type f \( -name "*.yaml" -o -name "*.yml" \) \
    -exec bash scripts/detect_crd_wrapper.sh {} +
fi

# Check rendered templates
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec bash scripts/detect_crd_wrapper.sh {} +

スクリプトはリソース情報を含む JSON を出力します。

[
  {
    "kind": "Certificate",
    "apiVersion": "cert-manager.io/v1",
    "group": "cert-manager.io",
    "version": "v1",
    "isCRD": true,
    "name": "example-cert"
  }
]

検出された各 CRD に対して：

1. まず context7 MCP を試します（推奨）：

   Use mcp__context7__resolve-library-id with the CRD project name
   Example: "cert-manager" for cert-manager.io CRDs
            "prometheus-operator" for monitoring.coreos.com CRDs
            "istio" for networking.istio.io CRDs
   
   Then use mcp__context7__query-docs with:
   - libraryId from resolve step
   - query: The CRD kind and relevant features (e.g., "Certificate spec required fields")
   

2. Context7 が失敗した場合は、web.search_query（ウェブ検索）にフォールバックします：

   Search query pattern:
   "<kind>" "<group>" kubernetes CRD "<version>" documentation spec
   
   Example:
   "Certificate" "cert-manager.io" kubernetes CRD "v1" documentation spec
   "Prometheus" "monitoring.coreos.com" kubernetes CRD "v1" documentation spec
   

3. 重要な情報を抽出します：

   • spec の必須フィールド
   • フィールドの型と検証ルール
   • ドキュメントの例
   • バージョン固有の変更点や非推奨化
   • 一般的な設定パターン

これが重要な理由： CRD には、標準的な Kubernetes 検証ツールでは利用できないカスタムスキーマがあります。CRD の spec 要件を理解することで、検証エラーを防ぎ、リソースを正しく設定できます。

Stage 7: スキーマの検証

レンダリングされたテンプレートを Kubernetes スキーマに対して検証します。

find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec \
  kubeconform \
    -schema-location default \
    -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
    -summary \
    -verbose \
    {} +

検討するオプション：

• 不明なフィールドを拒否するには、-strict を追加します（本番環境では推奨）
• カスタム／内部 CRD を扱う場合は、-ignore-missing-schemas を追加します
• 特定の K8s バージョンに対して検証するには、-kubernetes-version 1.28.0 を追加します
• プログラムで処理するには、-output json を追加します

よく検出される問題：

• 無効な apiVersion または kind
• 必須フィールドの欠落
• フィールドの型の誤り
• 無効な列挙値
• 不明なフィールド（-strict を指定した場合）

CRD の場合： kubeconform が「no schema found」を報告するのは想定どおりです。Stage 6 のドキュメントを使用して、spec フィールドを手動で検証してください。

Stage 7 の成功基準（明示）：

• ✅ 合格：kubeconform が終了コード 0 で終了し、無効なリソースが報告されていません。
• ⚠️ 警告：CRD のスキーマ欠落に関する指摘のみが残っており、Stage 6 のドキュメント作成と手動検証が完了しています。
• ❌ 失敗：CRD 以外のスキーマ違反、解析エラー、または未解決の必須フィールド／型エラーがあります。

Stage 8: クラスターのドライラン（利用可能な場合）

kubectl が設定され、クラスターにアクセスできる場合は、サーバーサイドのドライランを実行します。

# Test installation
helm install <release-name> <chart-directory> \
  --dry-run=server \
  --debug \
  --values <values-file>

# Test upgrade
helm upgrade <release-name> <chart-directory> \
  --dry-run=server \
  --debug \
  --values <values-file>

Helm のバージョンが --dry-run=server をサポートしていない場合は、--dry-run を使用し、クライアントサイドの Helm シミュレーションのみを実行したことを記録してください。

以下を検出できます：

• アドミッションコントローラーによる拒否
• ポリシー違反（PSP、OPA、Kyverno など）
• リソースクォータ違反
• 名前空間の欠落
• 無効な ConfigMap／Secret の参照
• Webhook による検証
• 既存リソースとの競合

ドライランを実行できない場合：

• レンダリングされたテンプレートに対して kubectl を使用します：kubectl apply --dry-run=server -f ./rendered/
• クラスターにアクセスできない場合はスキップします
• クラスター固有の検証をスキップしたことを記録します

既存のリリースを更新する場合：

helm diff upgrade <release-name> <chart-directory>

これにより変更内容を確認でき、意図しない変更の検出に役立ちます。（helm-diff プラグインが必要です）

Stage 8 の成功基準（明示）：

• ✅ 合格：ドライランのインストールおよびアップグレードコマンドが終了コード 0 で終了し、アドミッション／ポリシーエラーがありません。
• ⚠️ 警告：kubectl／クラスターコンテキスト／アクセスが利用できないためにステージをスキップした場合、またはクライアントサイドの代替手段しか利用できなかった場合です。
• ❌ 失敗：アドミッション Webhook、ポリシー違反、名前空間／クォータエラー、または参照エラーにより、ドライランコマンドがゼロ以外の終了コードを返します。

Stage 9: セキュリティのベストプラクティス確認（必須）

重要： このステージは必須です。レンダリングされたテンプレートを分析し、セキュリティのベストプラクティスに準拠しているか確認してください。

レンダリングされた Deployment／Pod テンプレートで、以下を確認します：

1. securityContext の欠落 - セキュリティ設定がない Pod／コンテナを確認します：

   # Check if pod-level securityContext exists
   spec:
     securityContext:
       runAsNonRoot: true
       runAsUser: 1000
       fsGroup: 2000
   

2. コンテナの securityContext の欠落 - 各コンテナには以下を設定する必要があります：

   securityContext:
     allowPrivilegeEscalation: false
     readOnlyRootFilesystem: true
     runAsNonRoot: true
     capabilities:
       drop:
         - ALL
   

3. リソースの limits／requests の欠落 - 以下を確認します：

   resources:
     limits:
       cpu: "100m"
       memory: "128Mi"
     requests:
       cpu: "100m"
       memory: "128Mi"
   

4. イメージタグの問題 - :latest を使用している場合、またはタグがない場合に警告します

5. プローブの欠落 - liveness／readiness プローブを確認します

確認方法： レンダリングされた deployment YAML ファイルを読み込み、これらのパターンを grep で検索します：

# Check for securityContext
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep -l "securityContext" {} +

# Check for resources
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep -l "resources:" {} +

# Check for latest tag
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep "image:.*:latest" {} +

Stage 10: 最終レポート（必須）

重要： すべての検証に合格した場合でも、このステージは必須です。以下のすべての作業を必ず完了してください。

デフォルトの動作は読み取り専用です。 ユーザーから修正の適用を明示的に求められない限り、ファイルを変更しないでください。

Step 1: 参照ファイルを読み込む（警告がある場合は必須）

警告、エラー、またはセキュリティ上の問題が1つでも見つかった場合は、必ず以下を読み込んでください：

Read references/helm_best_practices.md
Read references/k8s_best_practices.md

これらの参照資料を使用して、見つかった各問題の背景と推奨事項を提示してください。

Step 2: 検証の概要を提示する

必ず検証の概要を表形式で提示し、以下を示してください：

• 実行した各検証ステージ（Stages 1-9）
• 各ステージのステータス（✅ 合格、⚠️ 警告、❌ 失敗）
• ステージごとに見つかった問題の件数

例：

| Stage | Status | Issues |
|-------|--------|--------|
| 1. Tool Check | ✅ Passed | All tools available |
| 2. Structure | ⚠️ Warning | Missing: .helmignore, NOTES.txt |
| 3. Helm Lint | ✅ Passed | 0 errors |
| 4. Template Render | ✅ Passed | 5 templates rendered |
| 5. YAML Syntax | ✅ Passed | No yamllint errors |
| 6. CRD Detection | ✅ Passed | 1 CRD documented |
| 7. Schema Validation | ✅ Passed | All resources valid |
| 8. Dry-Run | ✅ Passed | No cluster errors |
| 9. Security Check | ⚠️ Warning | Missing securityContext |

ステップ 3：すべての問題を分類する

検出事項を重大度別に分類します。

❌ エラー（必ず修正）：

• テンプレート構文エラー
• 必須フィールドの不足
• スキーマ検証の失敗
• ドライランの失敗

⚠️ 警告（修正を推奨）：

• 非推奨の Kubernetes API
• securityContext の不足
• リソースの上限／リクエストの不足
• :latest イメージタグの使用
• 推奨ファイル（_helpers.tpl、.helmignore、NOTES.txt）の不足

ℹ️ 情報（推奨事項）：

• values.schema.json の不足
• README.md の不足
• 最適化の機会

ステップ 4：変更案を一覧表示する（適用しないでください）

各問題について、次の内容を含む修正案を提示します。

• ファイルパスと行番号（該当する場合）
• 変更前／変更後のコードブロック
• この変更を推奨する理由の説明

形式の例：

## Proposed Changes

### 1. Add securityContext to Deployment
**File:** templates/deployment.yaml:25
**Severity:** ⚠️ Warning
**Reason:** Running containers as root is a security risk

**Current:**
```yaml
spec:
  containers:
    - name: app
      image: nginx:1.21

提案：

spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 2000
  containers:
    - name: app
      image: nginx:1.21
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop:
            - ALL

2. .helmignore ファイルを追加する

ファイル： .helmignore（新規ファイル） 重大度： ⚠️ 警告 理由： チャートのパッケージ化時に不要なファイルを除外します

提案： assets/.helmignore からコピーします

#### Step 5: Automation Opportunities

List all detected automation opportunities:
- If `_helpers.tpl` is missing → Recommend: `bash scripts/generate_helpers.sh <chart>`
- If `.helmignore` is missing → Recommend: Copy from `assets/.helmignore`
- If `values.schema.json` is missing → Recommend: Copy and customize from `assets/values.schema.json`
- If `NOTES.txt` is missing → Recommend: Create post-install notes template
- If `README.md` is missing → Recommend: Create chart documentation

#### Step 6: Final Summary

Provide a final summary:

検証の概要

チャート： ステータス： ⚠️ 警告あり（または ✅ デプロイ可能）

検出された問題：

• エラー：X
• 警告：Y
• 情報：Z

変更案： N 件の変更を推奨

次のステップ：

1. 上記の変更案を確認します
2. 手動で変更を適用するか、helm-generator スキルを使用します
3. 検証を再実行して修正を確認します

## Workflow Done Criteria

Validation is complete only when all of the following are true:
- A Stage 1 to Stage 10 status table is present with `✅ Passed`, `⚠️ Warning`, `❌ Failed`, or `⏭️ Skipped` for each stage.
- Every skipped stage includes a concrete tool or environment reason.
- Stage 7 and Stage 8 are evaluated against their explicit success criteria above.
- Severity totals are reported (`Errors`, `Warnings`, `Info`) with proposed remediation actions.
- Role boundary is respected: no file edits unless explicitly requested by the user.

## Helm Templating Automation & Best Practices

This section covers advanced Helm templating techniques, helper functions, and automation strategies.

### Template Helpers (`_helpers.tpl`)

Template helpers are reusable functions defined in `templates/_helpers.tpl`. They promote DRY principles and consistency.

**Standard helper patterns:**

1. **Chart name helper:**
```yaml
{{/*
Expand the name of the chart.
*/}}
{{- define "mychart.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

2. Fullname ヘルパー：

{{/*
Create a default fully qualified app name.
*/}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

3. チャート参照ヘルパー：

{{/*
Create chart name and version as used by the chart label.
*/}}
{{- define "mychart.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

4. 標準ラベルヘルパー：

{{/*
Common labels
*/}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
{{ include "mychart.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

5. セレクターラベルヘルパー：

{{/*
Selector labels
*/}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

6. ServiceAccount 名ヘルパー：

{{/*
Create the name of the service account to use
*/}}
{{- define "mychart.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "mychart.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}

ヘルパーを作成するタイミング：

• 複数のテンプレートで使用される値
• 繰り返し使われる複雑なロジック
• 一貫性を保つ必要があるラベルセット
• 名前の生成パターン
• リソースの条件付き作成

必須のテンプレート関数

堅牢なチャートを作成するために、次の Helm テンプレート関数を参照して使用します。

1. required - 必須値を強制する：

apiVersion: v1
kind: Service
metadata:
  name: {{ required "A valid service name is required!" .Values.service.name }}

2. default - フォールバック値を指定する：

replicas: {{ .Values.replicaCount | default 1 }}

3. quote - 文字列値を安全に引用符で囲む：

env:
  - name: DATABASE_HOST
    value: {{ .Values.database.host | quote }}

4. include - パイプラインでヘルパーを使用する：

metadata:
  labels:
    {{- include "mychart.labels" . | nindent 4 }}

5. tpl - 文字列をテンプレートとしてレンダリングする：

{{- tpl .Values.customConfig . }}

6. toYaml - オブジェクトを YAML に変換する：

{{- with .Values.resources }}
resources:
  {{- toYaml . | nindent 2 }}
{{- end }}

7. fromYaml - YAML 文字列を解析する：

{{- $config := .Values.configYaml | fromYaml }}

8. merge - マップをマージする：

{{- $merged := merge .Values.override .Values.defaults }}

9. lookup - クラスターのリソースを照会する（慎重に使用してください）：

{{- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" }}
{{- if $secret }}
  # Secret exists, use it
{{- else }}
  # Create new secret
{{- end }}

高度なテンプレートパターン

1. リソースの条件付き作成：

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
# ... ingress definition
{{- end }}

2. リストの反復処理：

{{- range .Values.extraEnvVars }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

3. マップの反復処理：

{{- range $key, $value := .Values.configMap }}
{{ $key }}: {{ $value | quote }}
{{- end }}

4. スコープを設定する With ブロック：

{{- with .Values.nodeSelector }}
nodeSelector:
  {{- toYaml . | nindent 2 }}
{{- end }}

5. カスタムコンテキストを使用した名前付きテンプレート：

{{- include "mychart.container" (dict "root" . "container" .Values.mainContainer) }}

Values の構造に関するベストプラクティス

可能な場合はフラットな構造を優先します。

# Good - Flat structure
serverName: nginx
serverPort: 80

# Acceptable - Nested structure for related settings
server:
  name: nginx
  port: 80
  replicas: 3

values.yaml には必ずデフォルト値を指定します。

replicaCount: 1

image:
  repository: nginx
  pullPolicy: IfNotPresent
  tag: "1.21.0"

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi

すべての値を文書化します。

# replicaCount is the number of pod replicas for the deployment
replicaCount: 1

# image configures the container image
image:
  # image.repository is the container image registry and name
  repository: nginx
  # image.tag overrides the image tag (default is chart appVersion)
  tag: "1.21.0"

テンプレートのコメントとドキュメント

ドキュメントには Helm テンプレートコメントを使用します。

{{- /*
mychart.fullname generates the fullname for resources.
It supports nameOverride and fullnameOverride values.
Usage: {{ include "mychart.fullname" . }}
*/ -}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

ユーザー向けの注記には YAML コメントを使用します。

# WARNING: Changing the storage class will not migrate existing data
storageClass: "standard"

空白の管理

テンプレートディレクティブ内の空白を除去するには、- を使用します。

{{- if .Values.enabled }}
  # Remove leading whitespace
{{- end }}

{{ .Values.name -}}
  # Remove trailing whitespace

適切な書式：

{{- if .Values.enabled }}
  key: value
{{- end }}

不適切な書式：

{{if .Values.enabled}}
key: value
{{end}}

ヘルパーパターンのリファレンス

チャートを分析する際は、ヘルパー関数を導入できる箇所を特定します。

1. 繰り返しを特定する：

   • リソース間で同じラベルセットを使用している
   • 名前生成ロジックが繰り返されている
   • 共通の条件パターンがある

2. 推奨する一般的なヘルパーパターン：

   • チャート名ヘルパー（.name）
   • Fullname ヘルパー（.fullname）
   • チャートバージョンラベル（.chart）
   • 共通ラベル（.labels）
   • セレクターラベル（.selectorLabels）
   • ServiceAccount 名（.serviceAccountName）

3. ヘルパーを推奨するタイミング：

   • _helpers.tpl ファイルがない
   • テンプレート間でコードパターンが繰り返されている
   • ラベルの使用に一貫性がない
   • 切り詰めが必要な長いリソース名がある

ベストプラクティスのリファレンス

Helm と Kubernetes のベストプラクティスの詳細については、次のリファレンスを読み込んでください。

Read references/helm_best_practices.md
Read references/k8s_best_practices.md

これらのリファレンスには、次の内容が含まれています。

• Chart の構造とメタデータ
• テンプレートの規約とパターン
• Values ファイルの構成
• セキュリティのベストプラクティス
• リソースの上限とリクエスト
• よくある検証エラーと修正方法

読み込むタイミング： 検証で背景知識が必要な問題が見つかったとき、新機能を実装するとき、またはユーザーからベストプラクティスについて質問されたときです。

Chart の依存関係の操作

Chart に依存関係がある場合（Chart.yaml または charts/ ディレクトリ内）：

1. 依存関係を更新する：

helm dependency update <chart-directory>

2. 依存関係を一覧表示する：

helm dependency list <chart-directory>

3. 依存関係を検証する：

   • 依存関係のバージョンが利用可能であることを確認します
   • 依存関係の値が適切にスコープ設定されていることを確認します
   • 依存関係のリソースを使用してテンプレートをテストします

4. 依存関係の値をオーバーライドする：

# values.yaml
postgresql:
  enabled: true
  postgresqlPassword: "secret"
  persistence:
    size: 10Gi

エラー処理の方法

ツールを利用できない場合

• scripts/setup_tools.sh を実行して利用可能か確認します
• インストール手順を提示します
• 省略可能なステージはスキップし、何を省略したかを記録します
• 利用可能なツールを使って続行します

テンプレートのレンダリングエラー

• 該当するテンプレートファイルと行番号を示します
• values.yaml で値が定義されているか確認します
• テンプレート関数の構文を確認します
• より単純な値の組み合わせでテストします
• 詳細なエラーメッセージを表示するには --debug フラグを使用します

クラスターへのアクセスに関する問題

• クライアント側の検証に切り替えます
• レンダリングしたテンプレートを kubectl で使用します
• kubectl の設定がない場合はクラスター検証をスキップします
• 検証レポートに制限事項を記載します

CRD のドキュメントが見つからない場合

• ドキュメントの検索に失敗したことを記載します
• kubeconform の CRD スキーマを使った検証を試みます
• CRD の手動確認を提案します。

  kubectl get crd <crd-name>.group -o yaml
  kubectl explain <kind>
  

検証ステージの失敗

• いずれかのステージが失敗しても、次のステージに進みます
• ユーザーに提示する前にすべてのエラーを収集します
• まず Helm lint エラーの修正を優先します
• 次にテンプレートエラーを修正します
• 最後にスキーマ／検証エラーを修正します

macOS の拡張属性に関する問題

症状： ファイルが存在し、読み取り可能であるにもかかわらず、Helm が「Chart.yaml file is missing」と報告します。

原因： macOS では、プログラムで作成されたファイル（Write ツール、スクリプト、または一部のエディターを使用したもの）に拡張属性（例：com.apple.provenance、com.apple.quarantine）が付与され、Helm のファイル検出に干渉する場合があります。

診断：

# Check for extended attributes
xattr /path/to/chart/Chart.yaml

# If attributes are present, you'll see output like:
# com.apple.provenance
# com.apple.quarantine

解決方法：

1. 拡張属性を削除する：

   # Remove all extended attributes from a file
   xattr -c /path/to/chart/Chart.yaml
   
   # Remove all extended attributes recursively from chart directory
   xattr -cr /path/to/chart/
   

2. 代わりにシェルコマンドを使ってファイルを作成する：

   # Use cat with heredoc instead of direct file writes
   cat > Chart.yaml << 'EOF'
   apiVersion: v2
   name: mychart
   version: 0.1.0
   EOF
   

3. helm で作成した Chart からコピーする：

   # Create a fresh chart and copy structure
   helm create temp-chart
   cp -r temp-chart/* /path/to/your/chart/
   rm -rf temp-chart
   

予防策： macOS で新しい Chart ファイルを作成するときは、helm create をベースとして使用するか、ファイルを直接作成するツールではなく、シェルのヒアドキュメント（cat > file << 'EOF'）を使用してください。

コミュニケーションのガイドライン

検証結果と修正内容を提示するときは、次の点に従ってください。

1. 見つかった内容を明確かつ簡潔に伝えます
2. 問題が重要な理由を説明します（例：「これにより Pod の作成に失敗します」）
3. 関連する場合は、Helm のベストプラクティスに基づく背景情報を提示します
4. 関連する問題をまとめます（例：ヘルパーの不足に関する問題をまとめる）
5. 可能であれば、file:line 形式で参照を示します
6. 自動修正の信頼度を示します（信頼度が高い＝構文の変更、低い＝ロジックの変更）
7. 修正を提案した後（および明示的に依頼されて修正を適用した後）は、必ず次の内容を含む概要を提示します。
   • 変更内容とその理由
   • 各修正のファイルと行番号の参照
   • 解決した問題の合計数
   • 最終的な検証ステータス
   • 残っている警告や推奨事項

バージョンへの配慮

Kubernetes と Helm のバージョン互換性を常に考慮してください。

• 非推奨の Kubernetes API がないか確認します
• Helm Chart の apiVersion が v2（Helm 3 以降）であることを確認します
• CRD については、apiVersion がクラスター内のものと一致することを確認します
• kubectl api-versions を使用して利用可能な API バージョンを一覧表示します
• 利用可能な場合は、バージョン固有のドキュメントを参照します
• 必要に応じて、Chart.yaml に kubeVersion 制約を設定します

チャートのテスト

包括的なテストには、Helm のテストリソースを使用します。

1. テストリソースを作成します：

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "mychart.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
    - name: wget
      image: busybox
      command: ['wget']
      args: ['{{ include "mychart.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

2. テストを実行します：

helm test <release-name>

自動化の機会に関するリファレンス

ステージ 10（最終レポート）では、検出した自動化の機会をすべて概要に記載してください。

ユーザーに質問したり、ファイルを変更したりしないでください。推奨事項を列挙するだけにしてください。

検出して列挙する自動化の機会：

不足している項目	推奨事項
_helpers.tpl	実行：bash scripts/generate_helpers.sh <chart>
.helmignore	assets/.helmignore からコピー
values.schema.json	assets/values.schema.json からコピーしてカスタマイズ
NOTES.txt	インストール後のノート用テンプレートを作成
README.md	チャートのドキュメントを作成
繰り返しパターン	ヘルパー関数に抽出

問題が見つかった場合に含めるセキュリティ上の推奨事項：

問題	推奨事項
Pod の securityContext がない	runAsNonRoot: true、runAsUser: 1000、fsGroup: 2000 を追加
コンテナの securityContext がない	allowPrivilegeEscalation: false、readOnlyRootFilesystem: true、capabilities.drop: [ALL] を追加
リソース制限がない	CPU／メモリの制限とリクエストを追加
:latest タグを使用している	イメージのバージョンを固定
プローブがない	liveness プローブと readiness プローブを追加

テンプレート改善の推奨事項：

問題	推奨事項
include ではなく template を使用している	パイプラインをサポートするため、include に置き換え
nindent がない	YAML のインデントを適切にするため、nindent を追加
デフォルト値がない	オプション値に default 関数を追加
required 関数がない	重要な値に required を追加

リソース

scripts/

setup_tools.sh

• 必要な検証ツール（helm、yamllint、kubeconform、kubectl）があるか確認します
• 不足しているツールのインストール手順を提示します
• インストール済みツールのバージョンを検証します
• 使用方法：bash scripts/setup_tools.sh

validate_chart_structure.sh

• Helm チャートのディレクトリ構造を検証します
• 必須ファイル（Chart.yaml、values.yaml、templates/）を確認します
• ファイル形式と構文を検証します
• 使用方法：bash scripts/validate_chart_structure.sh <chart-directory>

detect_crd_wrapper.sh

• Python の依存関係を管理するラッパースクリプトです
• PyYAML が利用できない場合、一時的な venv を自動作成します
• YAML ファイルを解析するため、detect_crd.py を呼び出します
• 使用方法：bash scripts/detect_crd_wrapper.sh <file.yaml> [file2.yaml ...]

detect_crd.py

• YAML ファイルを解析して、カスタムリソース定義を特定します
• kind、apiVersion、group、version の情報を抽出します
• プログラムで処理できるよう、JSON を出力します
• PyYAML が必要です（ラッパースクリプトが自動的に処理します）
• 直接呼び出すこともできます：python3 scripts/detect_crd.py <file.yaml> [file2.yaml ...]

generate_helpers.sh

• チャート用の標準的な Helm ヘルパー（_helpers.tpl）を生成します
• fullname、ラベル、セレクターのヘルパーを作成します
• 使用方法：bash scripts/generate_helpers.sh <chart-directory>

references/

helm_best_practices.md

• Helm チャートのベストプラクティスに関する包括的なガイドです
• テンプレートパターン、ヘルパー関数、values の構成を扱います
• よくある検証の問題とその修正方法を説明します
• セキュリティとパフォーマンスに関する推奨事項を紹介します
• Helm 固有の問題について背景情報を提供するときに読み込みます

k8s_best_practices.md

• Kubernetes YAML のベストプラクティスに関する包括的なガイドです
• メタデータ、ラベル、リソース制限、セキュリティコンテキストを扱います
• よくある検証の問題とその修正方法を説明します
• Kubernetes 固有の問題について背景情報を提供するときに読み込みます

template_functions.md

• Helm テンプレート関数のリファレンスガイドです
• すべての組み込み関数の例を掲載しています
• Sprig 関数ライブラリのリファレンスです
• カスタム関数のパターンを紹介します
• 複雑なテンプレートを実装するときに読み込みます

assets/

.helmignore

• パッケージ化からファイルを除外するための標準的な .helmignore ファイルです
• 一般的なパターンがあらかじめ設定されています

.yamllint

• Kubernetes の YAML 用に yamllint ルールがあらかじめ設定されています
• Kubernetes の規約（2 スペースのインデント、行の長さなど）に従っています
• プロジェクトごとにカスタマイズできます
• 使用方法：yamllint -c assets/.yamllint <file.yaml>

values.schema.json

• 値の検証に使用する JSON Schema の例です
• 特定のチャート向けにコピーしてカスタマイズできます
• 型安全性と検証機能を提供します