Skip to main content
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.

​
What a platform update is

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.

​
Approve a platform update

​
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.
1

Find the staged bundle

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.
The result field ends with run: clctl platform approve (pending bundle sha <sha256>). On Kubernetes the hint reads run: clctl platform approve --secret-namespace <connector-namespace> (pending bundle sha <sha256>). 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:
2

Run approve

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 <name> when your kubeconfig holds several) and the 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:
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.
3

Confirm

approve ends with:
On Kubernetes a third line follows: Bundle written to Secret <namespace>/<name>; 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:
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.

​
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 <connector-namespace> on Kubernetes. CustomResourceDefinitions, RBAC, and the StorageClass stay in place. Run approve again before the next platform sync.
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.
Last modified on September 22, 2026