運用 - ClickHouse Documentation

このページでは、両方のインストール先における ClickHouse Connector のDay 2運用について説明します。インストールとオンボーディングについては、オンボーディングを参照してください。

アップグレード

Kubernetes

Day 2 以降の Kubernetes 運用では、ワークステーション上の helm CLI を使用します。組み込みの Helm クライアントを備えているのは init のみであるため、最初のアップグレード前に helm をインストールしてください。

init で用意した values オーバーレイを再利用し、パブリックチャートリポジトリからリリースをアップグレードします。

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
helm upgrade --install clicklink-connector clicklink-connector \
  --repo https://releases.clicklink.clickhouse.com/charts \
  --version <version> \
  -n "${CONNECTOR_NAMESPACE}" \
  -f clicklink-values.yaml

チャートのバージョンは、先頭の v を除いたリリースタグです (チャート 0.9.0 はタグ v0.9.0 に対応します) 。公開済みのチャートはすでにパブリックコンテナーイメージを参照しているため、通常のインストールやアップグレードでイメージ値を指定する必要はありません。チャートのデフォルト値を確認するには、helm show values clicklink-connector --repo https://releases.clicklink.clickhouse.com/charts を実行してください。直接指定したチャート参照 (oci://、URL、ローカルのアーカイブまたはディレクトリ) からインストールした場合、解決に使用できるリポジトリはありません。そのため、新しいバージョンでは helm upgrade clicklink-connector <same-chart-reference> を再実行してください。新しい CLI で init を再実行しても同じ状態に収束しますが、init には常にいずれかのエントリポイントが必要です。バンドルを保持している場合は --handoff を使用し、そうでない場合は、ドキュメントに記載されたクリーンアップ後に --force を指定して新しい登録トークンを使用します。通常は、上記の helm upgrade を使用してください (再実行と復旧を参照) 。

Linux VM

ホスト上でインストーラーを再実行します。これにより、オンボーディング時と同様に新しいリリースがダウンロードおよび検証され、以前のバイナリがバックアップされるとともに、運用中の機密情報マスキングパターンと環境ファイルが保持されます。続いて、デーモンを再起動します。

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | sudo bash -s -- --host
sudo systemctl restart clicklink-scraper clicklink-troubleshooter

最新バージョンではなく特定のリリースにアップグレードするには、インストーラーコマンドに --version vX.Y.Z を追加します。

ヘルス

各デーモンは、ヘルスポートで /livez エンドポイントを公開します。レスポンスボディの JSON status フィールドがヘルス状態を示すものであり、HTTP ステータスコードではありません。したがって、200 に頼らずボディを確認してください。Prometheus メトリクスは各コンポーネントのメトリクスポートで公開されます。両方のターゲットのデフォルトポートは次のとおりです。

コンポーネント	ヘルスポート	メトリクスポート
グローバルデフォルト	8080	9090
スクレーパー	8082	9092
トラブルシューター	8084	9094

サポートセッションが有効な場合、ゲートウェイは追加でポート 8443 でもリッスンします。VM では自己署名 TLS を使用し、Kubernetes では kubectl port-forward 経由のポッドローカル HTTP、または TLS 終端イングレスを使用します。 VM では、いつでも完全なチェック一式を実行できます。

sudo clicklink clctl preflight

config、ファイル、ポートの競合、ネットワーク到達性 (API エンドポイントと各 ClickHouse インスタンス) 、ClickHouse への接続、systemd ユニットの状態、コンポーネントごとのアクセス、ディスク、機密情報マスキングパターンを確認し、いずれかのチェックに失敗すると 2 で終了します。

証明書

コネクタは自身のクライアント証明書を自動更新します。各デーモンは12時間ごとにleafを確認し、残りの有効期間が10日になると更新します。既存のmTLSおよびHMAC認証済みチャネルを通じて、30日間有効なleafを取得します。operatorによる操作は不要です。Kubernetesでは、更新されたleafはclicklink-mtls Secretに書き戻されます。VMでは、/etc/clicklink/tls/配下に書き込まれます。現在の有効期限を確認するには:

# Linux VM
sudo openssl x509 -in /etc/clicklink/tls/client.crt -noout -enddate

# Kubernetes
CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl get secret clicklink-mtls -n "${CONNECTOR_NAMESPACE}" -o jsonpath='{.data.tls\.crt}' \
  | base64 -d | openssl x509 -noout -enddate

認証情報のローテーション

API (HMAC) 認証情報

ClickHouse のアカウントチームに新しい登録トークンを依頼し、元の init コマンドに --enroll と --force を付けて再実行します。--force は保持されている設定を再ステージングするため、初回インストール時に指定したターゲット固有のフラグ (--target-namespace、--values、および --chart、--chart-repo、--chart-version のミラーフラグ) をすべて維持してください。デフォルトのインストールでは、以下のようになります。

# Kubernetes, from your workstation
clicklink clctl init --enroll https://<subdomain>.<connector-domain> --target helm --force

# Linux VM, on the host
sudo clicklink clctl init --enroll https://<subdomain>.<connector-domain> --force

SQL プロビジョニングでパスワードが必要な無人ローテーションでは、stdin から両方のシークレットを順に渡します。1 行目にトークン、2 行目にパスワードを指定します。トークンの読み取りでは、正確に 1 行が消費されます。

