Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

設定

View as MarkdownEdit this pageReport an issueSet up docs MCP

このページでは、ClickHouse Connector のインストール後に特に変更する可能性が高い設定について説明します。各キーのデフォルト値と意味については設定リファレンスを、コマンドフラグについてはCLI リファレンスを参照してください。

設定箇所

コネクタでは、インストール先ごとに設定箇所が 1 つあります。

clicklink clctl init は、作業ディレクトリに clicklink-values.yaml という values オーバーレイを作成し、それを使用して clicklink-connector チャートをデプロイします。このオーバーレイはデプロイメントの永続的な記録です。--force を指定しない限り、init を再実行しても保持されるため、編集内容は再実行後や復旧後も維持されます。

オーバーレイを編集してから適用します。

CONNECTOR_NAMESPACE='clicklink'   # 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

このブロックは、すでにインストールされているチャートバージョンに編集済みの values を再適用します。これにより、設定変更が意図しないアップグレードを伴うことはありません。新しいバージョンへの移行は、操作で説明する意図的な手順です。チャートリポジトリを使用するミラーインストールでは、--repo をミラーに置き換えてください。

直接指定したチャート参照 (oci://、URL、またはローカルのアーカイブやディレクトリ。詳細はプライベートミラーを参照) からインストールした場合、解決に使用できるリポジトリはありません。インストール時に使用した参照を指定して、アップグレードを再実行してください。

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

ClickHouse インスタンスの追加または変更

instances 配下の各エントリでは、コネクタが読み取る ClickHouse ネイティブプロトコルのエンドポイントとして、host、port、database、secure、および Kubernetes 上では namespace と cluster を指定します。認証情報は設定には含まれません。各コンポーネントは、プロビジョニングで作成されるアクセスバンドルから読み取り専用の ClickHouse ユーザーを取得します。

clicklink-values.yaml の両方のコンポーネントマップにインスタンスを追加し、そのネームスペースを networkPolicy.clickhouseNamespaces に追加します (ネームスペースの kubernetes.io/metadata.name ラベルに基づいて照合されます) 。

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"

ワークステーションから各コンポーネントの読み取り専用アクセスをプロビジョニングします。--apply-ch-grants は、生成された ClickHouse 権限を kubectl exec 経由でポッド内に適用します。指定しない場合、コマンドは Kubernetes 側のリソースのみを作成し、適用するための ch-grants.sql をディスクに残します。管理ユーザーにパスワードが設定されている場合は、--ch-admin-password-stdin を追加し、パイプで渡します。

CONNECTOR_NAMESPACE='clicklink'   # 初期化時に選択したコネクタのネームスペース
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

SQL を実行できる管理者がいない Operator 管理インスタンスでは、--apply-ch-grants の代わりに --ch-user-via cr を使用します (ポッド選択フラグはそのまま使用します) 。詳細は CLI リファレンスを参照してください。次に、各コマンドで作成される Secret と ServiceAccount の組を対応する accessBundles マップに設定し、上記の helm upgrade を実行します。

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

Operator 許可リスト

ゲートウェイで管理されるセッションは、operator のメールアドレスの許可リストによって制限されます。セッションゲートウェイへのすべてのリクエストには、証明済みメールアドレスがリストに含まれている、短期間有効な OIDC ID トークンが必要です。許可リストが空の場合、ゲートウェイは閉鎖され、誰もゲートウェイ経由でセッションを開始できません。VM では、ホストの root ユーザーはローカルのセッションファイルを通じてセッションを直接管理することもできます。許可リストはゲートウェイ経由の経路にのみ適用されます。信頼モデルの詳細については、サポートセッションを参照してください。

許可リストはオーバーレイで定義され、ConfigMap にレンダリングされます。変更するには、リストを編集して helm upgrade を実行します。

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

ネットワークポリシーとegress

Kubernetes では、チャート にデフォルト拒否の NetworkPolicy と egress の許可リスト (networkPolicy.enabled: true) が含まれています。NetworkPolicy オブジェクトは、CNI がこれらを適用する場合にのみ有効になります。適用可能な CNI を使用している場合、allowEgressCIDRs でコネクタの API エンドポイントの背後にある CIDR を指定するまで、コネクタからの egress は一切許可されません。

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"

特に注意が必要なルールは次の 2 つです。

  • apiserverCIDRs: 空の場合、チャートは API サーバーへの egress ルールを生成しません。そのため、デーモンは最初の Kubernetes トークンリクエストでネットワークエラーにより失敗します。これが設定が必要であることを示すシグナルです。Managed Kubernetes では、クラスターの API サーバーエンドポイントの CIDR を使用してください。
  • clctl.gateway.jwksEgressCIDRs: セッションゲートウェイが有効な場合、troubleshooter は operatorトークンを検証するために、アイデンティティプロバイダーの JWKS を取得します。デフォルト拒否の方針では、これを空のままにすると、すべてのトークンチェックがブロックされます。
clctl:
  gateway:
    jwksEgressCIDRs:
      - "199.36.153.8/30"

例として、Private Google Access 経由でアクセスする Google のアイデンティティプロバイダを対象とする private.googleapis.com の範囲を示します。その他のアイデンティティプロバイダの場合は、そのプロバイダの範囲 (またはその前段のエグレスプロキシの CIDR) を指定してください。

イングレスに関する設定は、さらに 2 つあります。metricsScrapeSelector は、ラベルによりメトリクスのスクレイプ用イングレスを特定の Prometheus ネームスペースに制限します。kubeletProbeCIDRs は、デフォルト拒否が厳格に適用される環境でキューブレットのヘルスプローブを明示的に許可します。キーの完全な一覧については、設定リファレンスを参照してください。

マスキングパターン

Troubleshooter の出力は、境界外に送信される前にマスキングされます。組み込みパターンでは、ipv4、ipv6、bearer-token、aws-access-key、email、jwt、ssh-private-key、connection-string-credentials を対象とします。独自のパターンは YAML ファイルに追加できます。独自のパターンはファイル内の記述順に最初に実行され、その後に組み込みパターンが実行されます。また、組み込みパターンと同じ name を使用するエントリは、その組み込みパターンを置き換えます。

各パターンでは、name (必須、一意) 、regex (必須、Go RE2 構文) 、replace (デフォルトは [REDACTED]、$1 のキャプチャ参照をサポート) 、case_insensitive (デフォルトは 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]'

VM では、ファイルは /etc/clicklink/redaction-patterns.yaml にあります。インストーラーはコメント付きのデフォルトファイルを配置し、アップグレード時にも独自のバージョンを保持します。Kubernetes では、YAML を redaction-patterns.yaml キーの ConfigMap に格納し、troubleshooter.redaction.patternsConfigMap にその名前を設定します。チャート はこれを同じパスにマウントします。

プライベートミラーと境界内のエンドポイント

公開されているチャートでは、image.repository にパブリックなマルチアーキテクチャ対応のcosign署名済みコネクタイメージが事前設定されているため、通常のインストールではイメージ値を指定する必要はありません。公開されているデフォルトを確認するには:

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}"

