運用 - ClickHouse Documentation

このページでは、両方のインストール先における connector のDay 2運用について説明します。インストールと登録については、オンボーディングを参照してください。services 自体の運用 (作成、スケール、削除、プラットフォーム更新) については、managed servicesおよびプラットフォーム更新で説明しています。

アップグレード

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

Linux VM

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

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

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

ヘルス

各デーモンは、ヘルスポートで /livez エンドポイントを公開します。ヘルス状態を示すのはレスポンスボディの JSON status フィールドであり、HTTP ステータスコードではありません。Prometheus メトリクスは同じポートの /metrics で公開され、メトリクス専用のポートはありません。両方のターゲットのデフォルトポートは次のとおりです。

コンポーネント	ヘルスポート
scraper	8082
トラブルシューター	8084
executor	8086

executorは、ローカルのコマンド API を 127.0.0.1:9999 でも公開します。これ自体は認証を持たず、ホストやポッドの外部に公開されることはありません。clicklink clctl のサービスコマンドはローカルでこれに接続します。サポートセッションが有効な場合、ゲートウェイはポート 8443 でもリッスンします。VM では自己署名 TLS を使用し、Kubernetes では kubectl port-forward 経由のポッドローカル HTTP、または TLS 終端イングレスを使用します。 VM では、いつでも完全なチェック一式を実行できます。

sudo clicklink clctl preflight

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

証明書

コネクタは自身のクライアント証明書を自動更新します。scraper、troubleshooter、executorはそれぞれ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) 認証情報

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

# 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

VM では、init はまだ実行されていないユニットのみを有効化して起動するため、ローテーション後にデーモンを再起動してください。

sudo systemctl restart clicklink-scraper clicklink-troubleshooter clicklink-executor

Kubernetes では、init がローテーション後の clicklink-hmac および clicklink-mtls Secret を事前に作成するため、チャート側ではこれらをレンダリングしません。チャートの checksum annotation はこれらを対象に含まないため、稼働中のポッドは起動時の認証情報を保持し続けます。ローテーション後は、すべてのコンポーネントを再起動してください。

kubectl rollout restart deployment,statefulset -n "${CONNECTOR_NAMESPACE}" \
  -l app.kubernetes.io/part-of=clicklink-connector

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 では、admin パスワードをパイプで渡してホスト上で実行します。その場合、--ch-user-via cr を指定しない限り、パスワードは必須です：

printf '%s\n' "$CH_ADMIN_PASSWORD" | sudo clicklink clctl scraper access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --ch-admin-password-stdin --force
printf '%s\n' "$CH_ADMIN_PASSWORD" | sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --ch-admin-password-stdin --force

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

クライアント証明書

証明書は自動的に更新されます (証明書を参照) 。有効期限が切れる前に証明書をすぐに置き換えるには、--force を指定して init を再実行します。その後、デーモンが新しいリーフ証明書を提示するよう、すべてのコンポーネントを再起動します。Kubernetes では API 認証情報に記載のとおりに、VM では 3 つのユニットを再起動します。

再実行と復旧

init は再実行しても収束するため、まずは同じコマンドを再実行してください。--force を指定しない場合、既存の /etc/clicklink/config.yaml (VM) または clicklink-values.yaml オーバーレイ (Kubernetes) は保持され、既存のクライアント秘密鍵が再利用されます。init は認証情報と CA チェーンをアトミックに上書きします。部分的な失敗後に CLI が出力する復旧コマンドは、安全に繰り返し実行できます。 --force は保持されている設定またはオーバーレイを上書きし、クライアント秘密鍵を再生成して、有効期限が切れていないクライアント証明書を置き換えます。新しいクラスター UUID が発行されることはないため、コネクタ’のアイデンティティは保持されます。置き換えられる設定のmanaged モードの状態は、無人での再実行時には維持され、端末上ではデフォルトとして提示されます (--managed または --no-managed を指定した場合を除く) 。ステージング後に証明書の署名に失敗した場合、または有効期限が切れていない証明書がすでに存在するために署名エンドポイントが 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 を含む完全な形式を出力するため、出力されたコマンドをそのまま使用してください。 コネクタがオフラインの場合。 コネクタが停止している、または到達不能な間も、コネクタが管理する services は稼働し続けます。クラスター内の ClickHouse operator がそれらを維持し、executor はデータパス上には存在しません。ライフサイクルの変更には executor の接続が必要なため、再接続されるまで変更は一切適用されません。再起動時、executor は転送中だったコマンドを自身のコマンドデータベースから復旧します。ClickHouse Cloud が再送したコマンドは、記録済みの結果を使って応答されます。再実行されるのは失敗したコマンドのみです。executor が接続されていない間のライフサイクルコマンドについては、コネクタがオフラインの場合を参照してください。

アンインストール

アンインストールする前に、サービスの削除の手順に従ってすべてのマネージドサービスを削除し、それぞれの削除処理が完了するまで待機してください。先にコネクタを削除してしまうと、サービスのライフサイクルを管理するコンポーネントが存在しない状態になります。

