プラットフォーム更新

ClickHouse Cloud がマネージドクラスターに対して提案するプラットフォームバンドルを承認します。バンドルとは何か、承認の流れ、承認によって付与される権限について説明します

マネージドクラスターでは、ClickHouse のサービスが依存する小規模なプラットフォームレイヤーが動作しています。ClickHouse Cloud はそのレイヤーに対するプラットフォーム更新を提案しますが、各更新をご自身のクラスターの認証情報で承認するまで、executor は何も適用しません。

​

プラットフォーム更新とは

プラットフォームレイヤーは、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-platform identity として適用し、しかも承認によって発行された短命の トークン が有効な間に限られます。

executor が未承認の バンドル を適用することは決してありません。権限側の半分 が欠けている場合、sha256 が承認済みのものと異なる場合、または トークン が期限切れの場合、プラットフォーム同期は拒否されます。拒否時には承認が必要である旨と、ステージングされている バンドル の sha256 が示されます。現在のプラットフォームに存在しない custom resource definition を必要とする サービス の作成も同様に失敗し、実行すべきコマンドも同じものが示されます。

​

プラットフォーム更新の承認

​

レジストリ認証情報

レジストリの認証方式は、環境に登録されているイメージの配布モードによって異なります。

• ClickHouse のレジストリへの直接アクセス。 承認はコネクタの EC2 VM 上で実行します。approve と executor の プラットフォーム同期 はいずれも、EC2 instance metadata サービス から取得した認証情報を使用して、環境の読み取り専用 ECR プラーロールを assume します。このロールでチャートレジストリにログインし、executor はプラットフォームイメージの存在確認にもこのロールを使用します。ワークステーション上の AWS プロファイル、環境変数による認証情報、SSO 認証情報は instance profile の代わりにはなりません。権限側の半分を適用するクラスター管理者の認証情報は、引き続き kubeconfig から提供されます。
• 自前のミラーを含む、別の ECR レジストリ上のチャート。 チャートへのログインには、approve または executor を実行しているプロセスの ambient な AWS 認証情報が使用されます。これらの認証情報には、そのレジストリへの読み取り権限が必要です。

以下の Kubernetes ワークステーション手順は、Kubernetes プラットフォーム承認を有効にしたミラーレジストリ構成のデプロイメントでのみ使用してください。直接アクセスの場合は、まず必要な EC2 instance profile を備えたサポート対象の実行環境であることを account team に確認してください。

1. ステージング済みのバンドルを確認する

   ClickHouse Cloud は、提案された各 bundle をまず executor に送信します。executor はこれを pending bundle としてステージングし、その sha256 をハートビートで報告します。ステージングされる bundle は常に 1 つのみで、より新しい提案が届くと置き換えられます。その後 executor は同期を拒否し、failed コマンドとして記録します。その結果の末尾には、実行すべきコマンドが示されます。

   clicklink clctl commands list --status failed --action sync_platform
   

   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

   エグゼキューターは、コネクタホスト上のアクセスバンドルと同じ場所に、バンドルをファイルとしてステージングします:

   sudo cat /etc/clicklink/access/executor/platform-pending.json
   

   Kubernetes

   エグゼキューターポッドは、自身のステートボリュームにバンドルをステージングし、ローカル API 経由で提供します。ポートフォワードを開いて内容を読み取ってください:

   CONNECTOR_NAMESPACE='clicklink'   # init で選択したコネクタネームスペース
   kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
   curl -s http://127.0.0.1:9999/v1/platform/pending
   

   最初の提案が届くまで、API は no platform bundle is staged というメッセージとともに 404 を返します。次のステップで使用するため、ポートフォワードは開いたままにしておいてください。

