Kubernetes の監視 - ClickHouse Documentation

このガイドでは、Kubernetes システムからログとメトリクスを収集し、可視化と分析のために ClickStack に送信できます。デモデータとして、必要に応じて公式 OpenTelemetry デモの ClickStack フォークを使用します。

前提条件

このガイドを進めるには、以下が必要です。

ClickHouse 用に、少なくとも 1 つのノードで 32 GiB の RAM と 100GB のディスク容量を利用できる Kubernetes クラスター (v1.20 以降を推奨)
Helm v3 以降
クラスターにアクセスできるよう設定された kubectl

デプロイオプション

このガイドは、次のいずれかのデプロイオプションで進められます。

Open Source ClickStack: 以下を含め、ClickStack を Kubernetes クラスター内に完全にデプロイします。
- ClickHouse
- HyperDX
- MongoDB (ダッシュボードの状態管理と設定に使用)
Managed ClickStack: ClickHouse と ClickStack UI (HyperDX) は ClickHouse Cloud で管理されます。これにより、クラスター内で ClickHouse や HyperDX を実行する必要がなくなります。

アプリケーショントラフィックをシミュレートするには、必要に応じて OpenTelemetry Demo Application の ClickStack フォークをデプロイできます。これにより、ログ、メトリクス、トレースを含むテレメトリーデータが生成されます。すでにクラスター内でワークロードが稼働している場合は、この手順を省略して、既存のポッド、ノード、コンテナーを監視できます。

cert-manager をインストールする (任意)

TLS 証明書が必要な場合は、Helm を使用して cert-manager をインストールします。

# Cert manager リポジトリを追加する 

helm repo add jetstack https://charts.jetstack.io 

helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set startupapicheck.timeout=5m --set installCRDs=true --set global.leaderElection.namespace=cert-manager

OpenTelemetry Demo をデプロイする (任意)

このステップは任意で、監視対象の既存のポッドがない場合を想定しています。Kubernetes 環境にすでにサービスをデプロイしている場合はスキップできますが、このデモにはトレースとセッションリプレイのデータを生成するインストルメント済みのマイクロサービスが含まれているため、ClickStack のすべての機能を試すことができます。以下では、オブザーバビリティのテストとインストルメンテーションの実演向けに調整された、OpenTelemetry Demo Application スタックの ClickStack フォーク版を Kubernetes クラスター内にデプロイします。これには、バックエンドのマイクロサービス、ロードジェネレーター、テレメトリーパイプライン、補助的なインフラストラクチャ (例: Kafka、Redis) 、および ClickStack との SDK インテグレーションが含まれます。すべてのサービスは otel-demo ネームスペースにデプロイされます。各デプロイメントには次が含まれます:

トレース、メトリクス、ログ向けの、OTel と ClickStack SDKS による自動インストルメンテーション。
すべてのサービスは、インストルメンテーションデータを my-hyperdx-hdx-oss-v2-otel-collector OpenTelemetry collector (未デプロイ) に送信します
環境変数 OTEL_RESOURCE_ATTRIBUTES を介してログ、メトリクス、トレースを相関付けるためのリソースタグの転送。

## デモ用 Kubernetes マニフェストファイルをダウンロード
curl -O https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
# wget を使う場合の代替コマンド
# wget https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
kubectl apply --namespace otel-demo -f opentelemetry-demo.yaml

デモをデプロイしたら、すべてのポッドが正常に作成され、Running 状態になっていることを確認します：

kubectl get pods -n=otel-demo

NAME                                 READY   STATUS    RESTARTS   AGE
accounting-fd44f4996-fcl4k           1/1     Running   0          13m
ad-769f968468-qq8mw                  1/1     Running   0          13m
artillery-loadgen-7bc4bdf47d-5sb96   1/1     Running   0          13m
cart-5b4c98bd8-xm7m2                 1/1     Running   0          13m
checkout-784f69b785-cnlpp            1/1     Running   0          13m
currency-fd7775b9c-rf6cr             1/1     Running   0          13m
email-5c54598f99-2td8s               1/1     Running   0          13m
flagd-5466775df7-zjb4x               2/2     Running   0          13m
fraud-detection-5769fdf75f-cjvgh     1/1     Running   0          13m
frontend-6dcb696646-fmcdz            1/1     Running   0          13m
frontend-proxy-7b8f6cd957-s25qj      1/1     Running   0          13m
image-provider-5fdb455756-fs4xv      1/1     Running   0          13m
kafka-7b6666866d-xfzn6               1/1     Running   0          13m
load-generator-57cbb7dfc9-ncxcf      1/1     Running   0          13m
payment-6d96f9bcbd-j8tj6             1/1     Running   0          13m
product-catalog-7fb77f9c78-49bhj     1/1     Running   0          13m
quote-576c557cdf-qn6pr               1/1     Running   0          13m
recommendation-546cc68fdf-8x5mm      1/1     Running   0          13m
shipping-7fc69f7fd7-zxrx6            1/1     Running   0          13m
valkey-cart-5f7b667bb7-gl5v4         1/1     Running   0          13m

