Harbor スタック — 1 つの release としてデプロイされるコンテナレジストリ
この例では、Developer が作成した 1 つの Aggregate から、実際のコンテナレジストリを Kubernetes マニフェストにコンパイルします。
コンテナレジストリは、多数のサービスが連携して動作するものです。API とトークンサービスからなるコントロールプレーン、OCI blob ストアとそのコントローラ、Web コンソール、非同期ワーカー層、脆弱性スキャナ、リレーショナルバックエンド、キーバリューキャッシュ、そしてそれらの前段に置かれるリバースプロキシがあります。カタログはこれらすべてを 1 つの Component として記述します。レジストリのメンテナー自身が、全体を 1 つの release として、各サービスが必要とする順序でデプロイする Helm チャートを公開しているためです。Component はレジストリを宣言し、Recipe はそのチャートをラップします。
レジストリはモジュールとしてインポートされます。モジュールとは、Component を構成し、その公開アドレスをエクスポートする再利用可能なサブアグリゲートです。トップレベルの Aggregate はモジュールを名前でインポートし、レジストリのキーのうち 3 つを渡します。オペレーターは Release の中でモジュールのコンポーネントのサイズを指定します。
ファイル
| ファイル | 役割 |
|---|---|
aggregate.yaml | 開発者の意図:コンテナレジストリのモジュール(core/harbor)をインポートし、自身のパラメータからレジストリのキーのうち 3 つを渡します。 |
manifest-helm-synth.yaml | レジストリのコンポーネントタイプを、その Helm チャートをラップする Recipe にマッピングし、資格情報の Feature を、名前空間にすでに存在する Secret を読み取る実現にマッピングします。ただし管理者のパスワードは例外で、これは名前によって、モジュールのパラメータから Secret を出力する実現にバインドします。 |
release-helm-synth.yaml | Kubernetes ターゲット向けのオペレーターのレコードです。Aggregate が渡す 3 つのキーを保持する Secrets を指定し、モジュールのコンポーネントをモジュールスコープの ID によってサイジングし、トークン署名キー、サービス間の共有シークレット、保存される資格情報の暗号化に使うキーを、それらを保持する Secrets を指定することでそのコンポーネントにアタッチします。それ以外はスキーマのデフォルトに任せます。 |
示す内容
- 複数サービスからなる製品を 1 つの Component として扱う。 このレジストリを複数ではなく 1 つの Component にしているのは、その規模ではなく、配線がどこで保守されているかです。リバースプロキシのルーティング、コントロールプレーンがすべての pull と push を照合するトークンサービスの鍵、各サービスがバックエンドとキャッシュ用に読み込む接続設定、サービスごとのキャッシュキー空間を分離する論理データベースの分割、そして起動順序。これらはすべて、製品を出荷する人々によってチャートの中で製品と歩調を合わせて保たれています。利用者はレジストリを宣言するだけで、それらが整合した状態を得られます。
- ラップされたチャート。 Recipe は
source:でチャートを指定し、その上にvaluesMapping:を重ねます。values テンプレートが実装のすべてであり、Helm プロバイダーはチャート自身のテンプレートをそれに対してレンダリングします。ここではワークロードは合成されません。 - 固定された外部入力。 チャートはビルドが取得する入力であるため、他の依存関係と同様に固定されます。ロックファイルは
source_artifactsの下に、チャートのバージョン、解決された URL、tarball のダイジェストを記録します。ロックファイルが埋まった状態でのビルドは、コンテンツストアからチャートを提供し、そのダイジェストに対して検証します。 - プラットフォーム全体に対して公開されるアドレスは 1 つ。 チャートのリバースプロキシは、
ブラウザ用パス
/をコンソールへ、レジストリと API のパス (/v2/、/api/、/service/、/c/) をコントロールプレーンへルーティングします。そのため、コンテナクライアントは、ブラウザがコンソールにアクセスするのと同じホストに対してログイン、push、pull を行います。その Service がprovides.hostが公開するものであり、利用者はどちらのパス群に到達するにも 2 つ目のアドレスを必要としません。 - それに対する 2 つの公開名。 モジュールはその 1 つのアドレスを、イメージクライアントと API が通信するエンドポイントとして
registryの名前で、 Web エンドポイントとしてuiの名前でエクスポートします。 どちらも両方のパス群を提供するアドレスに解決されるため、利用者は自らの意図を表す方の名前に配線します。 - モジュールのコンポーネントに対するオペレーターによるサイジング。 Release はモジュールのコンポーネントをモジュールスコープの ID (
harbor.registry) で指定してコンピュートを設定するため、 開発者の Aggregate が物理的なサイジングを改めて記述する必要はありません。 - グループ化された値に対する完全性ルール。
infra.computeは CPU とメモリのキーを持ち、Recipe はそのどちらかを空のままにしたグループに対して停止します。CPU 制限があってメモリ制限のない状態でレンダリングされたコントロールプレーンは、Component の宣言されたデフォルトが記述するものとは実質的に異なり、レンダリング結果のどこにもそれは示されません。そのため、ビルドは停止し、代わりに欠けているキーを示します。グループが省略したキーには Component のデフォルトが適用されます。 - デフォルトを持たない 6 つの鍵。 トークンサービスがレジストリのトークンに署名する鍵とその証明書、レジストリ自身のサービスが相互認証とアップロード状態の署名に使う 3 つのシークレット、リクエストフォージェリ対策の鍵、そしてコントロールプレーンが保存された認証情報を暗号化する鍵には、デフォルト値がありません。カタログの読者全員が持つ鍵があれば、誰でもレジストリが信頼するトークンを発行したり、保存内容を読んだりできてしまうためです。 Component はこれらのスロットを必須として宣言しているため、いずれかを空のままにしたビルドは停止し、そのスロットを示します。ビルドは 6 つの値のいずれも読み込まず、いずれもレンダリングしません。各ワークロードは、それぞれを自らが指定する Secret から読み込みます。
- Release が付加する 3 つの鍵。 モジュールは、トークン署名鍵、コントロールプレーンの共有シークレット、保存された認証情報の暗号化鍵のいずれも付加しないため、Release がその 3 つすべてをモジュールのコンポーネントに
token_key、core_secret、secret_keyとして付加します。いずれもcore/referenced-secretを通じ、infra.originで Secret を指定します。そして Manifest は Feature をk8s-existing-secretにバインドします。コントロールプレーンはトークン署名鍵と暗号化鍵をそれぞれが指定する Secret からマウントし、各サービスは共有シークレットをそれぞれの Secret から読み込みます。 - モジュールが埋める認証情報。 管理者アカウントのパスワード、クロスサイトリクエストフォージェリ対策の鍵、ワーカー層の共有シークレット、blob ストアのアップロード状態シークレットも Component の認証情報スロットであり、モジュールはそれぞれを自身のパラメーター (
admin_password、csrf_key、jobservice_secret、registry_http_secret) からcore/referenced-secret認証情報 Feature を通じて埋めます。そのため、各ワークロードはそれらを名前で指定した Secret から読み込みます。モジュールがその Feature を付加するため、Manifest がそれをマッピングします。3 つの鍵はモジュールでもデフォルトを持たないため、Aggregate は自身のパラメーターを宣言してaggregates.harbor.parametersを通じて渡し、Release がそれらを満たし、k8s-existing-secretがそれぞれを名前空間内に既に存在する Secret の名前として読み込みます。値を与えない Release はビルドを停止させ、そのパラメーターを示します。この例では管理者のパスワードをモジュールの開発用デフォルトのままにしており、Manifest はその 1 つの付加を名前でk8s-secret-from-parameterにバインドします。これはそれを格納した Secret を出力します。残りのパスワードは Release がレンダリングする設定に書き込まれるため、代わりにinfraを設定することで置き換えます。設定しない場合、それぞれ Recipe が定める開発用の値になります。 - 本来なら素材を生成してしまうチャートに対する決定的な出力。 このチャートは、何も与えられなければ自前でシークレットを生成します。コントロールプレーンの共有シークレットとトークン署名シークレット、ワーカー層と blob ストアのシークレット、リクエストフォージェリ対策の鍵、そして blob ストアのハッシュ化パスワードで、最後のものはレンダリングのたびに新しいソルトで再ハッシュされます。これらはすべて代わりに供給されます。6 つの鍵は常に Release が指定する Secret から、パスワードはスロットが埋められている場合は付加された認証情報から名前で、埋められていない場合は固定の開発用の値から供給されます。そのため、同一の入力を 2 回レンダリングするとバイト単位で同一の出力になります。
- 再現可能なイメージ。 レジストリが実行するすべてのイメージは明示的なタグに固定されています。製品はそれらをすべて 1 つのタグで出荷するため、
infra.engine_versionで すべてを一度に選択できます。infra.overrides.imageは単一サービスの固定を置き換え、infra.overrides.image_prefixはミラーから pull する Release のためにそれらをまとめて移動します。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example harbor-stackその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd harbor-stackビルド
このワークスペースには .aggrega-config.yaml がないため、標準ライブラリのエンティティはハブレジストリ hub.aggrega.ai から解決され、カタログフラグは不要です。Recipe はチャートを取得するため、まず依存関係を lockfile に解決します:
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlレンダリングされた成果物は dist/ 配下に出力されます。
これらを適用する前に、レジストリをデプロイする namespace に、Release が指定する 6 つの Secret を作成します。harbor-token-key にはデータキー tls.key の下に RSA 秘密鍵を、tls.crt の下にその鍵に対する証明書を格納します。
harbor-core-secret にはデータキー secret の下に 16 文字のシークレットを格納します。
harbor-secret-key には secretKey の下に 16 文字のキーを格納します。
harbor-csrf-key には CSRF_KEY の下に 32 文字のキーを格納します。
harbor-jobservice-secret と harbor-registry-http-secret には、それぞれ JOBSERVICE_SECRET と REGISTRY_HTTP_SECRET の下に 16 文字のシークレットを格納します。たとえば次のとおりです:
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \ -keyout tls.key -out tls.crtkubectl create secret tls harbor-token-key --key tls.key --cert tls.crtkubectl create secret generic harbor-core-secret --from-literal=secret="$(openssl rand -hex 8)"kubectl create secret generic harbor-secret-key --from-literal=secretKey="$(openssl rand -hex 8)"kubectl create secret generic harbor-csrf-key --from-literal=CSRF_KEY="$(openssl rand -hex 16)"kubectl create secret generic harbor-jobservice-secret --from-literal=JOBSERVICE_SECRET="$(openssl rand -hex 8)"kubectl create secret generic harbor-registry-http-secret --from-literal=REGISTRY_HTTP_SECRET="$(openssl rand -hex 8)"サービスがこれらの Secret を見つけられないレジストリは起動しません。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `harbor-stack` フォルダーがない場合は、`example` を `harbor-stack` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `harbor-stack` フォルダーに書き込まれます。次に、`workspace_root` を `harbor-stack`、`release` を `release-helm-synth.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。ファイルは `harbor-stack/dist/` の下にあります。合成されたレジストリの構成
ビルドは、この設定に対してチャートが定義するリソースを出力します。リバースプロキシ、コンソール、コントロールプレーン、ワーカー層、Blob ストアの Deployment、バックエンド、キャッシュ、スキャナーの StatefulSet、Blob ストアとワーカー層のログ用の永続ボリューム要求、各サービスが読み取る ConfigMap と Secret、そしてそれらの前段にある Service です。これらに加えて、認証情報の Feature が Secret を 1 つ、harbor-zdregistry-admin-password を出力します。これは管理者パスワードに対するモジュールの開発用デフォルト値を保持しており、コントロールプレーンはチャート自身の Secret ではなくこの Secret からパスワードを読み取ります。6 つのキーについては Secret は出力されません。コントロールプレーンはトークン署名キーを harbor-token-key から、暗号化キーを harbor-secret-key からマウントし、サービスはその他のキーを、Release が指定する Secret である harbor-core-secret、harbor-csrf-key、harbor-jobservice-secret、harbor-registry-http-secret から読み取ります。
これらの Service のうち、利用側が接続するアドレスとなるのはちょうど 1 つ、dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml です。
apiVersion: v1kind: Servicemetadata: name: harbor-zdregistry [… omitted: the namespace, the chart's labels, and the labels and annotations every rendered document carries]spec: type: ClusterIP ports: - name: http port: 80 targetPort: 8080 selector: release: harbor-zdregistry app: "harbor" component: nginxそのセレクタはリバースプロキシを指しており、これによってレジストリは単一のアドレスを持ちます。port は infra.port に従います。その背後のプロキシはチャートが固定するポートで待ち受け、Service はそこへ転送するため、infra.port を変更すると公開アドレスが変わり、リスナーは変わりません。
命名: アドレスを公開するノブはリソースに名前を付けるノブではない
この chart は、リソース名の大半をトップレベルの名前ノブから導出し、そこにサフィックスを付けます。コントロールプレーンの Service は <instance>-core、コンソールは <instance>-portal、blob ストアは <instance>-registry となり、ワーカー層、スキャナ、バックエンド、キャッシュも同様です。素の名前そのもので名付けられるものはありません。
公開される Service は別の、公開範囲に限定されたノブによって名付けられ、そのノブ自体のデフォルトはトップレベルの名前とは無関係な固定リテラルです。トップレベルのノブだけを固定する Recipe は、どの Service も応答しないアドレスを公開することになり、また 1 つの namespace 内の 2 つのインスタンスがどちらもその固定リテラルの名前で Service を出力して衝突します。そのため Recipe は両方のノブをインスタンス ID から設定します。これが、上で出力された Service がインスタンスにちなんで名付けられている理由であり、provides.host が実在するアドレスを指している理由です。
これは、どのプラットフォーム chart をラップする場合にも注意深く読む価値があります。provides.host は chart が実際に作成する Service を指す必要があり、それをどのノブが決めるかは chart ごとの性質であって、chart 間に共通する慣例ではありません。
この構成に含まれないもの
チャートの Ingress は無効のままにし、代わりにリバースプロキシをクラスタ内部の Service として公開します。Component が公開するのは外部ホスト名ではなくクラスタ内のアドレスだからです。単一の外部エンドポイントは ingress 層で組み立てられ、このモジュールがエクスポートするアドレスへルーティングします。トランスポートセキュリティは無効です。チャート自身の証明書ソースはレンダリング時に認証局と署名済み証明書を生成するため、同一の入力を 2 回レンダリングしても同じ結果が再現されないからです。Prometheus-operator のモニターも無効です。
レジストリのメトリクスも無効です。Component の values.metrics_enabled は、コントロールプレーン、ワーカー層、blob ストア、および追加のエクスポーターでメトリクスを有効にし、スクレイパーが検出できるよう 4 つの Service を公開します。ただし同じチャート設定は、blob ストアのデバッグリスナー(プロファイリング、実行トレース、ランタイム変数を、呼び出し元の検査なしで提供します)を、クラスタ内のすべての呼び出し元にも開放します。モジュールはこの値をデフォルトの false のままにしているため、この例ではメトリクスはレンダリングされません。Component を自ら宣言する Aggregate はこの値を設定できます。それでも、エクスポーターのイメージは他のイメージと同様に固定されています。