Skip to main content
Esta página orienta você desde o token de inscrição até um connector verificado em modo managed, no qual o executor aplica o ciclo de vida do serviço conduzido pelo ClickHouse Cloud. O connector é instalado em um cluster do Kubernetes (Helm) ou em uma VM Linux (systemd). A inscrição por token é o fluxo padrão. Quando o ambiente não puder acessar diretamente o connector endpoint do seu connector, consulte instalações isoladas da internet e com espelhamento. Para observar um ClickHouse que você mesmo executa, sem o executor, use --no-managed.

​
Pré-requisitos

​
Registre seu ambiente

Antes de realizar a inscrição, sua account team registra seu ambiente e habilita o modo managed para sua organização. Forneça a ela:
  • o ID da sua AWS account, a region e o nome do EKS cluster
  • se o connector é executado em uma Linux VM ou no cluster
  • o node group dos componentes de plataforma
  • o prefix do espaço de nomes dos serviços (padrão ns-)
  • como seu cluster obtém as imagens do ClickHouse: pelo registry access que o ClickHouse Cloud configura para sua account ou pelo seu próprio mirror
Em seguida, o ClickHouse Cloud emite seu connector endpoint, um token de inscrição de uso único e o ARN do repositório ECR do chart do cluster do ClickHouse (a entrada chart_repository_arn dos módulos raiz do Terraform). Uma instalação via Terraform também recebe o pacote da plataforma nesta etapa: no Helm, ele é aplicado por clicklink clctl init --managed --from-terraform --platform-bundle; em uma VM, por clicklink clctl platform approve --bundle, após a inscrição. Qualquer outra instalação gerenciada recebe seu primeiro pacote mais tarde, preparado pelo executor e aplicado com clicklink clctl platform approve, conforme descrito em atualizações da plataforma; uma instalação com --no-managed não precisa de pacote. O token identifica seu ambiente, portanto a inscrição não requer nenhum ID adicional.

​
Para toda instalação

  • Connector v0.17.0 ou posterior. Lançamentos anteriores não têm modo managed, comandos platform nem instances create. O instalador entrega o lançamento mais recente, a menos que você passe --version.
  • Seu connector endpoint e token de inscrição, fornecidos durante o registro.
  • Egress na porta 443 para https://<subdomain>.<connector-domain> e https://<subdomain>.enroll.<connector-domain>, além de releases.clicklink.clickhouse.com e Amazon ECR Public no momento da instalação. No modo managed, o executor também acessa o Amazon ECR e o STS quando uma sincronização ou criação de plataforma baixa um chart do ECR. Caso algum desses destinos esteja inacessível, consulte instalações isoladas da internet e com espelhamento.
  • Um EKS cluster da Amazon para o modo managed. O init recusa o modo managed em qualquer outro cluster e indica --no-managed para uma instalação sem o executor. O Terraform na AWS oferece módulos raiz tanto para um cluster novo quanto para um que você já opera, além do comando init que instala a camada de plataforma sobre eles.
  • Permissão de administrador do cluster para o grant do executor. O grant cria uma ClusterRole, um ClusterRoleBinding e uma ValidatingAdmissionPolicy que restringe o executor aos espaços de nomes sob o seu prefix. No Kubernetes, o kubeconfig com o qual você executa o init precisa dessa permissão. Em uma VM, quem precisa dela é o kubeconfig do host; quando o host não tem permissões de admin, o init imprime o comando a ser executado a partir de um host que as tenha.
  • Nenhum ClickHouse ainda. Uma instalação gerenciada começa sem serviços; os que o executor cria se registram sozinhos. No modo managed, o init não registra nenhum ClickHouse executado por você (no Kubernetes, ele recusa --instance e --instance-namespace). Para observar um cluster desse tipo, instale uma implantação de connector separada com --no-managed. O --ch-user-suffix permite que as duas implantações compartilhem uma instance sem conflitos entre os usuários do connector. Essa implantação precisa de um listener native acessível, 9440 seguro ou 9000 em plaintext, detectado automaticamente no Kubernetes. Ela também precisa de acesso de ClickHouse admin para o provisioning: um usuário default sem password, uma password informada com --ch-admin-password-stdin ou no prompt, ou injection de CR para instances gerenciadas por operator.
  • cosign em qualquer lugar onde você baixe release artifacts. O instalador sempre verifica o checksum SHA-256. Com o cosign instalado, ele também verifica a assinatura do lançamento e, com CLICKLINK_REQUIRE_COSIGN=1, recusa-se a prosseguir sem o cosign.

