コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

インポートの回答ファイル

どのソースにも保持できない値があります。自分のコードからビルドしたアプリケーションのイメージ、オーナーアカウントのメールアドレス、ソースが名前を挙げていないモデル、Kubernetes Secret の名前などです。aggrega import はそのような値をそれぞれ空文字列として下書きし、それが何であるかを示すコメントをその上に付け、回答ファイルから、またはターミナルでの質問によって、一度だけ受け取ります。回答は回答ファイル import-answers.yaml に保存されるため、同じソースの以降のインポートはすべてそこから読み取り、何も質問しません。

このページでは、ファイルの場所、その内容、値がどのように書き込まれるか、そして値がまだ欠けているときにインポートが何をするかを説明します。インポートの目的と、ソースからビルドまでのウォークスルーは、インポートにあります。

未提供となる値

下書きの後、インポートは下書きした各ドキュメントを、そのドキュメント自身のスキーマと、ドキュメントが宣言する各 Component、Feature、接続のカタログスキーマに照らして読み取ります。値は、そのスキーマが値を必須とする箇所でまだ空である場合、またはスキーマがキーを宣言しているのに何もそれを与えていない場合に、未提供となります。未提供の各値は、スキーマ自身によるそのキーの説明で記述されます。スキーマに説明がない場合は、下書きがキーの上に書くコメントで記述されます。

未提供の値がある間、インポートは下書きした Release の依存関係を取得しません。すべての値に回答が得られた時点で取得します(再実行と --sync を参照)。

ファイルの場所

ソースが次の場合回答ファイルの場所
ファイルソースファイルと同じディレクトリにある import-answers.yaml
ディレクトリソースディレクトリ内の import-answers.yaml

--answers <file> は別のファイルを指定します。相対パスは、コマンドを実行するディレクトリを基準に解決されます。ドラフトに未回答の値があり、回答ファイルがソースの隣にあるデフォルトのものでない場合、インポートがドラフトの隣に書き込む記録 .aggrega-import.json にそのファイルが記されるため、同じディレクトリへの後続の aggrega import --sync は、改めて指定しなくてもそのファイルを読み込みます。この記録に回答が含まれることはありません。

シークレットの回答は、シークレットの取得元の名前であり、シークレットそのものでは決してありません(シークレットを参照)。そのため、回答ファイルはソースと一緒にバージョン管理で保持できます。

内容

このファイルは YAML です。トップレベルのキーはドラフトされたファイルで、それぞれがドラフトされるパスで示されます。その下では、キーはそのドキュメント内の未回答の値のドット区切りのキーパスであり、その値が回答です。スキーマによるキーの説明は、キーの上にコメントとして書き込まれます。空のキーパスセグメント、またはピリオド、空白、引用符を含むキーパスセグメントは、二重引用符で囲んで書き込まれます。この形として読めないファイルは、そのファイルと理由を示してインポートを停止させ、何も書き込まれません。

たとえば、--target helm でドラフトした Google ADK のインポートでは、その Release に未回答の値が 2 つあります。プロジェクトからビルドするエージェントのイメージと、エージェントの Gemini API キーの取得元です。両方に回答すると、ソースディレクトリ support_agent/ 内の回答ファイルは次のようになります:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# Container image running the application built on ADK, serving its API on infra.port on every
# interface.
spec.components.support-agent.infra.image: "ghcr.io/example/support-agent:1.0.0"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.support-agent.uses.model.gemini-2-5-flash.features.credential.infra.origin: "google-api-key"

どちらの回答も利用者自身が決めるものです。ghcr.io/example/support-agent:1.0.0 はビルドしてプッシュするイメージを、google-api-key はデプロイ先の名前空間でキーを保持する Kubernetes Secret の名前を表します。

