デスティネーション時のシークレット検索順序とドキュメントの明確化

Kamal のシークレットロード機構に関するドキュメントを整理し、デスティネーションを指定した際のファイル探索順序と .kamal/secrets が読み込まれないことを明示しました。これにより、利用者は共通シークレットとデスティネーション固有シークレットを正しく配置できるようになります。

背景

従来の Kamal のドキュメント では、デスティネーションを使用した場合のシークレットファイルの優先順位が曖昧に記述されており、ユーザーは期待通りのファイルが読まれないケースで混乱していました。実際に Issue やサポート問い合わせで、どのファイルが上書きされるか不明という声が上がっていました。この PR はその情報ギャップを埋め、設定ミスによるデプロイ失敗リスクを低減することを目的としています。

技術的な変更

ドキュメント生成スクリプトへのエントリ追加

bin/docs に "output" => "Output" というエントリが新たに加えられ、生成ドキュメントに Output セクションが含まれるようになりました。これにより、output に関する設定ページも自動生成対象に入ります。

@@ -23,6 +23,7 @@ DOCS = {
   "configuration" => "Configuration overview",
   "env" => "Environment variables",
   "logging" => "Logging",
+  "output" => "Output",
   "proxy" => "Proxy",
   "registry" => "Docker Registry",
   "role" => "Roles",

シークレットテンプレートへの注釈追加

lib/kamal/cli/templates/secrets に、デスティネーション別シークレット配置例と .kamal/secrets の使用条件を説明するコメントが追記されました。このコメントはテンプレートユーザーに対し、共通シークレットは .kamal/secrets-common、デスティネーション固有は .kamal/secrets.<destination> に置くべきことを明示します。

@@ -1,6 +1,10 @@
 # Secrets defined here are available for reference under registry/password, env/secret, builder/secrets,
 # and accessories/*/env/secret in config/deploy.yml. All secrets should be pulled from either
 # password manager, ENV, or a file. DO NOT ENTER RAW CREDENTIALS HERE! This file needs to be safe for git.
+#
+# When deploying with destinations, shared secrets can go in .kamal/secrets-common and
+# destination‑specific secrets in .kamal/secrets.<destination>. This .kamal/secrets file is used
+# only when no destination is selected.

 # Option 1: Read secrets from the environment
 # KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

設定コメントの拡充（configuration.yml）

lib/kamal/configuration/docs/configuration.yml では、secrets_path の探索ロジックを詳細に記述しました。まず <secrets_path>-common を探し、次に通常の <secrets_path>、デスティネーション指定時は <secrets_path>.<destination> を参照し、後に読まれたファイルが前の値を上書きする旨が明記されています。

@@ -108,7 +108,9 @@ hooks_output:
 # Secrets path
 #
 # Path to secrets, defaults to `.kamal/secrets`.
-# Kamal will look for `<secrets_path>-common` and `<secrets_path>` (or `<secrets_path>.<destination>` when using destinations):
+# Kamal looks for `<secrets_path>-common` first and then `<secrets_path>`.
+# When using destinations, it instead looks for `<secrets_path>-common` first and then
+# `<secrets_path>.<destination>`. Later files override earlier ones.
 secrets_path: /user_home/kamal/secrets

設定コメントの拡充（env.yml）

lib/kamal/configuration/docs/env.yml でも同様に、dotenv が読み込む対象ファイルの順序を明示しました。.kamal/secrets-common が最初に読み込まれ、次に .kamal/secrets、デスティネーションが選択されている場合は .kamal/secrets.<destination> が続き、.kamal/secrets は除外されます。

@@ -14,12 +14,14 @@ env:

 # Secrets
 #
-# Kamal uses dotenv to automatically load environment variables set in the `.kamal/secrets` file.
+# Kamal uses dotenv to automatically load environment variables from the configured secrets files.
 #
-# If you are using destinations, secrets will instead be read from `.kamal/secrets.<DESTINATION>` if
-# it exists.
+# Common secrets across all destinations can be set in `.kamal/secrets-common`. Kamal looks for
+# `.kamal/secrets-common` first, then `.kamal/secrets`, with later values overriding earlier ones.
 #
-# Common secrets across all destinations can be set in `.kamal/secrets-common`.
+# If you are using destinations, Kamal looks for `.kamal/secrets-common` first, then
+# `.kamal/secrets.<destination>`. The non‑destination `.kamal/secrets` file is not read when a
+# destination is selected.
 #
 # This file can be used to set variables like `KAMAL_REGISTRY_PASSWORD` or database passwords.
 # You can use variable or command substitution in the secrets file.

設計判断

本 PR は コードロジック自体を変更せず、ドキュメントとテンプレートにコメントを追記することで、利用者への情報提供を強化しました。検索順序は既存実装と合致しているため、後方互換性はそのまま維持されます。また、bin/docs に output エントリを追加したことで、全ての設定ドキュメントが生成対象になり、一貫したドキュメント体制が構築されました。これらの変更はユーザー体験の向上と設定ミス防止を目的とした、最小侵襲な設計判断と言えます。

まとめ

この PR は、デスティネーション利用時のシークレット検索順序を明示したコメント追加と、ドキュメント生成対象の拡充という二本柱の改善を行いました。実装上の挙動はそのままに、利用者が正しいファイル配置を把握できるようになり、設定エラーのリスクが低減します。