​
Para instalações no Kubernetes (Helm)

  • Um kubeconfig cujo contexto atual aponte para o cluster EKS. Ele deve ser capaz de criar e ler o espaço de nomes do connector, aplicar Secrets, criar ServiceAccounts, Roles e RoleBindings, instalar o chart e conceder ao executor seu acesso a todo o cluster.
  • AWS credenciais na workstation (ambiente ou perfil) com eks:DescribeCluster e ec2:DescribeVpcs. O init as utiliza para ler os blocos CIDR da VPC do seu cluster para a NetworkPolicy. Se o lookup falhar, ele emite um aviso e deixa essa lista para você preencher.
  • Os CIDRs por trás do seu connector endpoint, para habilitar a NetworkPolicy de negação padrão do chart no momento da instalação. Sem eles, o init prepara a policy desabilitada e exibe como habilitá-la posteriormente.
  • Uma StorageClass padrão, ou uma classe a ser informada com --storage-class; o solucionador de problemas e o executor mantêm estado em PersistentVolumeClaims.
  • Acesso de pull de imagens: os nós do cluster devem conseguir extrair a imagem pública do ECR, ou um mirror hospedado por você.

​
Para instalações em Linux VM (systemd)

  • Qualquer host Linux com systemd, amd64 ou arm64. As compilações Linux são executadas em modo FIPS.
  • Acesso root para o instalador e para o init.
  • Portas livres 8082, 8084 e 8086 para saúde e métricas, 9999 na interface de loopback para a API local do executor, e 8443 quando o gateway de sessão de suporte estiver habilitado.
  • Acesso de Admin ao Kubernetes API server para o provisioning e para o grant do executor: um kubeconfig no host, --server e --ca-data, ou os prompts. Os access bundles são ancorados em ServiceAccounts do Kubernetes em ambos os targets. No modo managed, o contexto atual do kubeconfig deve apontar para o EKS cluster que você gerencia; o init se recusa a conceder o grant por meio de qualquer outro contexto.
Em uma VM, --skip-provision é a única forma de contornar a exigência do Kubernetes API server, e vale apenas para stage. Ele ignora o provisioning do ClickHouse user, o grant do executor, a habilitação da unit e a verificação, ou seja, por si só não resulta em nenhum connector em execução. No Kubernetes, ele ignora apenas o provisioning do ClickHouse user. O grant do executor continua sendo aplicado, porque o executor do chart não consegue ser agendado sem a ServiceAccount com o grant concedido.

​
Instale e faça o registro

1

Obtenha o endpoint do conector e o token de inscrição

Ambos são fornecidos pela sua equipe de conta assim que o seu ambiente for registrado. O endpoint tem o seguinte formato:
O token é de uso único e expira rapidamente, portanto faça a inscrição logo após recebê-lo. Trate-o como um segredo: a CLI o lê a partir de um prompt oculto ou da primeira linha do stdin, nunca de argumentos de linha de comando, do disco ou de logs. Caso ele expire antes de você concluir a inscrição, solicite um novo à sua equipe de conta.
2

Instale e verifique a CLI

Um único comando instala um binary clicklink verificado. Ele detecta sua plataforma (macOS ou Linux, amd64 ou arm64), baixa o lançamento atual e verifica o checksum SHA-256. Caso o cosign esteja instalado, ele também verifica a assinatura do lançamento. A instalação é feita em /usr/local/bin quando esse diretório é gravável; caso contrário, em ~/.local/bin (adicione-o ao seu PATH, se necessário; --bin-dir sobrescreve esse comportamento). Para uma instalação em Kubernetes, execute-o em qualquer workstation com acesso ao cluster via kubeconfig:
Para uma instalação em VM, execute o mesmo script no host com --host. Após o download verificado, ele cria o usuário de sistema clicklink, os diretórios /etc/clicklink, /var/lib/clicklink e /var/log/clicklink, e as systemd units dos três componentes. Ele inicializa o /etc/clicklink/redaction-patterns.yaml com um conjunto inicial de patterns (um arquivo existente é preservado), de modo que a próxima etapa é a inscrição:
Ambas as formas aceitam --version vX.Y.Z para fixar um lançamento. Reexecutar qualquer uma delas é seguro: a instalação no host faz backup do binary anterior e preserva a sua configuração ativa. Para inspecionar o script antes de executá-lo, ou para baixar e verificar você mesmo o tarball do lançamento, consulte download e verificação manuais.
3

Registre e instale o conector