Linux VM

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

sudo ./uninstall.sh

これにより、clicklink-scraper、clicklink-troubleshooter、clicklink-executor の各ユニットが停止・無効化され、systemd ユニットとバイナリが削除されます。以下は保持されるため、後で再インストールした際に既存の設定が引き継がれます:

/etc/clicklink (/etc/clicklink/access/executor 配下の executor の access bundles を含む)
/var/lib/clicklink (executor のコマンドデータベース executor.db と service registry を含む)
/var/log/clicklink
clicklink ユーザー

これらも削除するには:

sudo ./uninstall.sh --purge

executor のクラスター全体に対する grant は、ホストではなくクラスター内に存在します。managed service が残っていない状態になったら、クラスターの admin として削除してください:

kubectl delete validatingadmissionpolicybinding pcm-executor-prefix-guard
kubectl delete validatingadmissionpolicy pcm-executor-prefix-guard
kubectl delete clusterrolebinding pcm-executor-cluster
kubectl delete clusterrole pcm-executor-cluster
kubectl delete serviceaccount pcm-executor -n clicklink-system

この grant により clicklink-system ネームスペースも作成されています。他に使用しているものがなければ削除してください。

Kubernetes

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

executor の PersistentVolumeClaim には helm.sh/resource-policy: keep のアノテーションが付与されているため、アンインストールしてもコマンドデータベースとservice registryを保持したまま残ります。init が作成した Secret、platform approve によって書き込まれたプラットフォームバンドル Secret、および executor が管理するservice registryの ConfigMap も同様にチャートの管理対象外であり、アンインストール後も残ります。これらは明示的に削除してください。その際、自分で登録したすべてのインスタンス、およびトラブルシューターをプロビジョニングしたすべてのマネージドサービスに対応するアクセス Secret と ServiceAccount のペア (サービス名に基づく名前) も削除対象に含めてください。--ignore-not-found を指定しておけば、初回承認前のプラットフォームバンドル Secret のように、そもそも作成されていないオブジェクトがあっても問題ありません:

kubectl delete pvc -n "${CONNECTOR_NAMESPACE}" -l app.kubernetes.io/instance=clicklink-connector --ignore-not-found
kubectl delete secret clicklink-hmac clicklink-mtls clicklink-platform-bundle -n "${CONNECTOR_NAMESPACE}" --ignore-not-found
kubectl delete configmap clicklink-instance-registry -n "${CONNECTOR_NAMESPACE}" --ignore-not-found
kubectl delete secret -n "${CONNECTOR_NAMESPACE}" --ignore-not-found \
  clicklink-connector-scraper-access-<instance> \
  clicklink-connector-troubleshooter-access-<instance>
kubectl delete serviceaccount -n "${CONNECTOR_NAMESPACE}" --ignore-not-found \
  pcm-scraper-<instance> pcm-troubleshooter-<instance>
# Repeat for every ClickHouse namespace that holds an instance you registered yourself;
# a managed service's namespace went away with the service.
for ns in <clickhouse-namespace-1> <clickhouse-namespace-2>; do
  kubectl delete serviceaccount,role,rolebinding -n "${ns}" --ignore-not-found \
    pcm-scraper pcm-troubleshooter
done

init が適用したのは executor のクラスター全体の grant であり、chart ではありません。managed service がすべて削除された後に、クラスターの Admin として削除してください:

kubectl delete validatingadmissionpolicybinding pcm-executor-prefix-guard
kubectl delete validatingadmissionpolicy pcm-executor-prefix-guard
kubectl delete clusterrolebinding pcm-executor-cluster
kubectl delete clusterrole pcm-executor-cluster
kubectl delete serviceaccount pcm-executor -n "${CONNECTOR_NAMESPACE}"

プラットフォームレイヤー

コネクタをアンインストールしても、プラットフォームレイヤーは削除されません。プラットフォームのネームスペースとワークロード、pcm-platform の RBAC、および承認によってインストールされた admission object はクラスター内に残り、すべてのマネージドサービスも残ったままになります。まずは service を削除してください。詳細は delete a service を参照してください。service が存在しないテストクラスターであれば、clicklink clctl platform reset でプラットフォームのリリースをアンインストールできます。残された CustomResourceDefinition、RBAC、StorageClass は手動で削除する必要があります。詳細は resetting a test cluster を参照してください。テストクラスター以外では、プラットフォームレイヤーに手を加える前に、アカウントチームと削除計画について合意してください。

ClickHouse ユーザー

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

DROP USER IF EXISTS pcm_scraper, pcm_troubleshooter;

はじめる

サービスとインフラストラクチャ

Bring Your Own Cloud

データとインテグレーション

接続とクエリ実行

アクセス管理

セキュリティとコンプライアンス

監視とバックアップ

AI ツールとエージェント

Cloud API

請求

サポート

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 ユーザー