Skip to main content
Um cluster gerenciado executa uma pequena camada de plataforma da qual os serviços ClickHouse dependem. O ClickHouse Cloud propõe atualizações para essa camada; o executor não aplica nada até que você aprove cada uma delas com suas próprias credenciais do cluster.

​
O que é uma atualização da plataforma

A camada de plataforma é composta por três componentes: o controlador de snapshots, o ClickHouse Operator e os coletores de monitoramento. Eles são instalados nessa ordem porque cada um depende das definições de recurso personalizado do anterior. Os serviços utilizam uma StorageClass chamada gp3-encrypted (volumes gp3 criptografados) que acompanha esses componentes. Um pacote de plataforma é o manifesto que o ClickHouse Cloud renderiza para o seu ambiente. Ele fixa as versões de chart e de imagem desses componentes e indica o registry do qual são obtidas. Todo pacote é identificado pelo sha256 desse manifesto. O ClickHouse Cloud o envia ao executor por meio do canal de comandos, e o executor o prepara para a sua aprovação. Um pacote é aplicado em duas metades:
  • A metade de permissões é tudo o que concede ou delimita o acesso: Espaços de nomes, CustomResourceDefinitions, ServiceAccounts, ClusterRoles e ClusterRoleBindings, Roles e RoleBindings, configurações de webhook e de admission, PriorityClasses e a StorageClass. Somente você a aplica, com suas credenciais, executando clicklink clctl platform approve.
  • A metade de cargas de trabalho é o que efetivamente é executado: Deployments, Services, ConfigMaps, Secrets, Jobs e PodDisruptionBudgets. O executor a aplica sob uma identidade dedicada, pcm-platform, que pode escrever apenas esses tipos e nada mais, e somente enquanto o token de curta duração gerado pela sua aprovação estiver válido.
O executor nunca aplica um pacote que você não tenha aprovado. Ele recusa uma sincronização de plataforma cuja metade de permissões esteja ausente, cujo sha256 seja diferente do aprovado ou cujo token tenha expirado. A recusa informa que a aprovação é necessária e indica o sha256 do pacote preparado. A criação de um serviço que precise de uma definição de recurso personalizado ausente na sua plataforma atual falha da mesma forma, com o mesmo comando a ser executado.

​
Aprovar uma atualização de plataforma

​
Credenciais de registry

A autenticação no registry depende do modo de distribuição de imagens registrado para o seu ambiente:
  • Acesso direto ao registry da ClickHouse. Execute a aprovação na VM EC2 do connector. Tanto o approve quanto a sincronização de plataforma do executor assumem a função read-only de puller do ECR do seu ambiente com credenciais do instance metadata service do EC2. Essa função faz login no registry do chart; o executor também a usa para verificar se as imagens de plataforma existem. Perfis da AWS, credenciais de ambiente ou credenciais de SSO em uma workstation não substituem o instance profile. O seu kubeconfig continua fornecendo as credenciais separadas de cluster-admin que aplicam a metade de permissões.
  • Charts em outro registry ECR, incluindo o seu próprio mirror. O login no chart usa as credenciais ambient da AWS do processo que executa o approve ou o executor. Essas credenciais precisam ter permissão de leitura nesse registry.
Use o procedimento de workstation do Kubernetes abaixo somente em deployments com registry espelhado e com a aprovação de plataforma do Kubernetes habilitada. Para acesso direto, peça primeiro à sua equipe de conta que confirme um ambiente de execução compatível com o instance profile do EC2 necessário.
1

Localize o pacote preparado

O ClickHouse Cloud envia cada pacote proposto primeiro ao executor. O executor o registra como o pacote pendente e informa seu sha256 no heartbeat. Existe apenas um pacote em espera por vez; uma proposta mais recente o substitui. Em seguida, o executor recusa a sincronização e registra um comando com falha, cujo resultado termina com o comando a ser executado.
O campo result termina com run: clctl platform approve (pending bundle sha <sha256>). No Kubernetes, a indicação é run: clctl platform approve --secret-namespace <connector-namespace> (pending bundle sha <sha256>). Um create que esbarrou em uma definição de custom resource ausente traz a mesma linha clctl platform approve. Ela aparece no próprio comando que falhou e no erro exibido por clicklink clctl instances create --wait. A sua equipe de conta também avisa você quando uma atualização de plataforma é proposta.Leia o pacote preparado antes de aprová-lo. Ele contém o manifesto e seu sha256.
O executor prepara o pacote como um arquivo junto aos access bundles no host do connector:
2

Execute approve