init --enroll resgata seu token, obtém um certificate de cliente assinado e o acesso cluster-wide do executor e, em seguida, instala e verifica o connector.Em um terminal, o init pergunta Enable managed mode (ClickHouse manages the lifecycle of ClickHouse services in this cluster)? com yes pré-selecionado. Passe --managed para pular o prompt, ou --no-managed para uma instalação somente de observação, sem o executor. Uma instalação nova não assistida sem nenhum dos dois flags deixa o modo gerenciado desativado (uma reexecução com --force mantém a postura da configuração substituída), portanto sempre passe --managed em scripts.
Na sua estação de trabalho, com o contexto kube apontado para o seu EKS cluster, execute:
Cole o enrollment token no prompt oculto. O init lê o nome, a region e a AWS account do cluster a partir do ARN do EKS do contexto atual, ou seja, você não digita nada sobre o cluster. Em seguida, ele solicita:
  • o namespace do connector (padrão clicklink)
  • uma StorageClass, apenas quando o cluster não define nenhuma como padrão
  • os CIDRs por trás do endpoint do seu connector, para a allowlist de egress da NetworkPolicy (deixe em branco para preparar a policy desativada)
  • a postura de support-session e, se habilitada, a allowlist de e-mails de operator
O init resgata o token e salva o enrollment bundle como handoff.yaml no diretório de trabalho. Ele prepara a sobreposição de values do Helm clicklink-values.yaml com o bloco executor e os intervalos da VPC do seu cluster como os CIDRs do API server da NetworkPolicy. Ele cria o namespace, aplica o Secret clicklink-hmac, gera a private key dentro do Secret clicklink-mtls e grava o CSR. Ele concede o acesso cluster-wide do executor ao namespace do connector e faz com que o ClickHouse Cloud assine o certificate do cliente. Ele instala o release Helm clicklink-connector com seu cliente Helm integrado (sem necessidade do binary helm) e verifica a integridade.Para execuções não assistidas, responda aos prompts com flags. Use o bundle salvo como ponto de entrada ou envie o enrollment token para --enroll como a primeira linha do stdin:
Passe --no-gateway em vez de --operators para desativar as support sessions; os dois flags são mutuamente exclusivos.
Quando a instalação é verificada, o init exibe Managed mode is on junto com o comando que prepara seu primeiro serviço. Continue em criar um serviço.
4

Verifique se a instalação foi bem-sucedida

O init verifica a instalação antes de reportar sucesso. No Kubernetes, ele consulta periodicamente o endpoint /livez de cada componente habilitado, incluindo o executor, por até cinco minutos. Quando o gateway de sessão de suporte está habilitado, ele também exige que o gateway responda 401 a probes não autenticados. Em uma VM, ele aguarda o /livez de cada daemon e, em seguida, executa a suíte completa de preflight. A suíte verifica a configuração, os arquivos, conflitos de porta, a alcançabilidade da rede, a conectividade com o ClickHouse, o estado das unidades systemd para as três unidades, o acesso por componente, o disco e os padrões de mascaramento.Para confirmar manualmente no Kubernetes:
Todos os pods do connector devem estar Running e prontos: o scraper, o solucionador de problemas e o executor.Para confirmar manualmente em uma VM:
Ele retorna 0 quando todas as verificações passam e 2 em caso de falha, além de exibir as verificações que falharam.
5

Limpar

O pacote de inscrição handoff.yaml (modo 0600, no diretório de trabalho) permite que reexecuções e a recuperação durante a instalação prossigam sem um segundo token. Ele armazena o secret de API do connector em plaintext, portanto exclua-o assim que a instalação for verificada:
O connector em execução mantém sua própria cópia das credenciais; upgrades e alterações de configuração nunca precisam desse arquivo. Se mais tarde você precisar do init novamente, solicite um novo enrollment token à sua account team e execute init --enroll --force.

​
Instalações isoladas da internet e com espelhamento