各回答は 1 つの値であり、インポートはそれを空の値の代わりに文字列としてドラフトに書き込み、ドラフト内のそれ以外は何も変更しません。ドラフトされた Aggregate に書き込まれた回答は、{{ も含め、入力したとおりに読み戻されます。空の回答では、その値は未回答のままになります。

値の入力方法

インポートは、まず回答ファイルから各未回答の値に回答します。ファイルで回答されていない値については、1 つずつ質問します — ただし、標準入力と標準出力の両方がターミナルであり、--dry-run が指定されていない場合に限ります:

  • 各質問はドラフトされたファイルとキーパスを示し、スキーマの説明に基づいて表現されます。
  • 質問は標準エラーに書き込まれるため、標準出力にはインポートの結果だけが出力されます。
  • Enter キーを押すとその値は後回しになり、入力を終了すると質問が止まります。

入力した各回答はドラフトと回答ファイルに書き込まれ、回答ファイルは書き込まれたファイルの中に示されます。回答ファイルに何も変更がない実行では、回答ファイルは再度書き込まれません。

シークレット

シークレットの値 — スキーマで機密としてマークされている値 — には、シークレットそのものではなく、シークレットの取得元を回答します。その質問はこれを尋ね、回答は次のいずれかの名前です:

回答例
変数名OPENAI_API_KEY
変数への参照${OPENAI_API_KEY}
Kubernetes Secret の名前openai-api-key

インポートは、回答がこれらの名前のいずれかの形式であることを確認し、それ以外はすべて拒否します:

  • ターミナルでは、回答が拒否され、理由が表示され、質問が再度行われます;
  • 回答ファイルでは、インポートは停止し、回答ファイル、ドラフトされたファイル、キーを示します — 回答そのものはシークレット自体である可能性があるため、決して示しません — そして何も書き込みません。

このチェックは回答の形式を読み取るため、たまたま名前のように見えるシークレットは名前と区別されません。シークレットそのものは、名前が指す場所、つまり変数または Secret にとどまります。

ターミナルがない場合

継続的インテグレーション、パイプ経由、アシスタントのインポートツール(aggrega mcp)からは何も質問されず、エディタのインポートも実行中は何も質問しません。回答ファイルを読み込んだ後も未設定の値が残るインポートは、次のように動作します:

  • 未設定の各値を空のままにしてドラフトを書き込みます;
  • 未設定の各キーを含み、その回答を空にした回答ファイルを書き込みます;
  • 未設定の各値を、ドラフトされたファイル、キーパス、その説明を示す警告として標準エラーに出力します;
  • ドラフトされた Release の依存関係をプルしません;
  • ステータス 1 で終了し、未設定の値がいくつあり、どこに書けばよいかを示す一文を出力します:
2 values the drafts leave empty are still owed, listed in the answers file <path>/support_agent/import-answers.yaml: write each beside its key there, then run the import again

各回答をそのキーの横に書き、同じディレクトリに対して aggrega import <source> --sync を実行します。このコマンドは、前回のインポートに指定されたターゲット向けにドラフトを作成し、各回答をドラフトに書き込み、何も質問しません。ドラフトされた Aggregate がすでに含まれているディレクトリへの通常の aggrega import は、--sync を示して停止し、何も書き込みません。新しい出力ディレクトリへのインポートも回答ファイルを読み込みます。既定のもの、または --answers で指定したものです。

アシスタントのインポートツールは、回答ファイルを answers として受け取り、ワークスペースのルートからの相対パスまたは絶対パスで指定します。未設定の値が残る呼び出しはその一文で失敗し、警告を含むインポートの結果をその横に返します。エディターのインポートも回答ファイルを受け取り、同じ一文がその診断を締めくくります。

どちらも、まだ必要な各値をデータとして owed の下に一覧表示します。ドラフトされたファイル、キーのリストとしてのキーパス、質問、その値がシークレットのものかどうか、そしてシークレットの場合はその回答が何でなければならないか(エディターからは secretAdvice、アシスタントのインポートツールからは secret_advice)です。各回答を answered の下に、ドラフトされたファイル、キーパス、回答とともに sync を付けて返すと、インポートはそれを検査し、回答ファイルに保持し、ドラフトに書き込みます。ターミナルで入力された回答と同じ扱いです。シークレットの回答が名前でない場合は、保持も書き込みもされません。その値は owed に残り、助言の代わりに理由が示されます。

ドラフトを書き込むインポートの後、エディタはまだ必要な各値をそれぞれ専用の入力ボックスで尋ねることを提案し、この方法で回答を送り返します。プレビューの後は、--dry-run では何も尋ねられないため、何も提案しません。質問についてはインポートがまだ必要とする値への回答で説明しています。

--dry-run の下では、何も質問されず、回答ファイルを含め何も書き込まれません。未設定の各値は引き続き標準エラーに示され、終了ステータスはドライラン自体のものになります。

再実行と --sync

aggrega import --sync は、前回のインポートと同じ回答ファイルを読み込みます。--answers で指定されたもの、なければドラフトの横にある記録が示すもの、それもなければソースの横にある既定のものです。各回答を空の値の代わりにドラフトに書き込み、回答ファイルがすべての未設定の値に答えている場合は何も質問しません。

未設定の値がなくなり、ワークスペースがオフラインでなければ、インポートは aggrega pull と同様にドラフトされた Release の依存関係をプルして release.lock を書き込むため、aggrega validate と aggrega build はすぐにドラフトに対して動作します。--offline の下では何もプルされず、インポートは次に実行すべき aggrega pull --release <path> を示します。

複数のターゲットに 1 つの回答ファイル

同じソースでも、異なるターゲット向けにドラフトすると必要な値が異なることがあります。上記の Google ADK の Release は、--target compose でドラフトするとイメージだけが必要ですが、同じ Release を --target helm でドラフトすると、エージェントの Gemini API キーの取得元も必要になります。1 つの回答ファイルで両方に対応できます:

  • インポートは、ドラフトに必要なキーを追加し、与えられた回答を設定します;
  • これらのドラフトに不要なキーへの回答はファイルに保持されますが適用されません;
  • ファイル内のその他のキーとコメントはすべてそのまま残ります。

回答ファイルは、ドラフトに何らかの値が必要な場合にのみ読み込まれます。その場合、標準エラーの情報行が、保持されて適用されなかった各回答を示します。ここでは --target compose でドラフトされた Flowise のインポート の例です。これは所有者のメールアドレスだけを必要とし、同じインポートが --target helm で必要とする 2 つの Kubernetes Secret も指定している回答ファイルを読み込みます。

info: the answers file <path>/import-answers.yaml also answers spec.components.flowise.features.owner_password.infra.origin in release.yaml, spec.components.flowise.uses.model.chatopenai-0.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not applied

ドラフトに必要な値が何もない場合、たとえばすべてのシークレットを変数から読み込む、--target compose でドラフトされた Langflow のインポート の場合、回答ファイルは読み込まれず、そのような行は出力されず、ファイルはそのまま残ります。

関連項目

  • aggrega import — コマンドのリファレンス。すべてのフラグを含みます。
  • インポート — インポートが何をドラフトするか、および各ソース形式のウォークスルー。