実行可能なサンプル
まずははじめにで Aggrega をインストールし、これらのサンプルのうち 2 つを一歩ずつたどります。
aggrega CLI でコンパイルできる、完結したフォーク可能なワークスペースです。それぞれが自己完結したディレクトリ(Developer が作成した Aggregate と、1 つ以上の Release/Manifest のペア)であり、各ページに記載されたもの以外のセットアップなしでビルドできます。デプロイする製品や示す内容から例を探すには、ここにあるすべての例を一覧にした製品と機能別の例を使ってください。
サンプルには 2 つのモードがあり、1 つのカリキュラムの両端にあたります。
-
利用 — ワークスペースは標準ライブラリのカタログエンティティを参照し、 学習用の固有コンテンツのみをローカルで作成します。
--catalogフラグなしでビルドできます。Terminal window aggrega build --release release.yaml参照されるエンティティの読み込み元はワークスペースによって異なります。ワークスペースのルートにある
catalog/ディレクトリは、何かがそれを指定しているかどうかにかかわらず読み込まれるため、独自の学習用コンテンツを作成するワークスペースは、それをそこに置くだけで済みます。.aggrega-config.yamlを持つワークスペースは、catalog_dirsに列挙されたすべてのディレクトリも読み込みます。いずれも、エンティティを置いているディレクトリです。列挙されたディレクトリが先に検索され、catalog/は最後に検索されます。このスタックは先勝ちであるため、先に検索されるディレクトリのエンティティは、後のディレクトリにある同じ識別子のエンティティを隠します。どのローカルディレクトリも宣言していないもの、つまり標準ライブラリのエンティティは、設定がdefault_registryとして指定するレジストリhub.aggrega.aiから解決されます。ローカルで何も作成しないワークスペースにはローカルのエントリは不要であり、catalog/ディレクトリも.aggrega-config.yamlも持たないワークスペースは、すべてを設定済みのレジストリを通じて解決します。catalog_dirsを空のリストとして記述すると、ワークスペースにローカルカタログがまったくないことを示します。catalog_dirsのすべてのパスはワークスペース内のディレクトリを指すため、ワークスペース全体を別の場所にコピーしても、そのままビルドできます。ターゲットごとに別々のカタログを保持するマルチターゲットのワークスペースは、各ターゲットのディレクトリを
workspace.releasesの下に Release ファイルをキーとして記述し、すべての Release がそれぞれ自身のカタログに対してビルドされるようにします。 -
作成 — ワークスペースはカタログエンティティ(Components、 Features、Recipes)をローカルの
catalog-*/ディレクトリでゼロから構築します。mariadb-adminerが作成の実例であり、そこで構築されるエンティティは、 利用のサンプルが利用するものと同じ種類です。
1 回の実行につき 1 つの release を aggrega build --release <release file> でビルドします。各例のページには、その例のコマンドが示されています。ワークスペースは上で説明したとおりにカタログを提供します。ワークスペースが指定していないカタログディレクトリには自分で --catalog を渡してください。必要なページにはその方法が示されています。
ロックファイルは同梱されず生成されるため、クローン直後には存在せず、最初のビルドで必要になります。aggrega build はデフォルトで読み取り専用です。ロックファイルがない場合は停止し、2 つの対処方法を示します。最初のビルドでは --auto-pull を渡すと(aggrega build --release release.yaml --auto-pull)、ビルド中にロックファイルが解決されます。事前に aggrega pull --release <release file> を一度実行しても同じ結果になり、以降のビルドはすべてフラグなしで実行できます。
ドキュメントリポジトリのチェックアウトでは、ほとんどのワークスペースに build-release.sh ヘルパーも含まれており、リポジトリ自身のチェックはこれを通じてビルドします。このヘルパーは 1 つのリリースについて aggrega build を実行し、先にそのコマンドを表示して、使用した aggrega バイナリとその入手元を報告します。バイナリを選ぶには AGGREGA_BIN を設定します。aggrega scaffold --example が書き出したコピーにはヘルパーが含まれますが、ヘルパーが呼び出す共有スクリプトは含まれないため、そのようなコピーは aggrega build で直接ビルドしてください。
ここにある例が標準ライブラリのカタログのチェックアウトに言及している場合、その入手先はインポートに記載されています。
これらは Examples Overview で説明しているコンセプトページを補完するものです。コンセプトページは 1 つの考え方を説明し、それを示すワークスペースにリンクします。ここにあるワークスペースは、ビルド、読解、応用ができる完全なスタックです。
ページにビルドの生成物が表示されている箇所では、そのブロックは実際の実行からコピーされているため、 自分の出力と比較できます。省略された行には印が付けられています。 これらのページの出力の読み方で、その慣例と使用される印を説明しています。
ここにあるすべてのディレクトリが 1 つのワークスペースであるわけではありません。クイックスタートの例はステップごとに 1 つのワークスペースを持ち、インポートの例は次の段落で説明するように、インポートの段階ごとに 1 つのワークスペースを持ちます。1 つのディレクトリはワークスペースをまったく含みません。policy-in-ci には、ビルドの出力ディレクトリを読み取り、ルールに違反する場合はそれを拒否する 2 つのルールスクリプトが、それぞれのパイプラインステップとともに含まれています。これらはここにあるワークスペースの出力や、独自の出力に対して実行されます。
各 import-* の例(製品と機能別の例の import 機能の下に掲載)は、別の形式で書かれたプロジェクトを aggrega import が受け取るままの形で、2 つのフォルダーに保持しています。source/ はプロジェクト、それをワークスペースにする .aggrega-config.yaml、そしてどのソースにも記述できない値をインポートが読み込む回答ファイルです。draft/ はインポートが書き出したファイルを変更せずに収めたもので、書かれたままでビルドできるワークスペースであり、標準出力(stdout.txt)と標準エラー(import.txt)に出力された内容も含みます。インポートにあるそのウォークスルーで各段階を説明しています。その check.sh はこのリポジトリの共有スクリプト scripts/check-import-example.sh を実行します。このスクリプトは再度インポートを行い、書き出した内容と出力した内容を draft/ と、ウォークスルーが引用するブロックを例のファイルと比較し、そのうえで下書きされた Release を検証してビルドします。
学習の順序
ここにあるすべての例は、ヘッダーの tier と position によって与えられる単一の学習順序の中に 1 つの位置を持ちます。ティアの一覧 が示す順にティアごとに並び、各ティア内では最も簡単なものが先に来ます。学習順 ではすべての例をこの順に一覧しており、サイドバーの例のセクションも同じ順序に従います。ティアを上から順に読むことも、作業内容に合ったティアに直接移ることもできます。代わりにデプロイするものや示す内容から例を探す場合は、同じページに製品別と機能別の一覧があります。
ビルドは、レンダリングしたものに対してプラグインを実行することもできます — パイプラインステップを使うべき場合を参照してください。
各例のヘッダー
各例の README は、YAML フロントマターとして書かれた短いヘッダーで始まり、その例が何であるか、つまりレベル、学習順序における位置、デプロイする製品、示す内容を記します。製品と機能別の例は、これらのヘッダーから生成されます。
---example: level: start tier: catalog-only position: 1 products: [core/datastore/mariadb, core/devtool/adminer] shows: [connections, credentials]---level は次のいずれかのレベルです。
start— 「カタログのみ」レベル: カタログエンティティから組み立てられ、Aggregate、Manifest、Release 以外は何も作成しません。authoring— 「作成」レベル: Component、Feature、Recipe のいずれかを作成するか、その形を示します。advanced— 「上級」レベル: boundary、ガバナンスポリシー、アノテーション駆動の Features、組み立てられたクラウドスタック。
tier は、その例が属する学習順序の区分で、次のいずれかの段階です。段階はこの順序で学びます。
start-here— ここから始める:「はじめに」ガイドが 1 ステップずつ発展させる 2 つの例と、その後に続くクラウド向けの 2 つの入門例です。catalog-only— カタログのみ:カタログエンティティから組み立てられ、Aggregate、Manifest、Release 以外は何も記述しません。authoring— オーサリング:独自の Component、Feature、Recipe を記述するか、その構成方法を示します。advanced— 上級:境界、ガバナンスポリシー、アノテーション駆動の Features、組み立てられたクラウドスタックを扱い、その複数を 1 つのビルドで組み合わせます。importers— インポーター:別の形式で書かれたプロジェクトをaggrega importで Aggrega ファイルに下書きし、レビューしたうえでビルドします。
position は段階内での例の位置で、その段階の他のどの例も使っていない正の整数です。段階は例を位置の小さいものから順に、最も簡単なものから並べます。
products は、例がデプロイする各カタログ Component を、そのカタログエントリが持つ名前で列挙します。汎用のコンピュートコンポーネント(たとえば core/compute/server)や、例が自身のために宣言したエンティティは列挙されないため、何も列挙しない例もあり得ます。
shows は例が示す内容を列挙し、各エントリは次のリストから取ります。
multi-target— 2 つ以上のターゲット向けにビルドされる、または 2 通り以上に実現される 1 つの Aggregate。recipe-selection— どの Recipe がコンポーネントを実現するか、またはどの FeatureRecipe がアタッチメントを実現するかを Manifest が選ぶこと。タイプごと、インスタンスごと、またはターゲットごと。modules— モジュールとしてインポートされるカタログの Aggregate。connections—usesソケットで接続され、各エッジを越えて値が受け渡されるコンポーネント。credentials— 認証情報のアタッチメントと、各ターゲットがそれをどう配信するか。parameters— パラメータに巻き上げられ、Release が充足する値。features— ルーティング、モニタリング、予算、キャッシュ、マスキングなど、認証情報以外の目的でアタッチされる Features。boundaries— boundary に配置されたコンポーネントやモジュールと、その間を越えるもの。policy— ビルド中に、またはその出力に対して、ビルドを受け入れるか拒否するガバナンスポリシー。guardrails— 停止することを意図した Release と、停止時のメッセージ。catalog-authoring— 例のために書かれ、例の隣に置かれるかカタログに公開される Component、Feature、または Recipe。cloud-infrastructure— マネージドクラウドサービス向けの Terraform または CloudFormation の出力。external-sources— レンダリングするものを取得する Recipe。上流のチャート、git リポジトリ、またはモジュール。import— 別の形式で書かれたプロジェクトを、aggrega importで Aggrega ファイルに下書きし、その後レビューしてビルドします。
例は、インデックスが配置できるように、少なくとも 1 つの製品または 1 つの機能を列挙します。その README には ## Scaffold the example セクションもあり、その最初のコマンドブロックには aggrega scaffold --example <name> が、2 番目のコマンドブロックには cd <name> が書かれ、その直後に ## Build セクションが続きます。このセクションの最初のコマンドブロックは、aggrega scaffold --example がその cd の次に実行するものとして出力する内容です。このリポジトリのルートから実行する scripts/gen-examples-index.sh --check は、すべてのヘッダーをこれらのリストと照合し、どちらかのセクションが欠けている例と、実行可能な check.sh も build-release.sh も持たない例を拒否し、インデックスが最新であることを確認します。インデックスを書き直すには --check なしで実行してください。