Duas partes independentes podem ser transferidas fora de banda, dependendo do que o seu ambiente consegue alcançar. O executor não precisa de nada adicional: ele se autentica com o mesmo certificado de cliente e as mesmas credenciais de API que os demais componentes. Você aplica o grant cluster-wide dele pelo seu kubeconfig, e não pela rede. Entrega do pacote. Se preferir não resgatar um token on-line, a sua account team pode entregar o pacote de inscrição diretamente durante o onboarding; execute clicklink clctl init --handoff <bundle-file> no lugar de --enroll. O --handoff substitui apenas o resgate do token. A assinatura do certificado continua ocorrendo pelo endpoint de inscrição, portanto use --handoff sozinho apenas quando esse endpoint estiver acessível de onde você executa o init. Assinatura de certificado fora de banda. Quando o endpoint de inscrição não estiver acessível de onde você executa o init, adicione --no-auto-sign: o init prepara tudo e grava o clicklink.csr. Envie o CSR para a sua account team e conclua a instalação com o certificado e a chain retornados. Em uma VM, execute sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt. No Kubernetes, execute clicklink clctl init --signed-cert client.crt --chain ca-chain.crt --target helm --target-namespace <connector-namespace> --values clicklink-values.yaml; a execução preparada imprime uma sequência equivalente de kubectl patch seguida de helm upgrade --install. Apenas o CSR trafega; a private key nunca sai do seu ambiente. No Kubernetes, o --chart aceita um nome de chart resolvido por meio de --chart-repo, uma referência oci://, uma URL direta ou um arquivo compactado ou diretório local. O --chart-version assume por padrão a própria versão da CLI, de modo que o binary e o chart avançam juntos. Para servir imagens a partir do seu próprio registry, espelhe a imagem de container e defina image.repository no values overlay. Se o seu caminho de egress apresentar uma private CA ao connector, passe --api-private-ca. O connector passa então a verificar o seu connector endpoint com base nas raízes do sistema e na CA chain do pacote de inscrição. O instalador também funciona a partir de um mirror: hospede os release artifacts e o install.sh no seu próprio mirror e aponte para ele com CLICKLINK_MIRROR_URL.

​
Download e verificação manuais

Se preferir não usar pipe para executar o instalador, baixe e verifique o lançamento manualmente. O bloco detecta sua plataforma e arquitetura; execute-o como está no macOS ou Linux, amd64 ou arm64:
Verifique a assinatura com o cosign antes de extrair os arquivos:
Em uma estação de trabalho (para instalações no Kubernetes), extraia o tarball e instale o binary:
Em uma VM, extraia o tarball e execute sudo ./install.sh no diretório extraído. Ao lado dos release artifacts, ele realiza a mesma instalação no host que --host.

​
Se algo falhar

Execute novamente o mesmo comando. O init é idempotente: novas execuções convergem para o mesmo estado, preservam sua configuração existente e os arquivos preparados e ignoram o trabalho já concluído. Quando um passo falha no meio do processo, a CLI imprime os comandos de recuperação exatos; eles podem ser repetidos com segurança. Se a inscrição for recusada, é porque o token já foi utilizado, é inválido ou expirou. Para um token já utilizado, execute novamente com --handoff handoff.yaml, que existe até o passo de limpeza. Caso contrário, solicite um novo token ao seu account team. Se a inscrição falhar com um erro de transporte, execute novamente o mesmo comando. Uma nova execução recusada significa que a primeira tentativa consumiu o token, então solicite um novo. Se o modo managed for recusado porque o cluster não é EKS, execute novamente com --no-managed para instalar sem o executor. Em uma VM, um kubeconfig cujo contexto atual aponta para outro lugar também é recusado: troque de contexto com kubectl config use-context e execute novamente. Se o grant do executor não puder ser aplicado:
  • Em uma VM, o init não falha. Ele prepara o pacote e imprime um aviso com o comando exato a ser executado a partir de um kubeconfig que tenha privilégios de administrador do cluster. O preflight de verificação reporta o estado do executor como ele está. Execute o comando impresso e, em seguida, execute novamente o mesmo comando init para verificar:
  • No Kubernetes, um grant recusado interrompe o init antes que o chart seja implantado, porque o executor faz o bind à ServiceAccount concedida e não consegue iniciar sem ela. O overlay preparado, os Secrets e a CSR são mantidos, e o init exibe os dois comandos que devem ser executados a partir de um host com permissões de admin do cluster. Execute-os e, em seguida, rode novamente o mesmo comando init para continuar:
--force é uma redefinição explícita; uma retentativa de rotina não precisa dele. Ele sobrescreve a config ou o values overlay mantidos, regenera a client key e substitui um certificado de cliente não expirado (um 409 do endpoint de assinatura significa que já existe um). Ele preserva o UUID do cluster do connector e sua postura de modo managed. Reexecuções não assistidas mantêm a postura e, em um terminal, o prompt assume esse valor por padrão, a menos que você passe --managed ou --no-managed. Use --force para rotacionar credenciais ou substituir um certificado; consulte operações para o modelo completo de reexecução e recuperação.