独自のレジストリから取得するには、オーバーレイでリポジトリを上書きします。

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

ミラーからチャート自体をインストールするには、init の --chart に、--chart-repo を基準に解決されるチャート名、直接指定する oci:// 参照、URL、ローカルのアーカイブまたはディレクトリを指定できます。--chart-version のデフォルトは CLI 自身のバージョンのため、バイナリとチャートのバージョンが連動します。

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

コネクタの API エンドポイントが境界内の private CA の配下にある場合は、init に --api-private-ca を渡します。これにより api.tls.caFile: /etc/clicklink/secrets/mtls/ca.crt が設定され、エンドポイントはシステムルートではなく、登録バンドルの CA チェーンを使用して検証されます。VM では、これに相当する設定は /etc/clicklink/config.yaml の api.tls.ca_file です。init はバンドルのチェーンを /etc/clicklink/tls/ca.crt にインストールし、検証用にシステムルートへ追加します。完全に air-gapped な環境での登録と証明書署名については、オンボーディングを参照してください。

ストレージ

troubleshooter は PersistentVolumeClaim に状態を保存するため、セッション状態と監査証跡はポッドが再スケジュールされても保持されます。

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

storageClass が空の場合は、クラスターのデフォルト StorageClass が使用されます。クラスターでデフォルトの StorageClass が設定されていない場合は、プロンプトまたは --storage-class で init に指定する必要があります。

Navigation