> ## 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.

# Atualizações da plataforma

> Aprove os pacotes de plataforma que o ClickHouse Cloud propõe para um cluster gerenciado: o que é um pacote, como funciona a aprovação e o que ela concede

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>
            {'Em prévia privada'}
        </div>;
};

<PrivatePreviewBadge />

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.

<h2 id="what-a-platform-update-is">
  O que é uma atualização da plataforma
</h2>

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.

<h2 id="approve-a-platform-update">
  Aprovar uma atualização de plataforma
</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="Fluxo de aprovação de plataforma do ClickHouse Connector" width="1320" height="800" data-path="images/cloud/reference/byoc-connector-platform-approval.svg" />

<h3 id="registry-credentials">
  Credenciais de registry
</h3>

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.

<Steps>
  <Step title="Localize o pacote preparado" id="find-the-staged-bundle">
    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.

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

    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.

    <Tabs>
      <Tab title="Linux VM" id="inspect-vm">
        O executor prepara o pacote como um arquivo junto aos access bundles no host do connector:

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

      <Tab title="Kubernetes" id="inspect-kubernetes">
        O pod do Kubernetes do executor prepara o pacote em seu volume de estado e o disponibiliza em sua API local. Abra um redirecionamento de porta e leia-o:

        ```bash theme={null}
        CONNECTOR_NAMESPACE='clicklink'   # o espaço de nomes do connector que você escolheu no init
        kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
        curl -s http://127.0.0.1:9999/v1/platform/pending
        ```

        A API responde `404` com `no platform bundle is staged` até que a primeira proposta chegue. Deixe o redirecionamento de porta aberto para o próximo passo.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Execute approve" id="run-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](#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.

    <Tabs>
      <Tab title="VM Linux" id="approve-vm">
        Execute no host do connector, como root, onde o executor preparou o pacote:

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

        `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.
      </Tab>

      <Tab title="Kubernetes" id="approve-kubernetes">
        Em uma implantação com registry espelhado e aprovação de plataforma no Kubernetes habilitada, `approve` lê o pacote preparado por meio do redirecionamento de porta do passo anterior. Ele entrega o pacote de token como um Secret no espaço de nomes do connector, que o chart monta no pod do Kubernetes. Execute-o a partir de uma workstation cujo kubeconfig alcance o cluster, com uma cópia da configuração do connector e [access ao registry](#registry-credentials). O chart renderiza a configuração no ConfigMap do executor; `approve` precisa dela apenas para o prefix do espaço de nomes e não lê nenhuma credential dela.

        ```bash theme={null}
        CONNECTOR_NAMESPACE='clicklink'   # o espaço de nomes do connector que você escolheu no 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}"
        ```

        Por padrão, `approve` lê o pacote preparado em `http://127.0.0.1:9999`; passe `--endpoint` quando seu redirecionamento de porta usar outra porta local. Sem um redirecionamento de porta, ele interrompe a execução e exibe o comando `kubectl port-forward` a ser executado. O pacote é gravado no Secret `clicklink-platform-bundle` (use `--secret-name` para alterá-lo, mantendo correspondência com o `executor.platformBundleSecret` do chart). O pod do Kubernetes do executor passa a enxergá-lo assim que o agente de nó do Kubernetes atualiza a montagem, em cerca de um minuto.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Confirmar" id="confirm">
    `approve` termina com:

    ```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>.
    ```

    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:

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

    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.
  </Step>
</Steps>

<h2 id="the-approval-window">
  A janela de aprovação
</h2>

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.

<h2 id="what-the-approval-grants">
  O que a aprovação concede
</h2>

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](/pt-BR/products/bring-your-own-cloud/connector/reference/privilege-model).

<h2 id="resetting-a-test-cluster">
  Redefinindo um cluster de teste
</h2>

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.

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

`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.