printf '%s\n' "$ENROLLMENT_TOKEN" "$CH_ADMIN_PASSWORD" | \
  clicklink clctl init --enroll https://<subdomain>.<connector-domain> --force --ch-admin-password-stdin

ClickHouse ユーザー

インスタンスごとに、コネクタの読み取り専用ユーザーを再プロビジョニングします。Kubernetes では、ワークステーションから実行します。--apply-ch-grants を指定すると、再生成された権限がポッド内で再適用され、新しい認証情報が ClickHouse に反映されます (admin user にパスワードが設定されている場合は、--ch-admin-password-stdin を追加し、パイプで渡します) ：

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
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 troubleshoot 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

VM のホスト上で：

sudo clicklink clctl scraper access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --force
sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --force

operator によって管理されるインスタンスでは、どちらの形式にも --ch-user-via cr とポッド選択フラグを追加してください。詳細については、CLI リファレンスを参照してください。

クライアント証明書

証明書は自動的に更新されます (証明書を参照) 。有効期限が切れる前に証明書をすぐに置き換えるには、--force を指定して init を再実行します。

再実行と復旧

init は再実行しても収束するため、まずは同じコマンドを再実行してください。--force を指定しない場合、既存の /etc/clicklink/config.yaml (VM) または clicklink-values.yaml オーバーレイ (Kubernetes) は保持され、既存のクライアント秘密鍵が再利用されます。認証情報と CA チェーンはアトミックに上書きされます。部分的な失敗後に CLI が出力する復旧コマンドは、安全に繰り返し実行できます。 --force は保持されている設定またはオーバーレイを上書きし、クライアント秘密鍵を再生成して、有効期限が切れていないクライアント証明書を置き換えます。新しいクラスター UUID が発行されることはありません。--force を使用しても、コネクタ’のアイデンティティは保持されます。ステージング後に証明書の署名に失敗した場合、または有効期限が切れていない証明書がすでに存在するために署名エンドポイントが 409 を返した場合でも、新しいトークンや 2 回目の発行は必要ありません。すでにディスク上にある署名済みマテリアルを使用して、インストールを完了してください。

sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt

これは VM 用の形式です (root が /etc/clicklink を書き換え、サービスを管理します) 。Kubernetes では、CLI が --target helm、--target-namespace、--values を含む完全な形式を出力するため、出力されたコマンドをそのまま使用してください。

アンインストール

Linux VM

uninstall.sh はリリース tarball に含まれています。ホスト上に展開済みの tarball が残っていない場合は、手動でのダウンロードと検証の手順に従って取得・展開し、展開したディレクトリから実行します。

sudo ./uninstall.sh

これにより、サービスが停止・無効化され、systemd ユニットとバイナリが削除されます。ただし、/etc/clicklink、/var/lib/clicklink、/var/log/clicklink、および clicklink ユーザーは保持されるため、後で再インストールした際に既存の設定が引き継がれます。これらも削除するには:

sudo ./uninstall.sh --purge

Kubernetes

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
helm uninstall clicklink-connector -n "${CONNECTOR_NAMESPACE}"

init によって作成されたSecretはチャートによって管理されないため、アンインストール後も残ります。構成したすべてのインスタンスのインスタンスごとのアクセス用Secretを含め、明示的に削除してください。

kubectl delete secret clicklink-hmac clicklink-mtls -n "${CONNECTOR_NAMESPACE}"
kubectl delete secret -n "${CONNECTOR_NAMESPACE}" \
  clicklink-connector-scraper-access-<instance> \
  clicklink-connector-troubleshooter-access-<instance>
kubectl delete serviceaccount -n "${CONNECTOR_NAMESPACE}" \
  pcm-scraper-<instance> pcm-troubleshooter-<instance>
# Repeat for every ClickHouse namespace that holds a provisioned instance.
for ns in <clickhouse-namespace-1> <clickhouse-namespace-2>; do
  kubectl delete serviceaccount,role,rolebinding -n "${ns}" \
    pcm-scraper pcm-troubleshooter
done

ClickHouse ユーザー

どちらのターゲットをアンインストールしても、プロビジョニングされた読み取り専用ユーザーは残ります。各インスタンスで管理者として削除してください (--ch-user-suffix を設定している場合は、名前に付加してください) 。

DROP USER IF EXISTS pcm_scraper, pcm_troubleshooter;

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

運用

アップグレード

Kubernetes

Linux VM

ヘルス

証明書

認証情報のローテーション

API (HMAC) 認証情報

ClickHouse ユーザー

クライアント証明書

再実行と復旧

アンインストール

Linux VM

Kubernetes

ClickHouse ユーザー

​アップグレード

​Kubernetes

​Linux VM

​ヘルス

​証明書

​認証情報のローテーション

​API (HMAC) 認証情報

​ClickHouse ユーザー

​クライアント証明書

​再実行と復旧

​アンインストール

​Linux VM

​Kubernetes

​ClickHouse ユーザー

アップグレード

Kubernetes

Linux VM

ヘルス

証明書

認証情報のローテーション

API (HMAC) 認証情報

ClickHouse ユーザー

クライアント証明書

再実行と復旧

アンインストール

Linux VM

Kubernetes

ClickHouse ユーザー