デモアーキテクチャ

このデモは、異なるプログラミング言語で実装され、gRPC と HTTP 経由で相互に通信するマイクロサービス群と、Locust を使用してユーザートラフィックを擬似的に生成するロードジェネレーターで構成されています。このデモの元のソースコードは、ClickStack インストルメンテーションを使用するよう変更されています。出典: https://opentelemetry.io/docs/demo/architecture/このデモの詳細については、以下を参照してください。

ClickStack の Helm チャートリポジトリを追加する

ClickStack をデプロイするには、公式の Helm チャートを使用します。そのため、HyperDX の Helm リポジトリを追加する必要があります。

helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo update

ClickStack をデプロイする

Helm チャートをインストールしたら、ClickStack をクラスターにデプロイできます。ClickHouse や HyperDX を含むすべてのコンポーネントを Kubernetes 環境内で実行することも、collector のみをデプロイして、ClickHouse と HyperDX UI には Managed ClickStack を利用することもできます。

ClickStack Open Source（セルフマネージド）

次のコマンドは、otel-demo ネームスペースに ClickStack をインストールします。この helm チャートでは、以下がデプロイされます。

ClickHouse インスタンス
HyperDX
ClickStack ディストリビューションの OTel collector
HyperDX のアプリケーション状態を保存するための MongoDB

Kubernetes クラスターの構成に応じて、storageClassName の調整が必要になる場合があります。

OTel デモをデプロイしない場合は、適切なネームスペースを選んでこの設定を変更できます。

helm install my-hyperdx hyperdx/hdx-oss-v2   --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demo

本番環境の ClickStackこのチャートでは、ClickHouse と OTel collector もインストールされます。本番環境では、clickhouse と OTel collector の operator を使用するか、Managed ClickStack を使用することを推奨します。clickhouse と OTel collector を無効にするには、次の values を設定します。

helm install myrelease <chart-name-or-path> --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false

Managed ClickStack

Managed ClickStack を使用する場合は、ClickStack をデプロイし、同梱の ClickHouse を無効化できます。

現在、このチャートでは常に HyperDX と MongoDB の両方がデプロイされます。これらのコンポーネントは代替のアクセス経路を提供しますが、ClickHouse Cloud の認証とは統合されていません。このデプロイメントモデルでは、これらのコンポーネントは管理者向けであり、デプロイした OTel collector 経由でデータを取り込むために必要なセキュアなインジェストキーにアクセスできますが、エンドユーザーには公開すべきではありません。

# ClickHouse Cloud の認証情報を指定
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # 完全な https URL
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

helm install my-hyperdx hyperdx/hdx-oss-v2  --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} --set clickhouse.config.users.otelUserName=${CLICKHOUSE_USER} --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD} --set global.storageClassName="standard-rwo" -n otel-demo

デプロイメントのステータスを確認するには、次のコマンドを実行し、すべてのコンポーネントが Running 状態になっていることを確認してください。Managed ClickStack を使用している場合、ClickHouse は表示されません。

kubectl get pods -l "app.kubernetes.io/name=hdx-oss-v2" -n otel-demo

NAME                                                    READY   STATUS    RESTARTS   AGE
my-hyperdx-hdx-oss-v2-app-78876d79bb-565tb              1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-clickhouse-57975fcd6-ggnz2        1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-mongodb-984845f96-czb6m           1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-otel-collector-64cf698f5c-8s7qj   1/1     Running   0          14m

HyperDX UI にアクセスする

Managed ClickStack を使用する場合でも、Kubernetes クラスターにデプロイされたローカルの HyperDX インスタンスは引き続き必要です。これは、HyperDX に同梱された OpAMP サーバーによって管理されるインジェストキーを提供し、デプロイ済みの OTel collector を介した安全なインジェストを可能にするためです。この機能は、現時点では Managed ClickStack では利用できません。

セキュリティ上の理由から、このサービスは ClusterIP を使用しており、デフォルトでは外部に公開されません。HyperDX UI にアクセスするには、3000 からローカルポート 8080 へポートフォワードします。

kubectl port-forward \
 pod/$(kubectl get pod -l app.kubernetes.io/name=hdx-oss-v2 -o jsonpath='{.items[0].metadata.name}' -n otel-demo) \
  8080:3000 \
 -n otel-demo

HyperDX UI にアクセスするには、http://localhost:8080 にアクセスします。複雑さの要件を満たすユーザー名とパスワードを指定して、ユーザーを作成します。

インジェスト API key を取得する

