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

git リポジトリに置かれたチャート

Helm チャートはチャートレジストリから取得する必要はありません。この例では、git リポジトリにあるチャート(Helm プロジェクト自身の hello-world サンプルチャート)を取得し、Kubernetes マニフェストにビルドします。

開発者の Aggregate はこれについて何も述べません。宣言するのは 1 つの core/compute/server だけで、そのサーバーのパッケージングをどこから取得するかは Recipe で決まり、Manifest によって束縛されます。

source ブロック

catalog/recipe/helm/hello-world-git/1.0.0/recipe.yaml
source:
kind: git-repository
url: https://github.com/helm/examples.git
ref: hello-world-0.1.0
module_subdir: charts/hello-world

3 つの座標があり、それぞれが異なる問いに答えます。

  • url — クローンするリポジトリです。https://、ssh://、git:// のいずれも受け付けます。プライベートリポジトリには、SSH エージェントを介して SSH で、または netrc ファイルにそのホストのエントリ(machine github.com login <user> password <token>)を置いて HTTPS で到達します。URL 自体に書き込まれた認証情報は、認証 で説明しているとおり拒否されます。
  • ref — リポジトリを読み取る参照で、タグ、ブランチ、またはコミットです。 リポジトリの作者が付けた名前そのものであり、常に単なるバージョンとは限りません。 ここでは、タグにチャート名も含まれています。
  • module_subdir — リポジトリ内でチャートとなるディレクトリです。 このリポジトリはそれ自体がチャートなのではなく、このパスの下にチャートを保持しています。 また、ディレクトリはアーティファクトを区別する要素の一部です。1 つのリポジトリの同じコミットにある 2 つのディレクトリは、1 つではなく 2 つのアーティファクトです。

source の種類が示すのは転送方式と場所であり、形式ではありません。 同じ種類で、チャートも Terraform モジュールも、その他任意のファイルのディレクトリも取得できます。 ディレクトリに何が入っているかは、それを利用する provider が扱う事柄です。

ロックファイルに記録される内容

変更されることのない内容を指すのはコミットだけです。タグやブランチは、リポジトリが別のコミットに付け替えられる名前です。 そのため aggrega pull は参照を解決し、記述した参照と、それが解決されたコミットの両方を記録します。

# release-chart.lock
source_artifacts:
- kind: git-repository
url: https://github.com/helm/examples.git
module_subdir: charts/hello-world
pinned_version: f3dc419e558e6ccebce2ed447384e5d2e11de2f9
digest: sha256:2bee62cfc2efccc61d8e17efeb72f9f77ad7bd87f3ea4e50b1e4219c8d5a2c78
mediatype: application/gzip
referenced_by:
- entity: recipe
uri: helm/hello-world-git:1.0.0
field: spec.source
requested_ref: hello-world-0.1.0

どちらにも役割があります。コミットはビルドが取得するものであり、これによってビルドが再現可能になります。 参照はビルドがエントリを検索するためのキーです。これにより、Recipe に ref: hello-world-0.1.0 と書き続けたまま、 ロックファイルが書かれた時点でそのタグが指していたコミットへ正確に解決できます。

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example chart-from-git-repository

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd chart-from-git-repository

ビルド

Terminal window
aggrega build --release release-chart.yaml --auto-pull

この例には 2 つの release があるため、ビルドする release を指定します。最初のビルドには ロックファイルが必要なので、ここでは --auto-pull を渡しています。事前に aggrega pull --release release-chart.yaml を一度実行しても同じ効果があり、 以降のビルドはフラグなしで実行できます。

レンダリングされた Deployment には、Release が与えた値が、チャート自身の値名にマッピングされて含まれます。

