> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-revert-104359-revert-104251-parquet-single.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Platform updates
> Approve the platform bundles ClickHouse Cloud proposes for a managed cluster: what a bundle is, how approval works, and what it grants
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 ;
};
export const PrivatePreviewBadge = () => {
return ;
};
A managed cluster runs a small platform layer that the ClickHouse services depend on. ClickHouse Cloud proposes updates to that layer; the executor applies nothing until you approve each one with your own cluster credentials.
The platform layer is three components: the snapshot controller, the ClickHouse operator, and the monitoring collectors. They install in that order because each needs the previous one's custom resource definitions. The services use a StorageClass named `gp3-encrypted` (encrypted gp3 volumes) that ships with them.
A platform bundle is the manifest ClickHouse Cloud renders for your environment. It pins the chart and image versions of those components and names the registry they are pulled from. Every bundle is identified by the sha256 of that manifest. ClickHouse Cloud sends it to the executor over the command channel, and the executor stages it for your approval.
A bundle is applied in two halves:
* The **permission half** is everything that grants or shapes access: Namespaces, CustomResourceDefinitions, ServiceAccounts, ClusterRoles and ClusterRoleBindings, Roles and RoleBindings, webhook and admission configurations, PriorityClasses, and the StorageClass. Only you apply it, with your credentials, by running `clicklink clctl platform approve`.
* The **workload half** is what runs: Deployments, Services, ConfigMaps, Secrets, Jobs, and PodDisruptionBudgets. The executor applies it as a dedicated `pcm-platform` identity that can write those kinds and nothing else, and only while the short-lived token your approval minted is valid.
The executor never applies a bundle you have not approved. It refuses a platform sync whose permission half is missing, whose sha256 differs from the approved one, or whose token has expired. The refusal reports that approval is needed and names the sha256 of the staged bundle. A service create that needs a custom resource definition your current platform lacks fails the same way, with the same command to run.
Registry credentials
Registry authentication depends on the image distribution mode registered for your environment:
* **Direct access to ClickHouse's registry.** Run approval on the connector's EC2 VM. Both `approve` and the executor's platform sync assume your environment's read-only ECR puller role with credentials from the EC2 instance metadata service. That role logs in to the chart registry; the executor also uses it to check that the platform images exist. AWS profiles, environment credentials, or SSO credentials on a workstation do not replace the instance profile. Your kubeconfig still supplies the separate cluster-admin credentials that apply the permission half.
* **Charts in another ECR registry, including your own mirror.** Chart login uses the ambient AWS credentials of the process running `approve` or the executor. Those credentials must be allowed to read that registry.
Use the Kubernetes workstation procedure below only for mirrored-registry deployments with Kubernetes platform approval enabled. For direct access, ask your account team to confirm a supported execution environment with the required EC2 instance profile first.
ClickHouse Cloud sends each proposed bundle to the executor first. The executor stages it as the pending bundle and reports its sha256 on the heartbeat. One staged bundle exists at a time; a newer proposal replaces it. The executor then refuses the sync and records a failed command whose result ends with the command to run.
```bash theme={null}
clicklink clctl commands list --status failed --action sync_platform
```
The `result` field ends with `run: clctl platform approve (pending bundle sha )`. On Kubernetes the hint reads `run: clctl platform approve --secret-namespace (pending bundle sha )`. A create that hit a missing custom resource definition carries the same `clctl platform approve` line. It appears in its own failed command and in the error `clicklink clctl instances create --wait` prints. Your account team also tells you when a platform update is proposed.
Read the staged bundle before you approve it. It holds the manifest and its sha256.
The executor stages the bundle as a file next to its access bundles on the connector host:
```bash theme={null}
sudo cat /etc/clicklink/access/executor/platform-pending.json
```
The executor pod stages the bundle on its state volume and serves it on its local API. Open a port-forward and read it:
```bash theme={null}
CONNECTOR_NAMESPACE='clicklink' # the connector namespace you chose at init
kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
curl -s http://127.0.0.1:9999/v1/platform/pending
```
The API answers `404` with `no platform bundle is staged` until the first proposal arrives. Leave the port-forward open for the next step.
`approve` with no flags reads the staged bundle and hashes it, so you approve exactly what the executor received. It renders every chart as the executor will and applies the permission half with the kube context you choose. It creates the `pcm-platform` identity if needed and mints its token. It makes no request to your connector endpoint.
`approve` needs a kube context with cluster-admin rights on the managed cluster (`--context ` when your kubeconfig holds several) and the [registry credentials](#registry-credentials) for your environment's image distribution mode. `--dry-run` renders and lists the permission half without applying or minting anything; it still needs registry access to render the charts.
Run on the connector host, as root, where the executor staged the bundle:
```bash theme={null}
sudo clicklink clctl platform approve --config /etc/clicklink/config.yaml
```
`approve` writes the token to `/etc/clicklink/access/executor/_platform`, next to the executor's other credentials. It builds the new bundle beside the live one and swaps it in only once its token exists, so a failed approve leaves a still-valid token alone.
For a mirrored-registry deployment with Kubernetes platform approval enabled, `approve` reads the staged bundle over the port-forward from the previous step. It delivers the token bundle as a Secret in the connector namespace, which the chart mounts into the pod. Run it from a workstation whose kubeconfig reaches the cluster, with a copy of the connector configuration and [registry access](#registry-credentials). The chart renders the configuration into the executor's ConfigMap; `approve` needs it only for the namespace prefix and reads no credentials from it.
```bash theme={null}
CONNECTOR_NAMESPACE='clicklink' # the connector namespace you chose at 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` reads the staged bundle from `http://127.0.0.1:9999` by default; pass `--endpoint` when your port-forward uses another local port. Without a port-forward it stops and prints the `kubectl port-forward` command to open. The bundle lands in the Secret `clicklink-platform-bundle` (`--secret-name` to change it, matching the chart's `executor.platformBundleSecret`). The executor pod sees it once the kubelet refreshes the mount, within about a minute.
`approve` ends with:
```text theme={null}
Approved: permission object(s) applied, platform token valid until .
The executor may now apply the workload object(s) of this bundle inside .
```
On Kubernetes a third line follows: `Bundle written to Secret /; the executor pod sees it once the kubelet refreshes the mount, within about a minute.`
ClickHouse Cloud re-sends the sync once the executor's next heartbeat shows the approval. It waits up to 20 minutes for a sync already in flight and skips an executor whose last heartbeat is older than 5 minutes. After 3 attempts for one bundle it stops, and your account team re-triggers it. The executor applies the workload half and reports the platform as `synced`. Watch the sync land with:
```bash theme={null}
clicklink clctl commands list --action sync_platform
```
The most recent `sync_platform` command turns `completed`. The executor also reports the platform status and the component versions to ClickHouse Cloud on every heartbeat, so your account team sees the same outcome.
The approval window
An approval mints a token for the `pcm-platform` identity, valid for 2 hours by default (`--ttl` changes it). The executor never renews it. Once it expires the executor can no longer touch the platform layer and refuses the next platform sync with the approval message again. This is by design and independent of connectivity: an approval given while the connector is offline still expires on its own clock.
Run `approve` again whenever:
* the token expired before the sync finished;
* ClickHouse Cloud proposes a different bundle. The sha256 you approved is recorded on the `pcm-platform` ServiceAccount, and the executor refuses a sync for any other bundle until you approve that one;
* a service create reports a missing custom resource definition.
Approving the same bundle again is safe and replaces the token. The staged bundle stays in place after the sync, so a repeat approval needs no new proposal.
What the approval grants
You apply the permission half, so it carries your authority; the executor applies nothing in it. `approve` stamps it with the bundle's sha256, and before touching anything the executor verifies that every permission object of the bundle it was sent is present and approved.
The executor applies the workload half as `pcm-platform`. That identity can create and update Secrets, ConfigMaps, Services, Deployments, Jobs, and PodDisruptionBudgets, only inside the platform namespaces, which an admission policy enforces. It can read the objects it needs for its preflight (pods, events, namespaces, ServiceAccounts, the permission kinds above). It cannot:
* write any cluster-scoped kind or any RBAC object;
* `escalate`, `bind`, or `impersonate`;
* mint or renew its own token.
The executor's service-lifecycle identity, `pcm-executor`, is separate and confined to the service namespaces. It cannot write to the platform namespaces; its reads are not confined by the prefix guard. For the full listing of both identities, see the [privilege model](/products/bring-your-own-cloud/connector/reference/privilege-model).
Resetting a test cluster
`clicklink clctl platform reset` exists for test clusters: it uninstalls the platform components so their first installation can be exercised again. Before changing anything it lists the ClickHouse clusters in the namespaces this connector owns and refuses if any service exists.
On an empty cluster it uninstalls the platform releases in reverse dependency order. It then removes the executor's platform token bundle: the local directory on a VM, or the Secret named by `--secret-namespace ` on Kubernetes. CustomResourceDefinitions, RBAC, and the StorageClass stay in place. Run `approve` again before the next platform sync.
```bash theme={null}
sudo clicklink clctl platform reset --bundle --config /etc/clicklink/config.yaml --dry-run
```
`reset` takes the rendered platform manifest as a file (`--bundle`); it does not read the staged bundle. `--dry-run` checks for services and prints the plan without changing the cluster.