Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Configuração

View as MarkdownEdit this pageReport an issueSet up docs MCP

Esta página aborda as alterações de configuração que você provavelmente fará após instalar o ClickHouse Connector. Para ver todas as chaves, seus valores padrão e significados, consulte a referência de configuração; para flags de comando, consulte a referência da CLI.

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.

Edite a sobreposição e aplique-a:

CONNECTOR_NAMESPACE='clicklink'   # o espaço de nomes do conector escolhido durante o init
CHART_VERSION="$(helm get metadata clicklink-connector -n "${CONNECTOR_NAMESPACE}" | awk '/^VERSION:/{print $2}')"
helm upgrade clicklink-connector clicklink-connector \
  --repo https://releases.clicklink.clickhouse.com/charts \
  --version "${CHART_VERSION}" \
  --namespace "${CONNECTOR_NAMESPACE}" \
  -f clicklink-values.yaml

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 intencional abordada em 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:

helm upgrade clicklink-connector <same-chart-reference> \
  --version "${CHART_VERSION}" \
  -n "${CONNECTOR_NAMESPACE}" \
  -f clicklink-values.yaml

Adicionar ou alterar instâncias do ClickHouse

Cada entrada em instances nomeia um endpoint do protocolo nativo do ClickHouse a partir do qual o conector lê: host, port, database, secure, além de namespace e cluster no Kubernetes. As credenciais nunca ficam na configuração; cada componente obtém seu usuário somente leitura do ClickHouse a partir do pacote de acesso criado pelo provisionamento.

Adicione a instância aos maps de ambos os componentes em clicklink-values.yaml e adicione o respectivo espaço de nomes a networkPolicy.clickhouseNamespaces (correspondente ao label kubernetes.io/metadata.name do espaço de nomes):

scraper:
  instances:
    analytics:
      host: "clickhouse-analytics.clickhouse.svc.cluster.local"
      port: 9440
      database: "default"
      secure: true
      namespace: "clickhouse"
      cluster: "default"

troubleshooter:
  instances:
    analytics:
      host: "clickhouse-analytics.clickhouse.svc.cluster.local"
      port: 9440
      database: "default"
      secure: true
      namespace: "clickhouse"
      cluster: "default"

networkPolicy:
  clickhouseNamespaces:
    - "clickhouse"

Provisione acesso somente leitura 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.

CONNECTOR_NAMESPACE='clicklink'   # o espaço de nomes do conector escolhido durante a inicialização
clicklink clctl scraper access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance analytics --instance-namespace clickhouse \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace clickhouse
clicklink clctl troubleshoot access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance analytics --instance-namespace clickhouse \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace clickhouse

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:

scraper:
  accessBundles:
    analytics:
      secretName: clicklink-connector-scraper-access-analytics
      serviceAccountName: pcm-scraper-analytics

troubleshooter:
  accessBundles:
    analytics:
      secretName: clicklink-connector-troubleshooter-access-analytics
      serviceAccountName: pcm-troubleshooter-analytics

Lista de permissões de operadores

As sessões gerenciadas pelo gateway de sessão são controladas por uma lista de permissões de endereços de e-mail de operadores: 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, impedindo que qualquer pessoa abra uma sessão por meio dele. 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 é renderizada em um ConfigMap. Para alterá-la, edite a lista e execute helm upgrade:

clctl:
  gateway:
    enabled: true
    allowedOperators:
      - "oncall@example.com"
      - "dba@example.com"

Política de rede e tráfego de saída

No Kubernetes, o chart inclui uma NetworkPolicy padrão que nega todo o tráfego, com uma lista de permissão de saída (networkPolicy.enabled: true). Os objetos NetworkPolicy só têm efeito quando são aplicados pelo CNI; com um CNI que os aplica, o conector não tem tráfego de saída até que allowEgressCIDRs especifique os CIDRs por trás do endpoint da API do conector.

