Pré-requisitos
- O endpoint do conector e o token de inscrição, fornecidos pelo ClickHouse durante o onboarding (consulte a Etapa 1).
- Tráfego de saída pela porta 443 para
https://<subdomain>.<connector-domain>ehttps://<subdomain>.enroll.<connector-domain>, além dereleases.clicklink.clickhouse.come do Amazon ECR Public durante a instalação. Se algum deles estiver inacessível, consulte instalações isoladas da internet e espelhadas. - Um listener nativo do ClickHouse acessível a partir do local onde o conector é executado: seguro (9440) ou em texto simples (9000), detectado automaticamente no Kubernetes.
- Acesso de administrador ao ClickHouse para provisionamento: um usuário
defaultsem senha, uma senha (solicitada ou fornecida com--ch-admin-password-stdin) ou uma instância gerenciada por operador, caso em que o provisionamento passa a usar injeção de CR e não exige senha. - cosign em todo local onde você baixar artefatos de lançamento. O instalador sempre verifica o checksum SHA-256, adiciona a verificação de assinatura com cosign quando ele está instalado e se recusa a prosseguir sem ela se você definir
CLICKLINK_REQUIRE_COSIGN=1.
- Qualquer cluster do Kubernetes compatível.
- Um kubeconfig que permita criar e ler o espaço de nomes do conector, aplicar Secrets, executar comandos nos pods do Kubernetes do ClickHouse (o provisionamento executa
clickhouse-clientno pod), criar ServiceAccounts, Roles e RoleBindings e instalar o chart. - Uma StorageClass padrão, ou uma classe a ser informada com
--storage-class; o troubleshooter mantém o estado em um PersistentVolumeClaim. - Acesso para baixar imagens: os nós do cluster devem conseguir baixar a imagem pública do ECR ou uma imagem espelhada hospedada por você.
- Qualquer host Linux com systemd, amd64 ou arm64. As builds para Linux são executadas no modo FIPS.
- Acesso root para o instalador e o
init. - Portas livres 8080, 8082 e 8084 (integridade) e 9090, 9092 e 9094 (métricas), além da 8443 quando o gateway de sessão de suporte estiver habilitado.
- Acesso de administrador a um servidor da API do Kubernetes para provisionamento, fornecido por um kubeconfig no host, por
--servere--ca-dataou nos prompts. Os pacotes de acesso são vinculados a ServiceAccounts do Kubernetes em ambos os destinos.
--skip-provision é a única forma de contornar o requisito do Kubernetes e serve apenas para a etapa de preparação: ele ignora o provisionamento de usuários do ClickHouse e, em uma VM, a ativação e a verificação da unidade; portanto, não produz um conector em execução por si só.Instale e faça o registro
1
Obtenha o endpoint do conector e o token de registro
Durante o onboarding, o ClickHouse fornece o endpoint do conector e um token de inscrição de uso único. O endpoint tem o seguinte formato:O token é de uso único e expira rapidamente; portanto, execute a inscrição logo após recebê-lo. Trate-o como um segredo: a CLI o lê em um prompt oculto (ou na primeira linha de stdin), nunca em argumentos de linha de comando, disco ou logs. Se o token expirar antes de ser usado, entre em contato com a equipe de conta da ClickHouse para obter um novo.
2
Instale e verifique a CLI
Um único comando instala um binário Para uma instalação em VM, execute o mesmo script no host com Ambas as opções aceitam
clicklink verificado: ele detecta sua plataforma e arquitetura (macOS ou Linux, amd64 ou arm64), baixa o lançamento atual, verifica o checksum SHA-256 e, se o cosign estiver instalado, a assinatura do lançamento, e instala o binário no seu PATH. Para instalar no Kubernetes, execute-o em qualquer estação de trabalho com acesso ao cluster via kubeconfig:--host. Após o download ser verificado, ele também cria o usuário de sistema clicklink, os diretórios /etc/clicklink, /var/lib/clicklink e /var/log/clicklink, as unidades do systemd e um /etc/clicklink/redaction-patterns.yaml padrão (preservado se já existir), para que a próxima etapa comece diretamente pelo registro:--version vX.Y.Z para fixar uma versão, e é seguro executá-las novamente: a instalação no host faz backup do binário anterior e preserva sua configuração em uso. Para inspecionar o script antes de executá-lo ou baixar e verificar o tarball da versão manualmente, consulte download e verificação manuais.3
Registrar e instalar o conector
A inscrição é feita com um único comando. Ele resgata seu token, provisiona o acesso ao ClickHouse, obtém um certificado de cliente assinado, instala o conector e verifica tudo de ponta a ponta.
- Kubernetes
- VM Linux
Na sua estação de trabalho, execute:Cole o token de inscrição no prompt oculto. Em seguida, a CLI solicitará:Repita
- o espaço de nomes do conector (o padrão é
clicklink) - o espaço de nomes em que suas instâncias do ClickHouse são executadas
- os detalhes de conexão da instância, preenchidos com base no serviço ClickHouse detectado
- uma StorageClass, somente se o cluster não tiver nenhuma marcada como padrão
- a configuração das sessões de suporte e, se ativadas, a allowlist de e-mails dos operadores
- a senha de administrador do ClickHouse, somente se o provisionamento via SQL precisar dela
handoff.yaml no diretório de trabalho), prepara a sobreposição de valores do Helm clicklink-values.yaml, cria o espaço de nomes, aplica os Secrets clicklink-hmac e clicklink-mtls, provisiona usuários do ClickHouse somente leitura para cada instância (selecionando automaticamente concessões SQL ou injeção de CR para instâncias gerenciadas por operador), gera uma chave privada e uma CSR e faz com que o ClickHouse assine o certificado de cliente, instala a release Helm clicklink-connector com o cliente Helm integrado (sem necessidade do binário helm) e verifica a integridade.Para execuções não assistidas, responda aos prompts usando flags. Use o pacote salvo como ponto de entrada, pois, em execuções sem terminal, --enroll lê o token de inscrição da primeira linha de stdin e consumiria a senha redirecionada:--instance para cada instância do ClickHouse. Passe --no-gateway em vez de --operators para desativar as sessões de suporte; as duas flags são mutuamente exclusivas.4
Verifique se a instalação foi bem-sucedida
init verifica a instalação antes de reportar sucesso. No Kubernetes, ele consulta o endpoint /livez de cada componente habilitado por até cinco minutos e, quando o gateway da sessão de suporte está habilitado, também exige que o gateway responda a probes não autenticadas com 401. Em uma VM, ele aguarda o /livez de cada daemon e executa a suíte completa de preflight: configuração, arquivos, conflitos de porta, acessibilidade de rede, conectividade com o ClickHouse, estado da unidade do systemd, acesso por componente, disco e padrões de redação.Para confirmar manualmente no Kubernetes:Running e prontos.Para confirmar manualmente em uma VM:0 quando todas as verificações são concluídas com êxito e 2 em caso de falha, exibindo as verificações que falharam.5
Limpar
O pacote de inscrição O conector em execução mantém sua própria cópia das credenciais, portanto nenhuma operação depende do arquivo: upgrades e alterações de configuração nunca precisam dele e, se você precisar executar
handoff.yaml (gravado no diretório de trabalho com o modo 0600) permite que novas execuções e a recuperação durante a instalação não precisem de um segundo token. Ele contém o Secret da API do connector em texto simples; portanto, exclua-o assim que a instalação for verificada:init novamente no futuro, solicite um novo token de inscrição à equipe de contas da ClickHouse e execute init --enroll --force.Instalações isoladas da internet e espelhadas
clicklink clctl init --handoff <bundle-file> em vez de --enroll. --handoff substitui apenas o resgate do token: a assinatura do certificado ainda ocorre pelo endpoint de inscrição. Portanto, use-o sozinho quando esse endpoint puder ser acessado de onde você executa init.
Assinatura de certificado fora de banda. Quando o endpoint de inscrição não puder ser acessado de onde você executa init, adicione --no-auto-sign: init prepara tudo e grava clicklink.csr. Envie a CSR ao ClickHouse por meio da equipe responsável pela sua conta e, em seguida, conclua a instalação com o certificado e a cadeia retornados: sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt em uma VM ou o comando completo de conclusão exibido pela execução preparada no Kubernetes (incluindo --target helm). Apenas a CSR é transferida; a chave privada nunca sai do seu ambiente.
No Kubernetes, --chart aceita um nome de chart resolvido por --chart-repo, uma referência oci://, uma URL direta ou um arquivo ou diretório local. Por padrão, --chart-version usa a própria versão da CLI, para que o binário e o chart sejam movidos juntos. Para disponibilizar imagens a partir do seu próprio registry, espelhe a imagem de contêiner e defina image.repository na sobreposição de values. Se o tráfego de egress apresentar uma CA privada ao conector, passe --api-private-ca para que o endpoint da API seja verificado usando a cadeia de CA do pacote de inscrição, em vez do armazenamento de confiança do sistema.
O instalador também funciona a partir de um espelho: hospede os artefatos do lançamento e install.sh em seu próprio espelho e use CLICKLINK_MIRROR_URL para apontar para ele.
Download e verificação manuais
sudo ./install.sh no diretório extraído; ao lado dos artefatos do lançamento, ele realiza a mesma instalação no host que --host.
Se algo falhar
init é idempotente: novas execuções convergem para o mesmo estado, preservam a config e os arquivos preparados existentes e pulam o trabalho concluído. Quando uma etapa falha parcialmente, a CLI exibe os comandos de recuperação exatos para a sua situação, e é seguro repeti-los.
Se a inscrição for recusada, o token já terá sido usado (execute novamente com --handoff handoff.yaml, que existe até a etapa final de limpeza) ou será inválido ou estará expirado (entre em contato com a equipe de conta da ClickHouse para obter um novo token). Se a inscrição falhar com um erro de transporte, o token não foi consumido; execute novamente o mesmo comando.
--force é uma redefinição explícita, não uma nova tentativa rotineira: ele substitui a config preservada ou a sobreposição de values, gera novamente a chave do client e substitui um certificado de client ainda válido (um 409 do endpoint de assinatura indica que já existe um). O UUID do cluster do conector é preservado mesmo com --force, portanto, um conector reinicializado mantém sua identidade. Use-o ao alternar credentials ou substituir um certificado e consulte operations para conhecer o modelo completo de nova execução e recuperação.