2. 承認を実行

   フラグなしの approve は、ステージングされたバンドルを読み取ってハッシュ化するため、エグゼキューターが受け取ったものとまったく同じ内容を承認することになります。すべてのチャートをエグゼキューターとまったく同じようにレンダリングし、選択した kube コンテキストで権限側の適用を行います。必要に応じて pcm-platform アイデンティティを作成し、そのトークンを発行します。コネクタのエンドポイントへのリクエストは一切行いません。

   approve には、マネージドクラスターに対する cluster-admin 権限を持つ kube コンテキスト(kubeconfig に複数含まれる場合は --context <name> を指定します)と、環境のイメージ配布モードに応じたレジストリ認証情報が必要です。--dry-run を指定すると、適用や発行は行わず、レンダリングと権限側の一覧表示のみを実行します。ただし、チャートをレンダリングするためにレジストリへのアクセスは必要です。

   Linux VM

   エグゼキューターがバンドルをステージングしたコネクタホスト上で、root として実行します:

   sudo clicklink clctl platform approve --config /etc/clicklink/config.yaml
   

   approve はトークンを、エグゼキューターの他の認証情報と同じ場所にある /etc/clicklink/access/executor/_platform に書き込みます。新しいバンドルは生存中のバンドルの隣にビルドされ、そのトークンが存在した時点で初めて入れ替えられるため、承認に失敗しても有効なトークンはそのまま残ります。

   Kubernetes

   ミラーレジストリを使用するデプロイメントで Kubernetes のプラットフォーム承認が有効になっている場合、approve は前の手順で設定したポートフォワード経由でステージングされたバンドルを読み取ります。トークンバンドルはコネクタのネームスペース内の Secret として配信され、チャートがそれをポッドにマウントします。kubeconfig からクラスターに到達できるワークステーションで、コネクタの設定のコピーとレジストリへのアクセスを用意して実行してください。チャートはエグゼキューターの ConfigMap に設定をレンダリングします。approve はネームスペースのプレフィックスを得るためだけにこれを必要とし、そこから認証情報を読み取ることはありません。

   CONNECTOR_NAMESPACE='clicklink'   # init 時に選択したコネクタのネームスペース
   kubectl -n "${CONNECTOR_NAMESPACE}" get configmap clicklink-connector-executor \
     -o jsonpath='{.data.config\.yaml}' > clicklink-config.yaml
   clicklink clctl platform approve --config clicklink-config.yaml \
     --secret-namespace "${CONNECTOR_NAMESPACE}"
   

   approve はデフォルトで http://127.0.0.1:9999 からステージングされたバンドルを読み取ります。ポートフォワードが別のローカルポートを使用している場合は --endpoint を指定してください。ポートフォワードがない場合は処理を中止し、実行すべき kubectl port-forward コマンドを表示します。バンドルは Secret clicklink-platform-bundle に配置されます(変更するには --secret-name を使用し、チャートの executor.platformBundleSecret と一致させます)。エグゼキューターのポッドは、キューブレットがマウントを更新した時点、およそ1分以内にこれを認識します。

3. 確認

   approve は次のように終了します:

   Approved: <n> permission object(s) applied, platform token valid until <expiry>.
   The executor may now apply the <n> workload object(s) of this bundle inside <namespaces>.
   

   Kubernetes では、3 行目として次の内容が続きます: 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 として報告します。同期が反映されたことは次のコマンドで確認できます:

   clicklink clctl commands list --action sync_platform
   

   直近の sync_platform コマンドが completed に変わります。executor はハートビートのたびにプラットフォームの status とコンポーネントのバージョンを ClickHouse Cloud に報告するため、account team でも同じ結果を確認できます。

​

承認ウィンドウ

承認を行うと、pcm-platform identity 向けのトークンが発行されます。このトークンの有効期間はデフォルトで 2 時間です (--ttl で変更できます) 。executor がこれを更新することはありません。有効期限が切れると、executor はプラットフォームレイヤーを操作できなくなり、次回のプラットフォーム同期は再び承認メッセージを表示して拒否されます。これは設計どおりの動作であり、接続状態にも依存しません。コネクタがオフラインの間に与えた承認も、それ自身の時計に従って期限切れになります。

次の場合は、あらためて approve を実行してください。

• 同期が完了する前にトークンの有効期限が切れた場合
• ClickHouse Cloud が別の バンドル を提案した場合。承認した sha256 は pcm-platform ServiceAccount に記録され、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
• 自身のトークンの発行または更新

executor のサービスライフサイクル用 identity である pcm-executor はこれとは別個のもので、サービスのネームスペースに限定されています。プラットフォームのネームスペースへは書き込めませんが、読み取りはプレフィックスガードによる制限を受けません。両方の identity の完全な一覧については、権限モデルを参照してください。

​

テストクラスターのリセット

clicklink clctl platform reset はテストクラスター向けのコマンドです。プラットフォームのコンポーネントをアンインストールし、初回インストールを再度実行できる状態に戻します。変更を加える前に、このコネクタが所有するネームスペース内の ClickHouse クラスターを一覧表示し、サービスが 1 つでも存在する場合は処理を中止します。

クラスターが空の場合は、プラットフォームのリリースを依存関係の逆順にアンインストールします。続いて executor のプラットフォームトークンバンドルを削除します。対象は、VM 上ではローカルディレクトリ、Kubernetes 上では --secret-namespace <connector-namespace> で指定された Secret です。CustomResourceDefinition、RBAC、StorageClass はそのまま残ります。次回のプラットフォーム同期の前に、再度 approve を実行してください。

sudo clicklink clctl platform reset --bundle <manifest-file> --config /etc/clicklink/config.yaml --dry-run

reset はレンダリング済みのプラットフォームマニフェストをファイル (--bundle) として受け取ります。ステージングされたバンドルは読み込みません。--dry-run はサービスの有無をチェックし、クラスターを変更せずにプランを出力します。