dist/app/helm/web-deployment-web-hello-world.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: web-hello-world
[… omitted: the chart's own labels, and the labels and annotations every rendered document carries]
spec:
replicas: 2
[… omitted: the selector and the pod template's own labels]
spec:
serviceAccountName: web-hello-world
securityContext: {}
containers:
- name: hello-world
securityContext: {}
image: "nginx:1.27.3"
imagePullPolicy: IfNotPresent
[… omitted: the container port and the two probes]

ビルドのたびに警告が 1 つ出力されます。

warning: node "web": .infra key "compute" is read by no template in recipe "hello-world-git" — correct the spelling, or remove the key

この警告は正確であり、抑制するよりも読む価値があります。core/compute/server Component は CPU とメモリのサイズ調整項目を提供していますが、このチャートにはそれに対応する値がないため、 Recipe はそこに何もマッピングしていません。ソースを取得する Recipe は、取得したチャートが実際に受け付けるものをマッピングします。 コンパイラは、値が反映されたかのように装うのではなく、どこにも届かなかった値を報告します。

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `chart-from-git-repository` フォルダーがない場合は、`example` を `chart-from-git-repository` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `chart-from-git-repository` フォルダーに書き出されます。次に、`workspace_root` を `chart-from-git-repository`、`release` を `release-chart.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き出したファイルを教えてください。ファイルは `chart-from-git-repository/dist/` の下にあります。

参照が移動したとき

タグはリポジトリ側で付け替えられることがあります。その場合、次の通常の aggrega pull は、参照が記録済みのコミットとは別の場所に解決されることを検出し、それを採用せずに停止します。

# aggrega pull --release release-chart.yaml
#
# [E0130]
# lockfile: out of date; it no longer matches what its Release resolves to
# ---
# source-artifact kind=git-repository url=https://github.com/helm/examples.git
# module_subdir=charts/hello-world: reference "hello-world-0.1.0" moved — the
# lockfile pins 03f4a18d3c2b77b7ecd91d0324a95910d4f04152, and it now resolves to
# f3dc419e558e6ccebce2ed447384e5d2e11de2f9; adopt where it now points with
# `aggrega pull --upgrade --release <release>`

両方のコミットが示されるため、判断する前に何が移動したのかを正確に確認できます。 ロックファイルは元のまま残り(停止は何かが書き込まれる前に起こります)、新しいコミットの採用は意図的な操作として行います。

Terminal window
aggrega pull --upgrade --pin-sources --release release-chart.yaml

参照の移動は --upgrade が想定するケースです。通常の pull はロックファイルに記録されたコミットを保持し、 参照が現在指す場所を採用するのはアップグレードだけです。単独の --upgrade は記録済みのピンをすべて破棄するため、 最初に確認を求めます。--pin-sources も必要です。この Recipe は、隣にある entity.lock にもソースのコミットを記録しているためです。 アップグレードはそのピンを新しいコミットに書き換えますが、このフラグがない場合、pull はロックで停止し、 aggrega pin を案内します。書き換えられた entity.lock は Recipe と一緒にコミットしてください。

このワークスペースで行った編集(たとえば Aggregate や Release の編集)は、別の種類のドリフトです。 次のビルドがそれを報告し、通常の aggrega pull --release release-chart.yaml で解消されます。

タグの代わりに ref: でコミットを固定することでも同じ保証が得られますが、その代償として座標は人間には読めなくなります。

ガードレール用の release

release-negative.yaml は失敗することが想定されています。取得の経路を正常系でしか試さなければ、そのガードについては何もわからないため、 ここに置かれています。これは同じ Aggregate を manifest-negative.yaml を通じてデプロイします。この Manifest が束縛する Recipe は、 参照を除いて正常に動作するものと同一で、リポジトリに存在しないタグを指定しています。

Terminal window
aggrega build --release release-negative.yaml --auto-pull
# exits non-zero
# [E0137]
# auto-pull: resolving the source of each Recipe and FeatureRecipe the Release
# uses: resolve: resolve source for recipe
# "helm/hello-world-git-missing-ref:1.0.0": sourceresolver: kind=git-repository
# url=https://github.com/helm/examples.git version=: oci: artifact not found at
# remote source (cause: reference not found)
[… omitted: the rest of that line, a remediation naming the URL and version to check]

リポジトリには到達でき、クローンも成功します。単にその参照がリポジトリ内に存在しないため、 ピン留めするコミットもアーカイブするものもありません。

この例がネットワークに必要とするもの

ここにある大半のワークスペースとは異なり、このワークスペースは最初のビルドで実際のリポジトリをクローンします。 そのため、そのビルドには url に指定されたホストへの外向きのアクセスが必要です。ロックファイルと解決キャッシュが作成されると、 以降のビルドはキャッシュから読み取り、ネットワークなしで実行されます。aggrega build --release release-chart.yaml --offline で同じバイト列が再ビルドされます。