Set up docs MCPO conector é distribuído como um único binário chamado clicklink; os comandos são executados por meio de clicklink clctl. Esta página aborda os comandos usados durante a instalação e a operação diária. Execute qualquer comando com --help para ver o texto completo da ajuda. As flags nas subárvores troubleshoot e preflight também podem ser fornecidas por variáveis de ambiente CLCTL_* (nomeadas na saída de ajuda de cada flag) ou em ~/.clicklink/clctl.yaml.
clicklink clctl init
Inicializa o conector usando um token de inscrição, um pacote de inscrição salvo ou um certificado assinado fora de banda. Uma única execução prepara a configuração, provisiona o acesso ao ClickHouse, obtém o certificado mTLS do cliente, faz a implantação (Chart do Helm ou unidades systemd) e verifica a integridade. É seguro executar novamente: a configuração e o UUID do cluster são preservados, as credenciais são substituídas atomicamente e uma chave de cliente existente é reutilizada, a menos que você use --force. Consulte onboarding para conhecer o fluxo completo.
Pontos de entrada
Exatamente um dos três pontos de entrada é obrigatório; eles são mutuamente exclusivos.
| Flag | Descrição |
|---|---|
--enroll <url> |
O fluxo padrão. Usa o endpoint do conector da sua organização (https://<subdomain>.<connector domain>), resgata um token de inscrição de uso único (solicitado sem eco no terminal ou, caso contrário, lido da primeira linha de stdin), grava o pacote resultante em handoff.yaml (modo 0600) e continua como --handoff handoff.yaml. O token nunca passa pela linha de comando, pelo disco nem pelos logs. |
--handoff <path> |
Inicializa a partir de um pacote de inscrição salvo. Execuções subsequentes e a recuperação usam esta opção quando handoff.yaml já existe. |
--signed-cert <path> |
Fase 2 do fluxo isolado da internet: instala um certificado de cliente assinado fora de banda e conclui a instalação em etapas. Opcionalmente, --chain <path> substitui a cadeia de CA correspondente. |
Flags comuns
| Flag | Descrição |
|---|---|
--target <shape> |
Tipo de implantação: systemd (padrão; inicializa a VM atual) ou helm (prepara o Chart do Helm clicklink-connector a partir de uma estação de trabalho com um kubeconfig). |
--instance <spec> |
Instância do ClickHouse como pares key=value separados por vírgulas (name, host, port, secure, database, namespace, cluster); pode ser repetida. Ignora os prompts interativos da instância. |
--operators <emails> |
E-mails dos operadores autorizados a abrir sessões de suporte; habilita o gateway de sessões e ignora o prompt. |
--no-gateway |
Desabilita o gateway de sessões (sem sessões gerenciadas por OIDC); ignora o prompt. Em uma VM, o usuário root no host ainda pode gerenciar sessões pelo arquivo de sessão local. |
--force |
Sobrescreve uma configuração ou sobreposição existente e gera novamente a chave do cliente; também confirma a substituição de um certificado autoassinado ainda não expirado. O UUID do cluster é preservado mesmo com --force. |
--skip-provision |
Apenas preparação: ignora o provisionamento de acesso ao ClickHouse por função (e, no destino systemd, a habilitação e a verificação da unidade). Execute clicklink clctl {scraper,troubleshoot} access provision separadamente. |
--ch-user-suffix <suffix> |
Sufixo opcional para os nomes de usuário provisionados do ClickHouse (pcm_scraper passa a ser pcm_scraper_<suffix>), permitindo que uma segunda implantação do conector compartilhe uma instância sem conflitar com os usuários da primeira. |
--ch-admin-password-stdin |
Lê a senha de administrador do ClickHouse do stdin quando o provisionamento SQL exige uma; em execuções no terminal, a senha é solicitada. |
Flags de assinatura (somente na fase 1)
| Flag | Descrição |
|---|---|
--no-auto-sign |
Apenas na fase: ignora a assinatura automática da CSR pelo endpoint de inscrição, para fluxos de assinatura isolados da internet ou fora de banda. |
--sign-endpoint <url> |
Substitui o endpoint de assinatura de inscrição (padrão: derivado do endpoint do pacote com a inserção do rótulo DNS enroll). Deve ser uma URL HTTPS. |
Flags exclusivas do Kubernetes
Válidas apenas com --target helm.
| Flag | Descrição |
|---|---|
--target-namespace <ns> |
Espaço de nomes em que o Chart do Helm é instalado e seus Secrets são criados (padrão: clicklink; solicitado no terminal). |
--instance-namespace <ns> |
Espaço de nomes da instância ClickHouse de destino; inicializa a detecção de Service nativo e os prompts da instância. |
--storage-class <name> |
StorageClass do volume de estado do solucionador de problemas (padrão: a StorageClass padrão do cluster; solicitada ou obrigatória quando o cluster não define nenhuma). |
--values <path> |
Caminho da sobreposição de values preparada (padrão: clicklink-values.yaml). |
--chart <ref> |
Chart do Helm a implantar: um nome resolvido em --chart-repo ou uma referência direta oci://, URL ou local para instalações espelhadas (padrão: clicklink-connector). |
--chart-repo <url> |
Repositório Helm em que o nome do Chart do Helm é resolvido (padrão: https://releases.clicklink.clickhouse.com/charts); ignorado para referências diretas em --chart. |
--chart-version <ver> |
Versão do Chart do Helm a implantar (padrão: a versão de lançamento deste binário). |
--ch-pod <ref> |
Pod do Kubernetes do ClickHouse para as etapas de provisionamento no pod, como nome ou seletor de rótulo k=v (padrão: um pod em execução que dá suporte ao Service de cada instância). |
--api-private-ca |
O endpoint da API usa um certificado emitido pela CA do pacote de registro: prepara api.tls.caFile apontando para a cadeia de CAs montada, em vez das raízes do sistema. |
Flags exclusivas para VM
Válidas apenas com --target systemd.
| Flag | Descrição |
|---|---|
--server <url> |
URL do servidor da API do Kubernetes para o qual os pacotes de acesso apontam (padrão: kubeconfig deste host; caso contrário, será solicitado). |
--ca-data <base64> |
certificate-authority-data em Base64 para --server (padrão: kubeconfig deste host; caso contrário, será solicitado). |
Conflitos de flags
--handoff,--enrolle--signed-certsão mutuamente exclusivos; exatamente um é obrigatório.- As flags exclusivas do Kubernetes são rejeitadas, a menos que
--target helmseja usado;--servere--ca-datasão rejeitados com--target helm(o fluxo do Helm lê o kubeconfig da estação de trabalho). --no-auto-signe--sign-endpointsão mutuamente exclusivos, e ambos (além de--api-private-ca) são rejeitados com--signed-cert.--operatorse--no-gatewaysão mutuamente exclusivos.--skip-provisionrejeita--ch-pod,--ch-user-suffix,--server,--ca-datae--ch-admin-password-stdin(nada é provisionado).
clicklink clctl preflight
Executa o conjunto de verificações do conector, agrupadas por categoria: configuração, arquivos, rede, clickhouse, systemd, acesso, disco e redação. Cada verificação informa aprovação, aviso, falha ou ignorada. O código de saída 0 indica que todas as verificações foram aprovadas (os avisos não bloqueiam); o código de saída 2 indica que uma ou mais verificações falharam.
Por padrão, o comando é executado localmente. Com --k8s-namespace, ele executa o binário do conector no pod por meio de kubectl exec e gera o relatório localmente (as verificações de systemd são sempre ignoradas em pods). Com as flags do canal remoto, ele executa o binário instalado em uma VM remota.
| Flag | Descrição |
|---|---|
--config <path> |
Caminho para o arquivo de configuração do conector; em um destino remoto, o caminho nesse host. |
--output <fmt>, -o |
Formato de saída: text (padrão) ou json. |
--timeout <dur> |
Tempo limite geral para todas as verificações (padrão: 30s). |
--skip-systemd |
Ignora verificações do estado da unidade do systemd (hosts que não usam systemd). |
--k8s-namespace <ns> |
Espaço de nomes do Chart do Helm do conector; executa o preflight no pod do conector por meio de kubectl exec. |
--k8s-component <name> |
Pod do conector no qual executar: scraper (padrão) ou troubleshooter. |
--k8s-pod <ref> |
Nome do pod ou substituição do seletor de rótulo k=v (padrão: os rótulos de componente do Chart do Helm). |
--k8s-container <name> |
Contêiner no qual executar o comando exec (padrão: o nome do componente). |
As flags --k8s-* e as flags do canal remoto são mutuamente exclusivas; escolha um destino.
clicklink clctl troubleshoot session
Habilita, desabilita e inspeciona a sessão de suporte: o período limitado durante o qual o solucionador de problemas aceita comandos. Quando não há sessão ativa, o daemon recusa todos os comandos, mesmo que o WebSocket esteja conectado. Consulte sessões de suporte.
Os comandos operam em um de dois modos:
- Arquivo local (padrão): lê e grava o arquivo de estado da sessão no host em que o solucionador de problemas é executado (o padrão é
/var/lib/clicklink/session.json). - Gateway: com
--gateway-url, obtém um token de ID OIDC e, a partir da sua estação de trabalho, chama o gateway de sessão do solucionador de problemas.
| Flag | Descrição |
|---|---|
--session-file <path> |
Caminho do arquivo de estado da sessão (o padrão é /var/lib/clicklink/session.json). |
--config <path> |
Arquivo de configuração do conector; determina o caminho do arquivo de sessão a partir da seção troubleshooter. |
--gateway-url <url> |
URL base do gateway de sessão. Quando definida, o comando obtém um token Bearer OIDC e chama o gateway em vez de acessar o arquivo de estado local. Mutuamente exclusiva com --session-file e --config. |
--gateway-audience <aud> |
Claim de audiência ao qual o token OIDC está vinculado (o padrão é clicklink-clctl, que corresponde ao padrão do próprio gateway). Defina-a apenas se a audiência do gateway tiver sido reconfigurada. |
--gateway-issuer <url> |
Emissor OIDC que o gateway valida. Se estiver vazio, seleciona o fluxo do Google; defina-o junto com --oidc-client-id para executar o fluxo de código do dispositivo em um provedor de identidade diferente do Google. |
--oidc-client-id <id> |
ID de cliente OIDC público para o fluxo de código do dispositivo, registrado em --gateway-issuer com a concessão de dispositivo habilitada. |
--token-file <path> |
Arquivo que contém um token de ID OIDC pré-gerado, usado como token Bearer e que ignora os demais provedores de token. |
--gateway-ca <path> |
Bundle de CA que verifica o certificado do gateway (certificado fornecido por você). Quando não definido, é usado um certificado fixado via gateway trust; um gateway autossinado sem fixação falha de modo seguro. |
habilitar sessão
| Flag | Descrição |
|---|---|
--duration <dur> |
Por quanto tempo a sessão permanece ativa (padrão: 4h; máximo: 24h). |
--reason <text> |
Motivo opcional em texto livre registrado com a sessão (até 256 caracteres). |
--user <name> |
Identidade do operador a ser registrada no modo de arquivo local; por padrão, usa $SUDO_USER ou $USER. No modo gateway, o e-mail atestado pelo token é a fonte autorizada. |
A habilitação falha se já houver uma sessão ativa; primeiro, desabilite-a ou aguarde a expiração.
desativar sessão
Desativa a sessão imediatamente. Não tem efeito quando não há nenhuma sessão ativa.
status da sessão
Mostra se a sessão está ativa, quem a habilitou e quando expira. --output (-o) seleciona table (padrão) ou json.
No Kubernetes, acesse o gateway por meio de um redirecionamento de porta:
kubectl -n <connector-namespace> port-forward \
statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
--gateway-url http://localhost:8443 \
--duration 1h --reason "support ticket 1234"clicklink clctl troubleshoot gateway trust
Em uma VM, o gateway de sessão usa um certificado TLS autossinado. Este comando registra a impressão digital SHA-256 do certificado em ~/.clicklink/clctl.yaml para que os comandos session possam verificá-lo; se uma impressão digital fixada deixar de corresponder, a operação falhará de forma segura. A confiança é estabelecida fora de banda de uma destas duas formas:
- Com as flags do canal remoto, o certificado é lido diretamente da VM pelo canal já autenticado e fixado.
- Sem um canal, passe
--gateway-fingerprintcom o valor SHA-256 registrado pelo conector ao gerar o certificado; o certificado obtido só será fixado se corresponder. A omissão da flag exibe a impressão digital apresentada sem fixar nada.
| Flag | Descrição |
|---|---|
--gateway-url <url> |
URL base do gateway no qual confiar (obrigatória), por exemplo, https://<vm-host>:8443. |
--gateway-fingerprint <sha256> |
Impressão digital SHA-256 esperada do log do conector, verificada antes da fixação. Dois-pontos e diferenças entre maiúsculas e minúsculas são ignorados. |
--remote-cert-file <path> |
Caminho do certificado do gateway na VM, lido pelo canal (padrão: /var/lib/clicklink/gateway/tls/server.crt). |
clicklink clctl troubleshoot gateway trust \
--gateway-url https://<vm-host>:8443 \
--gateway-fingerprint <sha256-from-connector-log>No Kubernetes, o pinning não é usado: exponha o gateway por meio de uma Entrada com um certificado emitido por uma CA ou use o redirecionamento de porta.
clicklink clctl troubleshoot audit tail
Exibe as últimas entradas do log de auditoria do solucionador de problemas: JSON delimitado por quebras de linha, uma entrada para cada comando que o daemon aceitou ou bloqueou. O comando abre o log em modo somente leitura e nunca o modifica.
| Flag | Descrição |
|---|---|
--lines <n>, -n |
Número de entradas finais a exibir (padrão: 50). |
--path <path> |
Caminho para o arquivo de log de auditoria (padrão: /var/log/clicklink/troubleshoot-audit.log). |
A imagem de runtime do conector não inclui um shell; portanto, no Kubernetes, este comando é o leitor compatível:
kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
/clicklink clctl troubleshoot audit tailProvisionamento de acesso
clicklink clctl scraper access provision e clicklink clctl troubleshoot access provision criam e, com --force, rotacionam o pacote de acesso por instância de um componente: o usuário do ClickHouse com acesso somente leitura e suas permissões, além da ServiceAccount do Kubernetes, RBAC e token usados pelo componente. init executa essa operação inline durante a instalação; os comandos standalone permitem reexecutá-la e rotacionar credenciais.
| Flag | Descrição |
|---|---|
--instance <name> |
Nome da instância na configuração (obrigatório). |
--server <url> |
URL do servidor da API do Kubernetes (obrigatório). |
--ca-data <base64> |
Certificado da CA do cluster em Base64 para o kubeconfig gerado. |
--config <path> |
Arquivo de configuração do conector do qual a instância será lida. |
--target <shape> |
systemd (padrão: envia o pacote para uma VM por um canal remoto ou o gera localmente com --provider local) ou helm (envia o pacote como um Secret do Kubernetes para o Chart do Helm). |
--target-namespace <ns> |
Espaço de nomes em que o Secret do pacote será criado (obrigatório com --target helm). |
--instance-namespace <ns> |
(--target helm) Espaço de nomes da instância ClickHouse de destino. |
--force |
Sobrescreve um pacote existente: usado para reexecução e rotação de credenciais. |
--secret-name <name> |
Substitui o nome do Secret do pacote (padrão clicklink-connector-<component>-access-<instance>). |
--output-dir <path> |
(--target helm ou --provider local) Diretório raiz em que o pacote será criado. |
--ch-admin-user <name> |
Usuário administrador do ClickHouse para aplicar permissões (padrão default). |
--ch-admin-password-stdin |
Lê a senha do administrador do ClickHouse de stdin. |
--ch-user-suffix <suffix> |
Sufixo opcional para o nome de usuário provisionado do ClickHouse. |
--ch-user-via <mode> |
Como o usuário do ClickHouse é provisionado: sql (padrão; aplica as permissões geradas como --ch-admin-user) ou cr (grava o usuário no recurso personalizado da instância, para instâncias gerenciadas por operador sem administrador com acesso SQL). |
--apply-ch-grants |
(--target helm) Aplica as permissões geradas dentro do pod via kubectl exec, em vez de deixá-las para você aplicar. |
--ch-pod <ref>, --ch-pod-namespace <ns>, --ch-container <name> |
(--target helm com --apply-ch-grants ou --ch-user-via cr) Seleciona o pod do Kubernetes do ClickHouse e o contêiner no qual executar o comando. |
--token-duration <dur> |
Ciclo de vida do token da ServiceAccount (padrão 2160h, 90 dias; o EKS limita as concessões a 24 horas). |
--skip-restart |
Não reinicia o componente após o provisionamento. |
--dry-run |
Exibe o plano e encerra; não realiza gravações no Kubernetes, em canais remotos ou no ClickHouse. |
Rotacione as credenciais de uma instância para um componente:
clicklink clctl scraper access provision --target helm \
--target-namespace <connector-namespace> \
--instance <instance-name> --instance-namespace <clickhouse-namespace> \
--server <kubernetes-api-server-url> \
--apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
--forceFlags de canal remoto
preflight, gateway trust e access provision aceitam um conjunto compartilhado de flags que define como acessar uma VM de destino:
| Flag | Descrição |
|---|---|
--provider <name> |
Canal de execução: ssh, aws (SSM) ou gcp (IAP) para VMs remotas, ou local quando executado na própria VM de destino. É inferido pelas flags específicas de cada provedor quando não definido explicitamente; local nunca é inferido. |
--ssh-host <host>, --ssh-user <user>, --ssh-port <port>, --ssh-identity-file <path> |
Detalhes da conexão SSH (--provider ssh); usuário, porta e chave assumem como padrão as configurações de SSH. |
--instance-id <id>, --region <region>, --profile <name> |
Instância EC2, região e perfil de configuração compartilhada para SSM (--provider aws). |
--project <id>, --zone <zone>, --instance-name <name> |
Projeto, zona e instância para tunelamento via IAP (--provider gcp). |