> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# プラットフォーム更新

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

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'プライベートプレビュー'}
        </div>;
};

<PrivatePreviewBadge />

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

<h2 id="what-a-platform-update-is">
  プラットフォーム更新とは
</h2>

プラットフォームレイヤーは、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 を必要とする サービス の作成も同様に失敗し、実行すべきコマンドも同じものが示されます。

<h2 id="approve-a-platform-update">
  プラットフォーム更新の承認
</h2>

<Image img="https://mintcdn.com/private-7c7dfe99-vortex-format/wGEkZpH7GS15Wa4H/images/cloud/reference/byoc-connector-platform-approval.svg?fit=max&auto=format&n=wGEkZpH7GS15Wa4H&q=85&s=5225cd69056de0e59ac9f4a86c22d745" size="lg" alt="ClickHouse Connector のプラットフォーム承認フロー" width="1320" height="800" data-path="images/cloud/reference/byoc-connector-platform-approval.svg" />

<h3 id="registry-credentials">
  レジストリ認証情報
</h3>

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

* **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 に確認してください。

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

    ```bash theme={null}
    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 が含まれています。

    <Tabs>
      <Tab title="Linux VM" id="inspect-vm">
        エグゼキューターは、コネクタホスト上のアクセスバンドルと同じ場所に、バンドルをファイルとしてステージングします:

        ```bash theme={null}
        sudo cat /etc/clicklink/access/executor/platform-pending.json
        ```
      </Tab>

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

        ```bash theme={null}
        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` を返します。次のステップで使用するため、ポートフォワードは開いたままにしておいてください。
      </Tab>
    </Tabs>
  </Step>

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

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

    <Tabs>
      <Tab title="Linux VM" id="approve-vm">
        エグゼキューターがバンドルをステージングしたコネクタホスト上で、root として実行します:

        ```bash theme={null}
        sudo clicklink clctl platform approve --config /etc/clicklink/config.yaml
        ```

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

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

        ```bash theme={null}
        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分以内にこれを認識します。
      </Tab>
    </Tabs>
  </Step>

  <Step title="確認" id="confirm">
    `approve` は次のように終了します:

    ```text theme={null}
    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` として報告します。同期が反映されたことは次のコマンドで確認できます:

    ```bash theme={null}
    clicklink clctl commands list --action sync_platform
    ```

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

<h2 id="the-approval-window">
  承認ウィンドウ
</h2>

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

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

* 同期が完了する前にトークンの有効期限が切れた場合
* ClickHouse Cloud が別の バンドル を提案した場合。承認した sha256 は `pcm-platform` ServiceAccount に記録され、executor はその バンドル を承認するまで他の バンドル の同期を拒否します
* サービス の作成時に custom resource definition が見つからないと報告された場合

同じ バンドル を再度承認しても問題はなく、トークンは置き換えられます。ステージングされた バンドル は同期後もそのまま残るため、再承認にあたって新たな提案は不要です。

<h2 id="what-the-approval-grants">
  承認によって与えられる権限
</h2>

権限側の半分を適用するのはあなた自身であるため、そこにはあなたの権限が伴います。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 の完全な一覧については、[権限モデル](/ja/products/bring-your-own-cloud/connector/reference/privilege-model)を参照してください。

<h2 id="resetting-a-test-cluster">
  テストクラスターのリセット
</h2>

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

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

```bash theme={null}
sudo clicklink clctl platform reset --bundle <manifest-file> --config /etc/clicklink/config.yaml --dry-run
```

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