Skip to main content
Esta página aborda as alterações de configuração que você provavelmente fará após instalar o connector. Todas as chaves, com seus valores padrão e significados, estão na referência de configuração; as flags de comando estão na referência da CLI. Criar, escalar e excluir serviços é abordado em serviços gerenciados.

​
Superfícies de configuração

O conector tem uma superfície de configuração para cada destino de instalação.
clicklink clctl init cria, no diretório de trabalho, uma sobreposição de valores chamada clicklink-values.yaml e implanta o chart clicklink-connector com ela. A sobreposição é o registro persistente da sua implantação: ao executar init novamente, ela é mantida, a menos que você informe --force, de modo que suas edições sejam preservadas em novas execuções e durante a recuperação.
Os comandos de operação nesta página e em operações usam a CLI helm. Somente o init inclui um cliente Helm integrado.
Edite a sobreposição e aplique-a:
Esse bloco reaplica os valores editados à versão do chart já instalada, para que uma alteração de configuração não resulte também em um upgrade não planejado. Atualizar para uma nova versão é uma etapa separada; consulte operações. Em uma instalação espelhada que usa um repositório de charts, substitua --repo pelo seu espelho.Uma instalação a partir de uma referência direta ao chart (oci://, uma URL ou um arquivo ou diretório local; consulte espelhos privados) não tem um repositório para consulta. Execute o upgrade novamente usando a referência a partir da qual você instalou:

​
modo managed

O modo managed executa o executor, que aplica ao seu cluster o lifecycle de serviço conduzido pelo ClickHouse Cloud. O init o ativa na inscrição e preenche a identity do cluster (consulte habilitar modo managed). As keys abaixo são as que você talvez queira revisar depois. Para alterar a postura, execute o init novamente com --force e --managed ou --no-managed. Como em toda execução do init, é preciso um entry point: --handoff, caso você tenha guardado o pacote, ou --enroll com um token novo (consulte novas execuções e recovery). Em uma VM, --no-managed desabilita o executor na configuração, mas não interrompe nem desabilita um systemd unit em execução. Pare-o antes de alterar a configuração:
No Kubernetes, defina executor.enabled: false nos values e aplique com helm upgrade para remover a Implantação do executor. Em ambos os targets, a concessão no cluster permanece até que você a remova; consulte interromper o modo managed.
O init prepara o bloco executor no clicklink-values.yaml a partir do cluster EKS para o qual o seu contexto do kube aponta:
  • cluster.namespacePrefix é compartilhado por todos os componentes e é o prefixo ao qual o grant do executor o restringe. Alterá-lo após a instalação significa executar o grant novamente.
  • executor.cluster é exatamente um cluster: name, region, accountId e inCluster: true, o que faz o executor se autenticar como o ServiceAccount do pod do Kubernetes. As demais chaves são repassadas ao executor literalmente em snake_case, como s3_storage.
  • executor.serviceAccount permanece com create: false: o init concede acesso cluster-wide ao ServiceAccount pcm-executor no espaço de nomes do connector, e o chart vincula-se a ele em vez de criar um novo sem vínculo.
  • executor.persistence dá suporte a /var/lib/clicklink, onde o executor mantém seu banco de dados de comandos e o registry de serviços; consulte armazenamento.
  • executor.platformBundleSecret indica o Secret que contém uma atualização de plataforma aprovada. A montagem é opcional, portanto o pod do Kubernetes inicia antes da primeira aprovação; consulte aprovar uma atualização de plataforma.
  • executor.ports.health serve /livez e /metrics; não há porta de métricas separada em nenhum componente.
Aplique as alterações com o helm upgrade mostrado em superfícies de configuração.

​
Adicionando ou alterando instâncias do ClickHouse

Os serviços criados pelo executor se registram automaticamente, portanto, no modo gerenciado, você nunca os adiciona aqui. Esta seção se aplica a uma implantação separada do connector, executando sem o executor, que monitora o ClickHouse que você mesmo executa. Passe --ch-user-suffix no init dela quando as duas implantações compartilharem uma instância. Cada entrada em instances nomeia um endpoint de protocolo nativo do ClickHouse do qual o connector lê: host, port, database, secure, cluster e, no Kubernetes, namespace. max_open_conns e max_idle_conns limitam o connection pool. As credenciais nunca ficam na configuração; cada componente obtém seu usuário read-only do ClickHouse a partir do pacote de acesso criado pelo provisionamento.
Adicione a instância ao map instances de nível superior em clicklink-values.yaml (os mesmos campos do registro da VM). Adicione o respectivo espaço de nomes a networkPolicy.clickhouseNamespaces, correspondente ao label kubernetes.io/metadata.name do espaço de nomes. O chart renderiza o map no ConfigMap clicklink-instance-registry que ambos os daemons leem. Isso funciona apenas enquanto executor.enabled for false; com o executor ativo, a renderização falha porque o executor é o proprietário desse ConfigMap.
Provisione acesso read-only para cada componente a partir da sua estação de trabalho. --apply-ch-grants aplica as permissões geradas do ClickHouse no pod usando kubectl exec; sem essa opção, o comando cria apenas os recursos do Kubernetes e deixa ch-grants.sql no disco para que você o aplique. Se o usuário administrador tiver senha, adicione --ch-admin-password-stdin e forneça-a por pipe.
Para uma instância gerenciada por operador sem um administrador capaz de executar SQL, substitua --apply-ch-grants por --ch-user-via cr (as flags de seleção de pod permanecem); consulte a referência da CLI. Em seguida, associe o par Secret e ServiceAccount criado por cada comando ao map accessBundles correspondente e execute o helm upgrade mostrado acima:
Os mesmos comandos access provision, com --force, rotacionam as credenciais do ClickHouse de uma instância. Consulte operações.

​
Lista de permissões de operadores

Uma lista de permissões de endereços de e-mail de operadores controla as sessões gerenciadas pelo gateway. Cada solicitação ao gateway de sessão deve incluir um token de ID OIDC de curta duração cujo e-mail atestado conste na lista. Uma lista de permissões vazia fecha o gateway. Em uma VM, o usuário root no host também pode gerenciar sessões diretamente pelo arquivo de sessão local; a lista de permissões controla apenas o acesso pelo gateway. Consulte sessões de suporte para conhecer o modelo de confiança completo.
A lista de permissões fica na sobreposição, e o chart a renderiza em um ConfigMap. Para alterá-la, edite a lista e execute helm upgrade:

​
Política de rede e egress

No Kubernetes, o chart inclui uma NetworkPolicy de negação padrão com uma lista de permissões de egress. Objetos NetworkPolicy só entram em vigor quando o seu CNI os aplica. Com um CNI que aplica essas regras, apenas o DNS do cluster e os espaços de nomes do ClickHouse Service ficam acessíveis até que ambas as listas de CIDRs sejam preenchidas. Até lá, o connector não tem egress para o seu connector endpoint nem para o Kubernetes API server. O init só prepara a policy como enabled quando conhece os CIDRs por trás do seu connector endpoint.
As duas listas de CIDR vêm de lugares diferentes:
  • allowEgressCIDRs cabe a você fornecer: são os intervalos por trás do seu connector endpoint, informados na instalação com --egress-cidrs ou no prompt. Todos os componentes precisam deles para alcançar o seu connector endpoint. No modo gerenciado, quando os charts da plataforma ficam no Amazon ECR, adicione os intervalos do ECR e do STS da sua region (ou o intervalo do seu mirror). Sem eles, o download dos charts pelo executor falha sob a policy.
  • apiserverCIDRs é derivado pelo init, no modo gerenciado, a partir da VPC do EKS cluster (eks:DescribeCluster e ec2:DescribeVpcs). Todos os componentes emitem requisições de token do Kubernetes e o executor opera os serviços pela API, portanto, sob um CNI que aplica as regras, todos ficam bloqueados até que ela seja definida. Se o lookup falhar, o init emite um aviso e deixa a lista vazia para que você a preencha com os blocos CIDR da sua VPC.
Os espaços de nomes de serviço são selecionados de duas maneiras. Os espaços de nomes criados pelo executor recebem o rótulo clicklink.clickhouse.com/managed-by: executor, e a policy os admite por esse rótulo, de modo que uma instalação gerenciada pode deixar clickhouseNamespaces vazio. Somente os espaços de nomes criados fora do executor, para o ClickHouse que você mesmo executa, precisam ser listados pelo nome. Habilitar a policy depois. Se você pulou os CIDRs do endpoint na instalação, o init deixou enabled: false com allowEgressCIDRs: [] e exibiu o passo necessário para concluir. Assim que souber os CIDRs, defina enabled: true e allowEgressCIDRs em clicklink-values.yaml, confirme que apiserverCIDRs contém os intervalos da sua VPC e execute o helm upgrade mostrado em superfícies de configuração. Quando o gateway de sessão está habilitado, mais uma regra de egress entra em jogo: clctl.gateway.jwksEgressCIDRs. O solucionador de problemas busca o JWKS do seu identity provider para validar os tokens de operador, portanto, sob negação padrão, uma lista vazia bloqueia toda verificação de token:
O exemplo é o range private.googleapis.com, que abrange um identity provider do Google acessado via Private Google Access. Para qualquer outro identity provider, informe o range correspondente ou o CIDR do proxy de egress que fica à frente dele. Restam duas chaves de entrada: metricsScrapeSelector restringe a entrada de scrape de metrics a um único espaço de nomes do Prometheus por rótulo, e kubeletProbeCIDRs admite explicitamente probes de saúde do agente de nó do Kubernetes sob negação padrão estrita. Consulte a referência de configuration para ver a lista completa de chaves.

​
Padrões de redação

O solucionador de problemas redige sua saída antes que ela saia do seu ambiente. Os padrões integrados abrangem ipv4, ipv6, bearer-token, aws-access-key, email, jwt, ssh-private-key e connection-string-credentials. Adicione seus próprios padrões em um arquivo YAML. Eles são executados primeiro, na ordem em que aparecem no arquivo, seguidos pelos padrões integrados; uma entrada que reutiliza o name de um padrão integrado o substitui. Cada padrão aceita name (obrigatório, único), regex (obrigatório, sintaxe RE2 do Go), replace (o padrão é [REDACTED], com suporte a referências de captura $1) e case_insensitive (o padrão é false):
Em uma VM, o arquivo é /etc/clicklink/redaction-patterns.yaml. O instalador o inicializa com um conjunto inicial de padrões ativos (API keys de terceiros, AWS secret keys e assim por diante). Reduza ou amplie o conjunto; o instalador preserva sua versão durante os upgrades. No Kubernetes, coloque o YAML em um ConfigMap com a chave redaction-patterns.yaml e defina troubleshooter.redaction.patternsConfigMap como o nome dele; o chart o monta no mesmo caminho.
O solucionador de problemas se recusa a iniciar se houver um arquivo de padrões inválido e registra nos logs a entrada problemática. Um arquivo configurado, mas ausente, apenas gera um aviso nos logs e utiliza os padrões integrados. clicklink clctl preflight valida o arquivo; portanto, execute-o antes de reiniciar o daemon.

​
Espelhos privados e endpoints dentro da fronteira

O chart publicado predefine image.repository para a imagem pública do connector, compatível com várias arquiteturas e assinada com cosign; portanto, instalações simples não exigem values de imagem. Para inspecionar os padrões publicados:
Para extrair usando seu próprio registry, substitua o repository na sobreposição:
Para instalar o próprio chart a partir de um espelho, init aceita --chart como o nome de um chart resolvido a partir de --chart-repo ou como uma referência oci:// direta, uma URL, um arquivo compactado local ou um 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 atualizados juntos.
Quando o endpoint do connector estiver por trás de uma CA privada dentro da sua fronteira, passe --api-private-ca para init. Isso configura api.tls.caFile: /etc/clicklink/secrets/mtls/ca.crt, e o connector verifica o endpoint em relação às raízes do sistema mais a cadeia de CAs do pacote de inscrição. Em uma VM, o equivalente é api.tls.ca_file em /etc/clicklink/config.yaml: init instala a cadeia do pacote em /etc/clicklink/tls/ca.crt, e o connector a acrescenta às raízes do sistema da mesma forma. Para inscrição e assinatura de certificados em ambientes totalmente isolados da internet, consulte onboarding.

​
Armazenamento

Dois componentes mantêm estado em PersistentVolumeClaims. O do solucionador de problemas guarda o estado da sessão e a trilha de auditoria:
O do executor guarda seu banco de dados de comandos e o registro dos serviços que ele gerencia:
O init define os dois valores de storageClass com a classe que você escolheu. Um storageClass vazio usa a StorageClass padrão do cluster; quando o cluster não define nenhuma como padrão, o init solicita uma pelo prompt ou pela opção --storage-class. O claim do executor recebe a anotação helm.sh/resource-policy: keep, portanto o helm uninstall o mantém; consulte desinstalação.