Referência da CLI - ClickHouse Documentation

O 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, scraper, preflight, executor, instances create e platform, além das globais --endpoint e --cluster, também podem vir de variáveis de ambiente CLCTL_* (nomeadas na saída de ajuda de cada flag) ou de ~/.clicklink/clctl.yaml. A flag global -v registra em log as requisições à API de administração feitas por um comando; -vv adiciona os corpos das requisições. Os comandos instances e commands, além de executor teardown, leem a API local do executor. Duas flags globais a selecionam: --endpoint <url> (padrão http://127.0.0.1:9999, env CLCTL_ENDPOINT) e --cluster <name> (env CLCTL_CLUSTER), que indica o nome do cluster gerenciado quando algum comando precisa dele. No Kubernetes, abra primeiro um kubectl port-forward para a Implantação do executor; consulte serviços gerenciados.

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. Com --managed, também habilita o executor para o cluster EKS que ele detecta e concede o acesso cluster-wide do executor. É seguro executar novamente: o init preserva a configuração e o UUID do cluster, substitui as credenciais atomicamente e reutiliza uma chave de cliente existente, a menos que você use --force. Consulte onboarding para conhecer o fluxo completo e serviço gerenciado para saber o que o executor faz.

Pontos de entrada

Exatamente um ponto de entrada é obrigatório.

Flag	Descrição
`--enroll <url>`	O fluxo padrão. Usa o endpoint do seu conector (`https://<subdomain>.<connector-domain>`) e resgata um token de inscrição de uso único, solicitado sem eco no terminal ou 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>`	Formato da implantação: `systemd` (padrão; faz o bootstrap da VM em que você está) 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 que você mesmo opera, informada como pares `key=value` separados por vírgula (`name`, `host`, `port`, `secure`, `database`, `namespace`, `cluster`); pode ser repetida. Ignora os prompts interativos de instância. Recusada no modo gerenciado em Kubernetes: uma implantação separada, instalada com `--no-managed`, é quem observa essa instância.
`--env <label>`	Rótulo de ambiente injetado em cada métrica emitida como `scraper.labels.env` (padrão: `production`). Informe `staging` para uma instalação de staging.
`--operators <emails>`	E-mails de operadores, separados por vírgula, autorizados a abrir sessões de suporte; habilita o gateway de sessão e dispensa o prompt.
`--no-gateway`	Desabilita o gateway de sessão (sem sessões gerenciadas por OIDC); dispensa o prompt. Em uma VM, o root do host ainda pode gerenciar sessões por meio do arquivo de sessão local.
`--managed`	Habilita o modo gerenciado: executa o executor para que o ClickHouse Cloud gerencie o ciclo de vida dos serviços ClickHouse neste cluster; dispensa o prompt. Requer um cluster Amazon EKS.
`--no-managed`	Mantém o modo gerenciado (o executor) desativado; dispensa o prompt.
`--from-terraform <path>`	Saídas de um módulo raiz do Terraform, no formato impresso por `terraform output -json` (`-` lê do stdin). Preenche `--cluster-name`, `--server` e `--ca-data` em uma VM ou, em Kubernetes, `--target-namespace`, além da função IRSA e do seletor de nós do overlay gerenciado. Uma flag que diverge do arquivo é recusada.
`--force`	Sobrescreve um config ou overlay existente e regenera a chave de cliente; também confirma a substituição de um certificado autossinado ainda não expirado. O UUID do cluster é preservado mesmo com `--force`.
`--skip-provision`	Apenas prepara: ignora o provisionamento de acesso ao ClickHouse por função (e, no target systemd, a habilitação e a verificação da unit). Execute `clicklink clctl {scraper,troubleshoot} access provision` separadamente. Com `--target helm`, a concessão do executor ainda é aplicada; em uma VM, ela também é ignorada.
`--ch-user-suffix <suffix>`	Sufixo opcional para os nomes de usuário do ClickHouse provisionados (`pcm_scraper` passa a ser `pcm_scraper_<suffix>`), para que uma segunda implantação do conector possa compartilhar uma instância sem conflitar com os usuários da primeira.
`--ch-admin-password-stdin`	Lê a senha do admin do ClickHouse a partir do stdin quando o provisionamento SQL precisa dela; em uma execução no terminal, a senha é solicitada por prompt.

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. Rejeitada com `--managed`: uma instalação gerenciada não registra nenhuma instância existente.
`--storage-class <name>`	StorageClass dos volumes de estado do solucionador de problemas e do executor (padrão: a StorageClass padrão do cluster; solicitada ou obrigatória quando o cluster não define nenhuma).
`--values <path>`	Caminho do overlay de values preparado (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 do seu conector usa um certificado emitido pela CA do pacote de inscrição: prepara `api.tls.caFile` apontando para a cadeia de CAs montada, que é anexada às raízes do sistema.
`--egress-cidrs <cidrs>`	CIDRs separados por vírgula do endpoint do seu conector para a NetworkPolicy de negação padrão do Chart do Helm: prepara-a habilitada com esses valores em `networkPolicy.allowEgressCIDRs` (solicitado no terminal no modo gerenciado). Sem eles, a policy é preparada desabilitada para que você a habilite depois.
`--platform-bundle <path\|from-api>`	Manifesto de plataforma renderizado (o arquivo lido por `clicklink clctl platform approve --bundle`) ou `from-api` para obter, pela API do conector, o manifesto que o ClickHouse Cloud renderizou para a sua infraestrutura inscrita. Com `--managed` e `--from-terraform`, instala, caso ainda não existam, o Karpenter e seus pools de nós, o controlador AWS Load Balancer, a StorageClass `gp3-encrypted` e os componentes fixados pelo pacote. Consulte Terraform na AWS.
`--server-instance-families <families>`	Requer `--platform-bundle`. Famílias de instâncias EC2 arm64 com armazenamento de instância e NVMe local, separadas por vírgula, para o NodePool `clickhouse-server` (padrão: `m7gd`). As flags de pool afetam apenas novos NodePools; os pools existentes não são modificados.
`--keeper-instance-families <families>`	Requer `--platform-bundle`. Famílias de instâncias EC2 arm64, separadas por vírgula, para o NodePool `clickhouse-keeper` (padrão: `m7g`).
`--server-pool-limits <limits>`	Requer `--platform-bundle`. Limites de recursos `key=quantity`, separados por vírgula, para o NodePool `clickhouse-server` (padrão: `cpu=1000,memory=4Ti`).
`--keeper-pool-limits <limits>`	Requer `--platform-bundle`. Limites de recursos `key=quantity`, separados por vírgula, para o NodePool `clickhouse-keeper` (padrão: `cpu=100,memory=400Gi`).

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).
`--cluster-name <name>`	Nome do cluster EKS controlado pelo modo gerenciado (padrão: o único cluster EKS no kubeconfig deste host; solicitado em um terminal).
`--no-instance`	Inicia com um registry de instances vazio e ignora os prompts de instance.

Conflitos de flags

--handoff, --enroll e --signed-cert são mutuamente exclusivos; exatamente um é obrigatório.
As flags exclusivas do Kubernetes são rejeitadas, a menos que --target helm seja usado; --server, --ca-data, --cluster-name e --no-instance são rejeitados com --target helm (o fluxo do Helm lê o kubeconfig da estação de trabalho e detecta a instância in-cluster).
--no-instance e --instance são mutuamente exclusivos.
--managed e --no-managed são mutuamente exclusivos, e --cluster-name é rejeitado com --no-managed. Com --target helm, --instance e --instance-namespace são rejeitados com --managed.
--no-auto-sign e --sign-endpoint são mutuamente exclusivos, e ambos (além de --api-private-ca, --managed, --no-managed e --cluster-name) são rejeitados com --signed-cert.
--platform-bundle exige --target helm, --managed e --from-terraform, e é rejeitado com --no-managed ou --signed-cert. As quatro flags de pool são rejeitadas sem --platform-bundle e recusadas quando os NodePools já existem.
--operators e --no-gateway são mutuamente exclusivos.
--skip-provision rejeita --ch-pod, --ch-user-suffix, --server, --ca-data e --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 pelo menos uma falhou. Por padrão, o comando é executado localmente. Com --k8s-namespace, ele executa o binário do conector no pod do Kubernetes por meio de kubectl exec e gera o relatório localmente (as verificações de systemd são sempre ignoradas em pods do Kubernetes). 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 Kubernetes do conector por meio de `kubectl exec`.
`--k8s-component <name>`	Pod do Kubernetes do conector no qual executar: `scraper` (padrão) ou `troubleshooter`.
`--k8s-pod <ref>`	Nome do pod do Kubernetes 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. Sem uma sessão ativa, o daemon recusa todos os comandos, mesmo que o WebSocket esteja conectado. Consulte sessões de suporte. Os comandos são executados 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.

Flags compartilhadas

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, o comando usa 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 comando lê o certificado da VM pelo canal já autenticado e o fixa.
Sem um canal, passe --gateway-fingerprint com o valor SHA-256 registrado pelo conector ao gerar o certificado; o comando só fixa o certificado obtido se ele 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`. Deve ser `https://`.
`--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. Ele abre o log em modo somente leitura.

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 tail

Provisionamento 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>`	Espaço de nomes da instância ClickHouse de destino; com ele, o comando não precisa de uma entrada no registro para `--instance`.
`--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 (padrão: `./<component>/` no diretório de trabalho para `helm`; o diretório de acesso do componente para `local`).
`--audit-log <path>`	Log de auditoria do provisionamento, em NDJSON, com acréscimo ao final (padrão `clctl-audit.log` ao lado do diretório de saída do pacote; `none` o desativa).
`--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 um componente para uma instância:

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> \
  --force

clicklink clctl executor access

init --managed aplica o grant cluster-wide do executor com suas credenciais. Quando isso não é possível, o init exibe os comandos que devem ser executados a partir de um kubeconfig com admin do cluster: apenas access apply em uma VM (o pacote já está preparado), ou access grant seguido de access apply no Kubernetes. Consulte onboarding.

executor access grant

Renderiza o pacote de acesso de abrangência de cluster do executor em <output-dir>/_cluster/: uma ServiceAccount, uma Função de cluster e uma ClusterRoleBinding, e uma ValidatingAdmissionPolicy que restringe a ServiceAccount aos espaços de nomes sob o prefixo de espaço de nomes do executor. Revise o RBAC renderizado antes de aplicá-lo.

Flag	Descrição
`--cluster`	Renderiza o pacote de abrangência de cluster (obrigatório para este uso; sem ele, o comando renderiza um pacote por serviço para `--instance`).
`--config <path>`	Arquivo de configuração do connector (variável de ambiente `CLCTL_EXECUTOR_CONFIG`).
`--sa-namespace <ns>`	Espaço de nomes principal da ServiceAccount do executor (padrão `clicklink-system`; o espaço de nomes do connector em uma instalação Kubernetes).
`--context <name>`	contexto do kubeconfig do cluster gerenciado, como em `prepare`.
`--server <url>`, `--ca-data <base64>`	URL do Kubernetes API server e CA a serem incorporados no kubeconfig (padrão: os do kube context).
`--output-dir <path>`	Raiz de saída (padrão `/etc/clicklink/access/executor`; variável de ambiente `CLCTL_EXECUTOR_OUTPUT_DIR`).
`--force`	Sobrescreve um pacote existente.
`--dry-run`	Exibe o plano sem gravar arquivos.

executor access apply

Aplica o pacote grant renderizado de abrangência de cluster: o Espaço de nomes de origem da ServiceAccount, a ServiceAccount, a Função de cluster e o ClusterRoleBinding, além da política de admission, e em seguida gera o token da ServiceAccount no pacote. Não registra nenhum serviço.

Flag	Descrição
`--cluster`	Aplica o pacote de abrangência de cluster a partir de `<output-dir>/_cluster/` (obrigatório para este uso).
`--config <path>`	Arquivo de configuração do connector (variável de ambiente `CLCTL_EXECUTOR_CONFIG`).
`--context <name>`	Contexto do kubeconfig do cluster gerenciado, assim como em `prepare`.
`--output-dir <path>`	Raiz de saída (padrão `/etc/clicklink/access/executor`; variável de ambiente `CLCTL_EXECUTOR_OUTPUT_DIR`).
`--token-duration <dur>`	Ciclo de vida do token da ServiceAccount (padrão `2160h`, 90 dias).
`--dry-run`	Exibe o que seria aplicado sem executar.

clicklink clctl executor access grant --cluster --sa-namespace <connector-namespace> --server <kubernetes-api-server-url> --output-dir <dir>
clicklink clctl executor access apply --cluster --output-dir <dir>

clicklink clctl executor prepare

Prepara tudo do seu lado que a criação de um managed service exige, em uma única execução idempotente que para na primeira falha. Ele escolhe ou valida o nome do serviço e cria os buckets de dados e de backup e a IAM role (ou verifica uma role fornecida por você). Em uma VM, ele também renderiza e aplica o pacote de acesso do executor para o espaço de nomes do serviço; no Kubernetes, ele pula o pacote porque o executor é executado com a ServiceAccount do seu pod. Em seguida, gera a senha do usuário default (exibida uma única vez) e grava o corpo de criação para instances create. Consulte managed services. Em uma VM, ele é executado no host do connector. Em uma instalação no Kubernetes, ele é executado em uma workstation com credenciais AWS e um contexto kube do cluster gerenciado. Essa workstation também precisa de uma cópia da configuração do connector (--config), de um redirecionamento de porta para a API local do executor e de um --output-dir gravável.

Flag	Descrição
`--config <path>`	Arquivo de configuração do connector (obrigatório; variável de ambiente `CLCTL_EXECUTOR_CONFIG`). O pacote de acesso é renderizado a partir dele, e o contexto kube deve corresponder ao seu `executor.cluster`.
`--instance <name>`	Nome do serviço (variável de ambiente `CLCTL_EXECUTOR_INSTANCE`). Padrão: um nome gerado, registrado em `<output-dir>/_prepare/<eks-cluster-name>.name` e retomado na execução seguinte.
`--new-name`	Ignora o nome registrado por uma execução anterior e escolhe um novo.
`--context <name>`	Contexto do kubeconfig do cluster gerenciado: um nome ou um pattern (uma correspondência é usada; várias abrem um prompt); variável de ambiente `CLCTL_CONTEXT`. Padrão: o único contexto; caso contrário, um picker.
`--server <url>`, `--ca-data <base64>`	URL e CA do Kubernetes API server a serem embutidos no kubeconfig do executor (padrão: os do contexto kube).
`--data-bucket <name>`, `--backup-bucket <name>`	Buckets a verificar ou criar (padrão `<cluster>-clickhouse-data-<rand>` e `<cluster>-clickhouse-backup-<rand>`).
`--role-name <name>`	Nome da IAM role (padrão `CH-S3-<instance>-<region>-00-Role`).
`--role-arn <arn>`	Use sua própria IAM role: verifica sua relação de confiança e seus grants no S3 e nunca cria nem modifica IAM.
`--restore-from <name>`	Serviço cujos backups este serviço restaura; a IAM role também recebe acesso de leitura ao bucket de backup dele.
`--region <region>`	Region da AWS (padrão: a region do cluster para o qual o contexto kube aponta).
`--token-duration <dur>`	Ciclo de vida do token da ServiceAccount (padrão `2160h`, 90 dias).
`--force`	Regenera um pacote de acesso completo em vez de reutilizá-lo.
`--output-dir <path>`	Raiz de saída (padrão `/etc/clicklink/access/executor`; variável de ambiente `CLCTL_EXECUTOR_OUTPUT_DIR`).
`--output <fmt>`	`text` (padrão) ou `json`. Nenhum dos dois contém a senha.
`--dry-run`	Executa todas as etapas em modo dry-run; nada é criado nem gravado.

clicklink clctl executor teardown

Remove o que o prepare criou para um serviço que o ClickHouse Cloud excluiu. Ou seja, o IAM role, o nome registrado e o registro do serviço no executor; em uma VM, também a Função de cluster e o ClusterRoleBinding do serviço, o pacote de acesso local e a entrada no registry. O executor deve estar em execução e o serviço deve estar terminated (ou stale); a execução é recusada enquanto o espaço de nomes do serviço ainda contiver um cluster ClickHouse. Os buckets criados pelo prepare, com seus dados e backups, são preservados, a menos que você solicite a exclusão, e os buckets preservados recebem a nova etiqueta clicklink:retained-from=<name>. O comando lê tudo antes de excluir qualquer coisa. Consulte excluir um serviço.

Flag	Descrição
`--instance <name>`	Nome do serviço (variável de ambiente `CLCTL_EXECUTOR_INSTANCE`).
`--config <path>`	Arquivo de configuração do connector (variável de ambiente `CLCTL_EXECUTOR_CONFIG`); lido de `/etc/clicklink/config.yaml` no host do connector quando omitido. Fornece `delete_instance_data`.
`--context <name>`	Contexto do kubeconfig do cluster gerenciado, como em `prepare`.
`--delete-data`	Exclui os dados do serviço mesmo quando `delete_instance_data` está desativado. Requer `--yes`.
`--delete-backups`	Exclui o bucket de backup e os backups nele contidos (preservados por padrão). Requer `--yes`.
`--yes`	Confirma `--delete-data` e `--delete-backups`; sem ele, a execução para após a etapa de registro e informa os nomes dos buckets que seriam esvaziados.
`--data-bucket <name>`, `--backup-bucket <name>`	Substituem os buckets no registro do executor (padrão: aqueles vinculados à função do serviço ou etiquetados para ele).
`--role-name <name>`	Nome do IAM role (padrão `CH-S3-<instance>-<region>-00-Role`).
`--region <region>`	Região da AWS (padrão: a do cluster).
`--namespace-prefix <prefix>`	Prefixo do espaço de nomes do serviço (padrão `ns-`); deve coincidir com uma config carregada.
`--output-dir <path>`	Raiz de saída (padrão `/etc/clicklink/access/executor`).
`--output <fmt>`	`text` (padrão) ou `json`.
`--dry-run`	Imprime o que seria removido e encerra sem excluir nada.

clicklink clctl instances

instances create

Envia uma criação preparada ao ClickHouse Cloud pelo endpoint do connector, usando as credenciais do próprio connector. A criação é habilitada por ambiente; veja criar um serviço. Exibe o nome falado atribuído pelo ClickHouse Cloud, o state e uma dica watch: que usa o nome do seu serviço. O corpo da criação vem do arquivo gravado pelo prepare ou da combinação das quatro flags --deployed-name, --data-bucket, --backup-bucket e --irsa-role-arn. Um retry com as mesmas entradas retorna a primeira criação.

Flag	Descrição
`--from-prepare <path>`	Corpo da criação gravado por `executor prepare` (`<output-dir>/_prepare/<instance>.create.json`), incluindo os hashes da senha do usuário `default`. Mutuamente exclusivo com `--deployed-name` e `--default-user-password-file`.
`--deployed-name <name>`, `--data-bucket <name>`, `--backup-bucket <name>`, `--irsa-role-arn <arn>`	As entradas preparadas, em forma de flags; obrigatórias em conjunto.
`--default-user-password-file <path>`	Arquivo que contém a senha do usuário `default` (primeira linha), para o caminho via flags. Se ausente, o comando gera uma senha e a exibe uma única vez; um retry deve então fornecê-la por meio desse arquivo, caso contrário o serviço mantém a primeira senha enquanto uma nova é exibida.
`--config <path>`	Arquivo de configuração do connector (variável de ambiente `CLCTL_EXECUTOR_CONFIG`; padrão `/etc/clicklink/config.yaml` quando presente). Fornece o endpoint, suas credenciais e a identity do ambiente.
`--connector-namespace <ns>`	Apenas no Kubernetes, quando este host não possui arquivos de configuração ou de credencial do connector: o espaço de nomes do connector cujo ConfigMap e Secrets os fornecem (padrão `clicklink`). Toda leitura do cluster é anunciada.
`--connector-configmap <name>`	ConfigMap que contém o `config.yaml` do executor nesse espaço de nomes (padrão `clicklink-connector-executor`).
`--hmac-secret-name <name>`, `--mtls-secret-name <name>`	Secrets que contêm as credenciais da API e o certificado do cliente quando os arquivos estão ausentes (padrões `clicklink-hmac` e `clicklink-mtls`). O par de certificados é mantido em memória.
`--context <name>`	Context do Kube para essas leituras (variável de ambiente `CLCTL_CONTEXT`); um pattern ou o picker interativo, como nos comandos `executor`.
`--idempotency-key <key>`	Chave que um retry reutiliza para obter de volta a primeira criação (padrão: derivada do ambiente e do nome do serviço).
`--wait`	Faz poll da API local do executor até que o serviço esteja `running`. Falha imediatamente se houver uma criação malsucedida para o nome ou quando o serviço passa a `terminating`, `terminated` ou `stale`.
`--wait-timeout <dur>`	Por quanto tempo `--wait` faz poll antes de falhar (padrão `30m`).

instances list

Imprime, em JSON, todos os serviços conhecidos pelo executor. --cluster <name> filtra por cluster gerenciado.

instances get

Exibe um serviço, em JSON, com o armazenamento com o qual foi criado. --name <name> é obrigatório, assim como o cluster: passe --cluster, defina CLCTL_CLUSTER ou informe-o em ~/.clicklink/clctl.yaml. Os três subcomandos abaixo enviam comandos diretamente à API local do executor, contornando o ClickHouse Cloud. Execute-os somente quando a equipe de conta solicitar. Cada um exige --name <name> e o cluster (--cluster, CLCTL_CLUSTER ou ~/.clicklink/clctl.yaml), e cada um exibe o comando em JSON. Passe o id dele para commands get para acompanhá-lo; o result de um comando que falhou contém o erro correspondente.

instances scale

Define o número de réplicas de servidor de um serviço por meio de um ScalingOverride. --server-replicas <n> é obrigatório e deve ser maior que zero. O executor reporta o comando como em execução ao aplicar o override e como concluído quando as réplicas estiverem prontas.

instances patch

Altera um serviço no próprio lugar. --create-nlb é o único patch disponível; sem ele, o comando falha com nothing to patch. Ele provisiona um NLB interno, na forma de um Service do Kubernetes, apenas na AWS, para que um scraper fora do cluster consiga alcançar os servidores. O executor preenche o host do scraper a partir do balanceador de carga na sincronização seguinte.

instances delete

Remove um serviço do cluster. Ele para o serviço e aguarda o desligamento ordenado pelo operator. Em seguida, desinstala o workload, exclui o espaço de nomes ns-<name> e os artifacts do scraper, aguarda até que o espaço de nomes deixe de existir e marca o serviço como terminated. Os buckets e a IAM role do serviço são mantidos; executor teardown os remove com as suas credentials. Um retry de uma exclusão já concluída é um no-op. O caminho normal é excluir o serviço no ClickHouse Cloud; consulte excluir um serviço.

Comandos do clicklink clctl

commands list

Imprime os comandos que o executor registrou, em JSON, do mais recente para o mais antigo. O result de um comando que falhou contém o erro correspondente; uma sincronização de plataforma que aguarda sua aprovação indica ali o comando platform approve exato.

Flag	Descrição
`--status <status>`	Filtro: `pending`, `running`, `completed` ou `failed`.
`--action <action>`	Filtra por ação, por exemplo `create_instance` ou `sync_platform`.
`--cluster <name>`	Filtra por cluster gerenciado.

commands get

clicklink clctl commands get <id> exibe um comando, com seu stage e resultado.

clicklink clctl platform approve

Autoriza uma alteração de plataforma com as suas próprias credenciais de cluster. Lê o pacote preparado pelo executor, calcula seu hash e renderiza cada chart contido nele exatamente como o executor fará. Aplica a metade de permissões usando o contexto kube que você escolher, cria a identidade pcm-platform do executor se necessário e emite seu token. Não faz nenhuma requisição ao seu connector endpoint. A metade de permissões é composta por Namespaces, CustomResourceDefinitions, ServiceAccounts, Funções de cluster e bindings, Roles e bindings, configurações de webhook e admission, PriorityClasses e a StorageClass. O executor então aplica apenas a metade de workload, e somente enquanto esse token for válido. Consulte atualizações de plataforma. Para acesso direto ao registry da ClickHouse, execute a aprovação na VM EC2 do connector: a CLI usa o instance profile dela para assumir a função de pull read-only, independentemente das credenciais do seu kubeconfig. Outros registries de chart no ECR usam AWS credentials do ambiente. Consulte credenciais de registry.

Flag	Descrição
`--config <path>`	Arquivo de configuração do connector (variável de ambiente `CLCTL_EXECUTOR_CONFIG`). Fornece o prefixo de espaço de nomes; em uma workstation, uma cópia da configuração do connector.
`--context <name>`	Contexto do kubeconfig do cluster gerenciado, com direitos de cluster-admin; um nome ou um pattern (variável de ambiente `CLCTL_CONTEXT`). Padrão: o único contexto; caso contrário, um picker.
`--ttl <dur>`	Ciclo de vida do token de plataforma (padrão `2h`). O executor nunca o renova.
`--output-dir <path>`	Raiz de acesso: o pacote preparado é lido a partir dela e o token é gravado sob ela, em `_platform` (padrão `/etc/clicklink/access/executor`; variável de ambiente `CLCTL_EXECUTOR_OUTPUT_DIR`).
`--secret-namespace <ns>`	Instalações em Kubernetes: lê o pacote preparado a partir da API local do executor e entrega o pacote de token como um Secret neste espaço de nomes (o espaço de nomes do connector) em vez de `<output-dir>/_platform`.
`--secret-name <name>`	Nome do Secret para `--secret-namespace` (padrão `clicklink-platform-bundle`); deve corresponder ao `executor.platformBundleSecret` do chart.
`--endpoint <url>`	Instalações em Kubernetes: a API local do executor, acessada por meio de um `kubectl port-forward` (padrão `http://127.0.0.1:9999`; variável de ambiente `CLCTL_ENDPOINT`).
`--bundle <path>`	Override: um manifesto de plataforma renderizado entregue fora de banda, lido em vez do pacote preparado. Normalmente omitido.
`--dry-run`	Renderiza e lista a metade de permissões sem aplicá-la nem emitir o token.

clicklink clctl platform reset

Para clusters de teste sem serviços: desinstala os lançamentos da plataforma na ordem inversa de dependências e remove o pacote de tokens da plataforma do executor, permitindo que a primeira instalação seja executada novamente. Antes de alterar qualquer coisa, lista os clusters ClickHouse nos espaços de nomes pertencentes a este connector e recusa a operação caso algum exista. CustomResourceDefinitions, RBAC e a StorageClass são mantidos. Execute platform approve novamente antes da próxima sincronização da plataforma.

Flag	Descrição
`--bundle <path>`	Caminho para o manifesto renderizado da plataforma (obrigatório, lido após a verificação de cluster vazio).
`--config <path>`	Arquivo de configuração do connector (variável de ambiente `CLCTL_EXECUTOR_CONFIG`).
`--context <name>`	contexto do kubeconfig do cluster gerenciado, com direitos de cluster-admin.
`--output-dir <path>`	Raiz de acesso cujo pacote `_platform` é removido (padrão `/etc/clicklink/access/executor`).
`--secret-namespace <ns>`, `--secret-name <name>`	Instalações no Kubernetes: em vez disso, remove o Secret com o pacote da plataforma no espaço de nomes do connector (nome padrão `clicklink-platform-bundle`).
`--dry-run`	Verifica se há serviços e exibe o plano de reset sem alterar o cluster.

Flags de canal remoto

preflight, gateway trust e access provision compartilham um conjunto 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; assume `aws` como padrão quando nenhuma é definida. `local` nunca é inferido, portanto, na própria VM, sempre passe `--provider local`.
`--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 (padrão `us-east-1`) 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`).

​clicklink clctl init

​Pontos de entrada

​Flags comuns

​Flags de assinatura (somente na fase 1)

​Flags exclusivas do Kubernetes

​Flags exclusivas para VM

​Conflitos de flags

​clicklink clctl preflight

​clicklink clctl troubleshoot session

​Flags compartilhadas

​habilitar sessão

​desativar sessão

​status da sessão

​clicklink clctl troubleshoot gateway trust

​clicklink clctl troubleshoot audit tail

​Provisionamento de acesso

​clicklink clctl executor access

​executor access grant

​executor access apply

​clicklink clctl executor prepare

​clicklink clctl executor teardown

​clicklink clctl instances

​instances create

​instances list

​instances get

​instances scale

​instances patch

​instances delete

​Comandos do clicklink clctl

​commands list

​commands get

​clicklink clctl platform approve

​clicklink clctl platform reset

​Flags de canal remoto