networkPolicy:
  enabled: true
  # CIDRs behind your connector API endpoint. Required under an enforcing CNI.
  allowEgressCIDRs:
    - "203.0.113.0/24"
  # Ports opened to allowEgressCIDRs.
  allowEgressPorts:
    - 443
  # Namespaces of your ClickHouse Services, matched by the
  # kubernetes.io/metadata.name label. Empty allows no in-cluster
  # ClickHouse access.
  clickhouseNamespaces:
    - "clickhouse"
  # Kubernetes API server CIDRs. On managed Kubernetes the API server sits
  # outside the cluster network, so it cannot be matched with a selector.
  apiserverCIDRs:
    - "172.16.0.0/28"

Duas regras merecem atenção especial:

  • apiserverCIDRs: quando está vazio, o chart não gera nenhuma regra de egress para o servidor de API. Os daemons falham na primeira solicitação de token ao Kubernetes com um erro de rede, o que indica que essa configuração deve ser definida. No Kubernetes gerenciado, use os CIDRs do endpoint do servidor de API do cluster.
  • clctl.gateway.jwksEgressCIDRs: quando o gateway de sessão está habilitado, o solucionador de problemas busca o JWKS do seu provedor de identidade para validar os tokens de operador. Em uma política de negação por padrão, deixar esse campo vazio bloqueia todas as verificações de token:
clctl:
  gateway:
    jwksEgressCIDRs:
      - "199.36.153.8/30"

Um exemplo é o intervalo private.googleapis.com, que abrange um provedor de identidade do Google acessado por Private Google Access; para qualquer outro provedor de identidade, informe o intervalo desse provedor (ou o CIDR do proxy de saída à frente dele).

Outros dois controles de Entrada: metricsScrapeSelector restringe a Entrada para coleta de métricas a um Espaço de nomes específico do Prometheus por rótulo, e kubeletProbeCIDRs permite explicitamente sondas de integridade do agente de nó do Kubernetes em ambientes com negação padrão estrita. Consulte a referência de configuração para ver a lista completa de chaves.

Padrões de redação

A saída do solucionador de problemas é redigida antes de sair do seu ambiente. Os padrões integrados abrangem ipv4, ipv6, bearer-token, aws-access-key, email, jwt, ssh-private-key e connection-string-credentials. Você pode adicionar 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):

version: 1
patterns:
  - name: internal-hostname
    regex: '\b[a-z0-9-]+\.corp\.example\.com\b'
    replace: '[REDACTED:internal-host]'

  # Reusing a built-in name replaces the built-in pattern.
  - name: ipv4
    regex: '\b(?:\d{1,3}\.){3}\d{1,3}\b'
    replace: '[REDACTED:ip]'

Em uma VM, o arquivo é /etc/clicklink/redaction-patterns.yaml; o instalador fornece um arquivo padrão comentado e 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.

Espelhos privados e endpoints dentro da fronteira

O chart publicado predefine image.repository para a imagem pública do conector, 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:

CLICKLINK_VERSION="$(curl -fsSL https://releases.clicklink.clickhouse.com/latest-version.txt)"
helm show values clicklink-connector \
  --repo https://releases.clicklink.clickhouse.com/charts \
  --version "${CLICKLINK_VERSION#v}"

Para extrair usando seu próprio registry, substitua o repository na sobreposição:

image:
  repository: "registry.example.com/mirrors/clicklink"

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:

clicklink clctl init --handoff handoff.yaml --target helm \
  --chart oci://registry.example.com/charts/clicklink-connector

Quando o endpoint da API do conector 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, para que o endpoint seja verificado em relação à cadeia de CAs do pacote de inscrição, em vez das raízes do sistema. 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, que é adicionada às raízes do sistema para verificação. Para inscrição e assinatura de certificados em ambientes totalmente isolados da internet, consulte onboarding.

Armazenamento

O solucionador de problemas mantém seu estado em um PersistentVolumeClaim, de modo que o estado da sessão e o histórico de auditoria persistem mesmo após o reagendamento de pods do Kubernetes:

persistence:
  enabled: true
  storageClass: "gp3"
  size: 5Gi

Uma storageClass vazia usa a StorageClass padrão do cluster. Se o cluster não tiver nenhuma marcada como padrão, init exigirá uma, informada pelo prompt ou por --storage-class.

Navigation