approve sem flags lê o pacote preparado e calcula seu hash, de modo que você aprova exatamente o que o executor recebeu. Ele renderiza cada chart exatamente como o executor fará e aplica a metade de permissões com o kube context que você escolher. Cria a identidade pcm-platform, se necessário, e emite seu token. Não faz nenhuma requisição ao seu connector endpoint.approve precisa de um kube context com direitos de cluster-admin no cluster gerenciado (--context <name> quando seu kubeconfig contém vários) e das registry credentials referentes ao modo de distribuição de image do seu ambiente. --dry-run renderiza e lista a metade de permissões sem aplicar nem emitir nada; ainda assim, é necessário access ao registry para renderizar os charts.
Execute no host do connector, como root, onde o executor preparou o pacote:
approve grava o token em /etc/clicklink/access/executor/_platform, junto às demais credentials do executor. Ele constrói o novo pacote ao lado do pacote em uso e só o coloca no lugar depois que o token existe, de modo que uma aprovação malsucedida deixa intacto um token ainda válido.
3

Confirmar

approve termina com:
No Kubernetes, uma terceira linha aparece em seguida: Bundle written to Secret <namespace>/<name>; the executor pod sees it once the kubelet refreshes the mount, within about a minute.O ClickHouse Cloud reenvia a sincronização assim que o próximo heartbeat do executor indicar a aprovação. Ele aguarda até 20 minutos por uma sincronização já em andamento e ignora executores cujo último heartbeat tenha mais de 5 minutos. Após 3 tentativas para um mesmo pacote, o processo é interrompido, e a sua equipe de conta o reaciona. O executor aplica a metade de cargas de trabalho e informa a plataforma como synced. Acompanhe a conclusão da sincronização com:
O comando sync_platform mais recente passa para completed. O executor também reporta o status da plataforma e as versões dos componentes ao ClickHouse Cloud a cada heartbeat, de modo que sua equipe de conta vê o mesmo resultado.

​
A janela de aprovação

Uma aprovação emite um token para a identidade pcm-platform, válido por 2 horas por padrão (--ttl altera esse valor). O executor nunca o renova. Quando ele expira, o executor não consegue mais atuar sobre a camada de plataforma e recusa a próxima sincronização de plataforma, exibindo novamente a mensagem de aprovação. Isso é intencional e não depende de conectividade: uma aprovação concedida enquanto o connector está offline expira igualmente conforme seu próprio relógio. Execute approve novamente sempre que:
  • o token expirar antes de a sincronização terminar;
  • o ClickHouse Cloud propuser um pacote diferente. O sha256 que você aprovou fica registrado no ServiceAccount pcm-platform, e o executor recusa a sincronização de qualquer outro pacote até que você o aprove;
  • a criação de um serviço indicar uma definição de recurso personalizado ausente.
Aprovar o mesmo pacote novamente é seguro e substitui o token. O pacote preparado permanece no lugar após a sincronização, portanto uma nova aprovação não exige uma nova proposta.

​
O que a aprovação concede

Você aplica a metade de permissões, portanto ela carrega a sua autoridade; o executor não aplica nada dela. O approve a carimba com o sha256 do pacote, e, antes de tocar em qualquer coisa, o executor verifica se todos os objetos de permissão do pacote que lhe foi enviado estão presentes e aprovados. O executor aplica a metade de cargas de trabalho como pcm-platform. Essa identidade pode criar e atualizar Secrets, ConfigMaps, Services, Deployments, Jobs e PodDisruptionBudgets, apenas dentro dos espaços de nomes da plataforma, o que é imposto por uma política de admissão. Ela pode ler os objetos de que precisa para seu preflight (pods, eventos, espaços de nomes, ServiceAccounts, os kinds de permissão acima). Ela não pode:
  • escrever em nenhum kind de escopo de cluster nem em nenhum objeto RBAC;
  • escalate, bind ou impersonate;
  • emitir ou renovar o próprio token.
A identidade de ciclo de vida de serviço do executor, pcm-executor, é separada e restrita aos espaços de nomes de serviço. Ela não pode escrever nos espaços de nomes da plataforma; suas leituras não são limitadas pela proteção de prefixo. Para a listagem completa de ambas as identidades, consulte o modelo de privilégios.

​
Redefinindo um cluster de teste

O clicklink clctl platform reset existe para clusters de teste: ele desinstala os componentes da plataforma para que a primeira instalação possa ser testada novamente. Antes de alterar qualquer coisa, ele lista os clusters ClickHouse nos espaços de nomes pertencentes a este connector e recusa a operação caso exista algum serviço. Em um cluster vazio, ele desinstala os lançamentos da plataforma na ordem inversa de dependência. Em seguida, remove o pacote de tokens de plataforma do executor: o diretório local em uma VM ou o Secret indicado por --secret-namespace <connector-namespace> no Kubernetes. As CustomResourceDefinitions, o RBAC e a StorageClass permanecem intactos. Execute approve novamente antes da próxima sincronização da plataforma.
reset recebe o manifesto de plataforma renderizado como um arquivo (--bundle); ele não lê o pacote preparado (staged). --dry-run verifica os serviços e exibe o plano sem alterar o cluster.
Última modificação em 26 de setembro de 2026