プラットフォーム更新とは
プラットフォームレイヤーは、snapshot controller、ClickHouse operator、監視 collectors の3つのコンポーネントで構成されます。各コンポーネントは直前のコンポーネントの custom resource definitions を必要とするため、この順序でインストールされます。サービス は、これらと併せて提供されるgp3-encrypted という名前の StorageClass (暗号化された gp3 volume) を使用します。
プラットフォーム バンドルとは、ClickHouse Cloud がお使いの環境向けにレンダリングする マニフェスト です。対象コンポーネントの チャート バージョンと イメージ バージョンを固定し、それらの取得元となる レジストリ を指定します。各 バンドル は、その マニフェスト の sha256 によって識別されます。ClickHouse Cloud はコマンドチャネル経由でこれを executor に送信し、executor は承認待ちの状態でこれをステージングします。
バンドル は、次の2つの部分に分かれて適用されます:
- 権限側の半分 は、アクセスを付与または規定するすべての要素です: ネームスペース、CustomResourceDefinitions、ServiceAccounts、ClusterRoles と ClusterRoleBindings、Roles と RoleBindings、webhook および admission configurations、PriorityClasses、そして StorageClass です。これを適用できるのはユーザー自身のみで、
clicklink clctl platform approveを実行し、自身の 認証情報 を使用します。 - ワークロード側の半分 は、実際に稼働する要素です: Deployments、サービス、ConfigMaps、Secrets、Jobs、PodDisruptionBudgets です。executor はこれらの種類のみを書き込める専用の
pcm-platformidentity として適用し、しかも承認によって発行された短命の トークン が有効な間に限られます。
プラットフォーム更新の承認
レジストリ認証情報
レジストリの認証方式は、環境に登録されているイメージの配布モードによって異なります。- ClickHouse のレジストリへの直接アクセス。 承認はコネクタの EC2 VM 上で実行します。
approveと executor の プラットフォーム同期 はいずれも、EC2 instance metadata サービス から取得した認証情報を使用して、環境の読み取り専用 ECR プラーロールを assume します。このロールでチャートレジストリにログインし、executor はプラットフォームイメージの存在確認にもこのロールを使用します。ワークステーション上の AWS プロファイル、環境変数による認証情報、SSO 認証情報は instance profile の代わりにはなりません。権限側の半分を適用するクラスター管理者の認証情報は、引き続き kubeconfig から提供されます。 - 自前のミラーを含む、別の ECR レジストリ上のチャート。 チャートへのログインには、
approveまたは executor を実行しているプロセスの ambient な AWS 認証情報が使用されます。これらの認証情報には、そのレジストリへの読み取り権限が必要です。
1
ステージング済みのバンドルを確認する
ClickHouse Cloud は、提案された各 bundle をまず executor に送信します。executor はこれを pending bundle としてステージングし、その sha256 をハートビートで報告します。ステージングされる bundle は常に 1 つのみで、より新しい提案が届くと置き換えられます。その後 executor は同期を拒否し、failed コマンドとして記録します。その結果の末尾には、実行すべきコマンドが示されます。
result フィールドは run: clctl platform approve (pending bundle sha <sha256>) で終わります。Kubernetes の場合、ヒントは run: clctl platform approve --secret-namespace <connector-namespace> (pending bundle sha <sha256>) となります。カスタムリソース定義が見つからずに失敗した作成処理にも、同じ clctl platform approve の行が含まれます。この行は、失敗したコマンド自体の出力と、clicklink clctl instances create --wait が表示するエラーの両方に現れます。プラットフォーム更新が提案された際には、担当のアカウントチームからも連絡があります。承認する前に、ステージングされたバンドルを確認してください。バンドルにはマニフェストとその sha256 が含まれています。- Linux VM
- Kubernetes
エグゼキューターは、コネクタホスト上のアクセスバンドルと同じ場所に、バンドルをファイルとしてステージングします:
2
承認を実行
フラグなしの
approve は、ステージングされたバンドルを読み取ってハッシュ化するため、エグゼキューターが受け取ったものとまったく同じ内容を承認することになります。すべてのチャートをエグゼキューターとまったく同じようにレンダリングし、選択した kube コンテキストで権限側の適用を行います。必要に応じて pcm-platform アイデンティティを作成し、そのトークンを発行します。コネクタのエンドポイントへのリクエストは一切行いません。approve には、マネージドクラスターに対する cluster-admin 権限を持つ kube コンテキスト(kubeconfig に複数含まれる場合は --context <name> を指定します)と、環境のイメージ配布モードに応じたレジストリ認証情報が必要です。--dry-run を指定すると、適用や発行は行わず、レンダリングと権限側の一覧表示のみを実行します。ただし、チャートをレンダリングするためにレジストリへのアクセスは必要です。- Linux VM
- Kubernetes
エグゼキューターがバンドルをステージングしたコネクタホスト上で、root として実行します:
approve はトークンを、エグゼキューターの他の認証情報と同じ場所にある /etc/clicklink/access/executor/_platform に書き込みます。新しいバンドルは生存中のバンドルの隣にビルドされ、そのトークンが存在した時点で初めて入れ替えられるため、承認に失敗しても有効なトークンはそのまま残ります。3
確認
approve は次のように終了します:Bundle written to Secret <namespace>/<name>; the executor pod sees it once the kubelet refreshes the mount, within about a minute.ClickHouse Cloud は、executor の次のハートビートで承認が確認された時点で同期を再送します。すでに実行中の同期は最大 20 分待機し、最後のハートビートから 5 分以上経過している executor はスキップします。1 つのバンドルに対して 3 回試行しても完了しない場合は処理を停止し、担当のアカウントチームが再度トリガーします。executor はワークロード側の設定を適用し、プラットフォームを synced として報告します。同期が反映されたことは次のコマンドで確認できます:sync_platform コマンドが completed に変わります。executor はハートビートのたびにプラットフォームの status とコンポーネントのバージョンを ClickHouse Cloud に報告するため、account team でも同じ結果を確認できます。承認ウィンドウ
承認を行うと、pcm-platform identity 向けのトークンが発行されます。このトークンの有効期間はデフォルトで 2 時間です (--ttl で変更できます) 。executor がこれを更新することはありません。有効期限が切れると、executor はプラットフォームレイヤーを操作できなくなり、次回のプラットフォーム同期は再び承認メッセージを表示して拒否されます。これは設計どおりの動作であり、接続状態にも依存しません。コネクタがオフラインの間に与えた承認も、それ自身の時計に従って期限切れになります。
次の場合は、あらためて approve を実行してください。
- 同期が完了する前にトークンの有効期限が切れた場合
- ClickHouse Cloud が別の バンドル を提案した場合。承認した sha256 は
pcm-platformServiceAccount に記録され、executor はその バンドル を承認するまで他の バンドル の同期を拒否します - サービス の作成時に custom resource definition が見つからないと報告された場合
承認によって与えられる権限
権限側の半分を適用するのはあなた自身であるため、そこにはあなたの権限が伴います。executor 自身はその中身を一切適用しません。approve はそこにバンドルの sha256 を刻印し、executor は何かに手を加える前に、送信されたバンドルのすべての権限オブジェクトが存在し、かつ承認済みであることを検証します。
executor はワークロード側の半分を pcm-platform として適用します。この identity は Secret、ConfigMap、Service、Deployment、Job、PodDisruptionBudget を作成・更新できますが、その範囲はプラットフォームのネームスペース内に限られ、これは admission ポリシーによって強制されます。preflight に必要なオブジェクト (ポッド、イベント、ネームスペース、ServiceAccount、上記の権限 kind) は読み取れます。一方、次の操作はできません。
- クラスタースコープの kind や RBAC オブジェクトへの書き込み
escalate、bind、impersonate- 自身のトークンの発行または更新
pcm-executor はこれとは別個のもので、サービスのネームスペースに限定されています。プラットフォームのネームスペースへは書き込めませんが、読み取りはプレフィックスガードによる制限を受けません。両方の identity の完全な一覧については、権限モデルを参照してください。
テストクラスターのリセット
clicklink clctl platform reset はテストクラスター向けのコマンドです。プラットフォームのコンポーネントをアンインストールし、初回インストールを再度実行できる状態に戻します。変更を加える前に、このコネクタが所有するネームスペース内の ClickHouse クラスターを一覧表示し、サービスが 1 つでも存在する場合は処理を中止します。
クラスターが空の場合は、プラットフォームのリリースを依存関係の逆順にアンインストールします。続いて executor のプラットフォームトークンバンドルを削除します。対象は、VM 上ではローカルディレクトリ、Kubernetes 上では --secret-namespace <connector-namespace> で指定された Secret です。CustomResourceDefinition、RBAC、StorageClass はそのまま残ります。次回のプラットフォーム同期の前に、再度 approve を実行してください。
reset はレンダリング済みのプラットフォームマニフェストをファイル (--bundle) として受け取ります。ステージングされたバンドルは読み込みません。--dry-run はサービスの有無をチェックし、クラスターを変更せずにプランを出力します。