ClickStack collector によってデプロイされた OTel collector へのインジェストは、インジェストキーで保護されています。Team Settings に移動し、API Keys セクションから Ingestion API Key をコピーします。この API key により、OpenTelemetry collector 経由のデータインジェストの安全性が確保されます。

API key 用の Kubernetes Secret を作成する

インジェスト API key と、ClickStack Helm チャートでデプロイした OTel collector の場所を格納した ConfigMap を含む、新しい Kubernetes Secret を作成します。後続のコンポーネントはこれを使用して、ClickStack Helm チャートでデプロイした collector へのインジェストを行えるようになります。

# インジェスト API key を使って secret を作成する
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \
-n otel-demo

# 上記でデプロイした ClickStack OTel collector を指す ConfigMap を作成する
kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=http://my-hyperdx-hdx-oss-v2-otel-collector:4318

インジェスト API keyを反映するため、OpenTelemetry Demo Applicationのポッドを再起動します。

kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demo

デモサービスからのトレースおよびログデータが、HyperDX に流れ始めるはずです。

OpenTelemetry Helm リポジトリを追加する

Kubernetes のメトリクスを収集するため、標準の OTel collector をデプロイし、上記のインジェスト API key を使ってデータを ClickStack collector に安全に送信するよう設定します。これには、OpenTelemetry Helm リポジトリをインストールする必要があります。

# OTel Helm リポジトリを追加する
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts 

Kubernetes collector コンポーネントのデプロイ

クラスター自体と各ノードの両方からログとメトリクスを収集するには、それぞれ独自のマニフェストを持つ2つの独立したOpenTelemetry Collectorをデプロイする必要があります。提供されている2つのマニフェスト (k8s_deployment.yaml と k8s_daemonset.yaml) は連携して機能し、Kubernetesクラスターから包括的なテレメトリーデータを収集します。

k8s_deployment.yaml は、クラスター全体のイベントとメタデータを収集する役割を持つ単一の OpenTelemetry Collector インスタンスをデプロイします。Kubernetes イベントとクラスターのメトリクスを収集し、ポッドのラベルやアノテーションを使ってテレメトリーデータを拡充します。データの重複を避けるため、この collector は 1 つのレプリカを持つスタンドアロンのデプロイメントとして実行されます。
k8s_daemonset.yaml は、クラスター内のすべてのノードで実行される デーモンセットベースの collector をデプロイします。これは、kubeletstats、hostmetrics、Kubernetes Attribute Processor などのコンポーネントを使用して、ノードレベルおよびポッドレベルのメトリクス に加え、コンテナーログも収集します。これらの collector はログにメタデータを付与し、OTLP エクスポーターを使用して HyperDX に送信します。

これらのマニフェストを組み合わせることで、インフラストラクチャからアプリケーションレベルのテレメトリーまで、クラスター全体にわたるフルスタックのオブザーバビリティが実現し、エンリッチされたデータを一元分析のためにClickStackへ送信します。まず、collector をデプロイメントとしてインストールします。

# マニフェストファイルをダウンロードする
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml
# Helm チャートをインストールする
helm install --namespace otel-demo k8s-otel-deployment open-telemetry/opentelemetry-collector -f k8s_deployment.yaml

k8s_deployment.yaml

# k8s_deployment.yaml
mode: deployment

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
 
# このcollectorは1つだけ必要です。複数あると重複データが生成されます
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # 有効にすると、プロセッサーは関連するポッドのすべてのラベルを抽出し、リソース属性として追加します。
    # ラベルの正確な名前がキーになります。
    extractAllPodLabels: true
    # 有効にすると、プロセッサーは関連するポッドのすべてのアノテーションを抽出し、リソース属性として追加します。
    # アノテーションの正確な名前がキーになります。
    extractAllPodAnnotations: true
  # collectorがKubernetesイベントを収集するよう設定します。
  # k8sobject receiverをlogsパイプラインに追加し、デフォルトでKubernetesイベントを収集します。
  # 詳細: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Kubernetes Cluster Receiverがクラスターレベルのメトリクスを収集するよう設定します。
  # k8s_cluster receiverをmetricsパイプラインに追加し、ClusterRoleに必要なルールを追加します。
  # 詳細: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-cluster-receiver
  clusterMetrics:
    enabled: true

extraEnvs:
  - name: HYPERDX_API_KEY
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: HYPERDX_API_KEY
        optional: true
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT
 
config:
  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

次に、ノードおよびポッドレベルのメトリクスとログを収集するため、collectorをデーモンセットとしてデプロイします。

# マニフェストファイルをダウンロードする
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml
# Helm チャートをインストールする
helm install --namespace otel-demo k8s-otel-daemonset open-telemetry/opentelemetry-collector -f k8s_daemonset.yaml

k8s_daemonset.yaml

# k8s_daemonset.yaml
mode: daemonset

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
   
# kubeletstats の CPU/メモリ使用率メトリクスを使用するために必要
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get
 
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Kubernetes メタデータを追加するために Kubernetes Processor を設定します。
  # k8sattributes プロセッサーをすべてのパイプラインに追加し、クラスター ロールに必要なルールを追加します。
  # 詳細: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # 有効にすると、プロセッサーは関連するポッドのすべてのラベルを抽出し、リソース属性として追加します。
    # ラベルの正確な名前がキーになります。
    extractAllPodLabels: true
    # 有効にすると、プロセッサーは関連するポッドのすべてのアノテーションを抽出し、リソース属性として追加します。
    # アノテーションの正確な名前がキーになります。
    extractAllPodAnnotations: true
  # キューブレット上の API サーバーからノード、ポッド、コンテナーのメトリクスを収集するように collector を設定します。
  # kubeletstats receiver をメトリクスパイプラインに追加し、クラスター ロールに必要なルールを追加します。
  # 詳細: https://opentelemetry.io/docs/kubernetes/collector/components/#kubeletstats-receiver
  kubeletMetrics:
    enabled: true

extraEnvs:
  - name: HYPERDX_API_KEY
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: HYPERDX_API_KEY
        optional: true
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT

config:
  receivers:
    # 追加のキューブレットメトリクスを設定します
    kubeletstats:
      collection_interval: 20s
      auth_type: 'serviceAccount'
      endpoint: '${env:K8S_NODE_NAME}:10250'
      insecure_skip_verify: true
      metrics:
        k8s.pod.cpu_limit_utilization:
          enabled: true
        k8s.pod.cpu_request_utilization:
          enabled: true
        k8s.pod.memory_limit_utilization:
          enabled: true
        k8s.pod.memory_request_utilization:
          enabled: true
        k8s.pod.uptime:
          enabled: true
        k8s.node.uptime:
          enabled: true
        k8s.container.cpu_limit_utilization:
          enabled: true
        k8s.container.cpu_request_utilization:
          enabled: true
        k8s.container.memory_limit_utilization:
          enabled: true
        k8s.container.memory_request_utilization:
          enabled: true
        container.uptime:
          enabled: true
 
  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
 
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

HyperDX で Kubernetes データを確認する

Kubernetes にデプロイしたインスタンスを使う場合も、Managed ClickStack を使う場合も、HyperDX UI にアクセスします。

Managed ClickStack

Managed ClickStack を使用している場合は、ClickHouse Cloud サービスにログインし、左側のメニューから “ClickStack” を選択するだけです。自動的に認証されるため、ユーザーを作成する必要はありません。ログ、メトリクス、トレース用のデータソースはあらかじめ作成されています。

ClickStack Open Source

ローカルにデプロイした HyperDX にアクセスするには、次のローカルコマンドでポートフォワードを実行し、http://localhost:8080 で HyperDX にアクセスします。

kubectl port-forward \
 pod/$(kubectl get pod -l app.kubernetes.io/name=hdx-oss-v2 -o jsonpath='{.items[0].metadata.name}' -n otel-demo) \
  8080:3000 \
 -n otel-demo

本番環境での ClickStack本番環境では、Managed ClickStack を使用していない場合、TLS を使用するイングレスの利用を推奨します。例:

helm upgrade my-hyperdx hyperdx/hdx-oss-v2 \
--set hyperdx.ingress.enabled=true \
--set hyperdx.ingress.host=your-domain.com \
--set hyperdx.ingress.tls.enabled=true

Kubernetes データを確認するには、/kubernetes の専用ダッシュボードに移動します。例: http://localhost:8080/kubernetesPods、Nodes、Namespaces の各タブには、それぞれデータが表示されているはずです。

​前提条件

​デプロイオプション

​cert-manager をインストールする (任意)

​OpenTelemetry Demo をデプロイする (任意)

​デモアーキテクチャ

​ClickStack の Helm チャートリポジトリを追加する

​ClickStack をデプロイする

​HyperDX UI にアクセスする

​インジェスト API key を取得する

​API key 用の Kubernetes Secret を作成する

​OpenTelemetry Helm リポジトリを追加する

​Kubernetes collector コンポーネントのデプロイ

​HyperDX で Kubernetes データを確認する

前提条件

デプロイオプション

cert-manager をインストールする (任意)

OpenTelemetry Demo をデプロイする (任意)

デモアーキテクチャ

ClickStack の Helm チャートリポジトリを追加する

ClickStack をデプロイする

HyperDX UI にアクセスする

インジェスト API key を取得する

API key 用の Kubernetes Secret を作成する

OpenTelemetry Helm リポジトリを追加する

Kubernetes collector コンポーネントのデプロイ

HyperDX で Kubernetes データを確認する