Kubernetes の監視

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

前提条件

このガイドを進めるには、次のものが必要です：

Kubernetes クラスター（v1.20 以上を推奨）で、少なくとも 32 GiB の RAM と、1 ノード上に ClickHouse 用として 100 GB の空きディスク容量があること
Helm v3 以上
クラスターを操作できるように設定された kubectl

デプロイメントのオプション

このガイドは、次のいずれかのデプロイメントオプションで進めることができます。

セルフホスト型: Kubernetes クラスター内に ClickStack を完全にデプロイします（以下を含む）:
- ClickHouse
- HyperDX
- MongoDB（ダッシュボードの状態および設定に使用）
クラウドホスト型: ClickHouse Cloud を使用し、HyperDX はクラスター外で管理します。これにより、クラスター内で ClickHouse や HyperDX を実行する必要がなくなります。

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

cert-managerのインストール（オプション）

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

# Add Cert manager repo 

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デモのデプロイ（オプション）

この手順は任意であり、監視対象となる既存のポッドがない場合を想定しています。Kubernetes環境に既存のサービスがデプロイされているユーザーはスキップできますが、このデモにはインストルメント化されたマイクロサービスが含まれており、トレースとセッションリプレイのデータを生成するため、ClickStackの全機能を確認できます。

以下では、オブザーバビリティのテストと計装のデモンストレーションに最適化された、ClickStackフォーク版のOpenTelemetry Demo ApplicationスタックをKubernetesクラスタにデプロイします。バックエンドマイクロサービス、負荷生成ツール、テレメトリパイプライン、サポートインフラストラクチャ(Kafka、Redisなど)、およびClickStackとのSDK統合が含まれます。

すべてのサービスはotel-demoネームスペースにデプロイされます。各デプロイメントには次の内容が含まれます:

OTel および ClickStack SDKS によるトレース、メトリクス、ログの自動インストルメンテーション。
すべてのサービスは、my-hyperdx-hdx-oss-v2-otel-collector という名前の OpenTelemetry コレクター（まだデプロイされていない）にインストルメンテーションデータを送信します
リソースタグのポッドへの転送を通じて、環境変数 OTEL_RESOURCE_ATTRIBUTES を介してログ、メトリクス、トレースを相関付けます。

## download demo Kubernetes manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
# wget alternative
# 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 環境内で実行するか、HyperDX がマネージドサービスとして提供されている ClickHouse Cloud を使用するかを選択できます。

セルフマネージドデプロイメント

次のコマンドは、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 を使用するか、ClickHouse Cloud を利用することを推奨します。

ClickHouse と OTel collector を無効化するには、次の値を設定してください:

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

:::

ClickHouse Cloud の使用

ClickHouse Cloud を利用したい場合は、ClickStack をデプロイして、同梱の ClickHouse を無効化できます。

注記

現時点では、このチャートは常に HyperDX と MongoDB の両方をデプロイします。これらのコンポーネントは別経路でのアクセス手段を提供しているものの、ClickHouse Cloud の認証とは統合されていません。このデプロイメントモデルでは、デプロイ済みの OTel collector 経由でインジェストするために必要なセキュアなインジェスト API キーへのアクセスを提供する管理者向けコンポーネントとして想定されており、エンドユーザーに公開すべきではありません。

# specify ClickHouse Cloud credentials
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # full 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 状態であることを確認してください。なお、ClickHouse Cloud を使用している場合、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へのアクセス

注記

ClickHouse Cloudを使用する場合でも、KubernetesクラスタにデプロイされたローカルのHyperDXインスタンスは引き続き必要です。HyperDXにバンドルされているOpAMPサーバーが管理するインジェストキーを提供し、デプロイされたOTel collectorを通じて安全なインジェストを実現します。この機能は現在、ClickHouse Cloudのホスト版では提供されていません。

セキュリティのため、このサービスは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

http://localhost:8080 にアクセスして HyperDX UI を開きます。

複雑性要件を満たすユーザー名とパスワードを指定してユーザーを作成します。

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

ClickStack collectorによってデプロイされたOTel collectorへのインジェストは、インジェストキーで保護されています。

Team Settings に移動し、API Keys セクションから Ingestion API Key をコピーします。このインジェスト API key により、OpenTelemetry コレクターを通じたデータインジェストが安全に行われます。

API キー Kubernetes Secret の作成

インジェスト API key を含む新しい Kubernetes secret と、ClickStack Helm チャートでデプロイされた OTel collector の場所を含む config map を作成します。後続のコンポーネントは、これを使用して ClickStack Helm チャートでデプロイされた collector へのインジェストを可能にします:

# create secret with the ingestion API key
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \
-n otel-demo

# create a ConfigMap pointing to the ClickStack OTel collector deployed above
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リポジトリをインストールする必要があります:

# Add Otel Helm repo
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts

Kubernetesコレクターコンポーネントのデプロイ

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

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

これらのマニフェストにより、インフラストラクチャからアプリケーションレベルのテレメトリまで、クラスタ全体のフルスタックオブザーバビリティが実現され、エンリッチされたデータがClickStackに送信されて一元的な分析が行われます。

まず、コレクターをデプロイメントとしてインストールします：

# download manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml
# install the helm chart
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
 
# We only want one of these collectors - any more and we'd produce duplicate data
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # When enabled, the processor will extract all labels for an associated pod and add them as resource attributes.
    # The label's exact name will be the key.
    extractAllPodLabels: true
    # When enabled, the processor will extract all annotations for an associated pod and add them as resource attributes.
    # The annotation's exact name will be the key.
    extractAllPodAnnotations: true
  # Configures the collector to collect Kubernetes events.
  # Adds the k8sobject receiver to the logs pipeline and collects Kubernetes events by default.
  # More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Configures the Kubernetes Cluster Receiver to collect cluster-level metrics.
  # Adds the k8s_cluster receiver to the metrics pipeline and adds the necessary rules to ClusteRole.
  # More Info: 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

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

# download manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml
# install the helm chart
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
   
# Required to use the kubeletstats cpu/memory utilization metrics
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get
 
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Configures the Kubernetes Processor to add Kubernetes metadata.
  # Adds the k8sattributes processor to all the pipelines and adds the necessary rules to ClusterRole.
  # More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # When enabled, the processor will extract all labels for an associated pod and add them as resource attributes.
    # The label's exact name will be the key.
    extractAllPodLabels: true
    # When enabled, the processor will extract all annotations for an associated pod and add them as resource attributes.
    # The annotation's exact name will be the key.
    extractAllPodAnnotations: true
  # Configures the collector to collect node, pod, and container metrics from the API server on a kubelet..
  # Adds the kubeletstats receiver to the metrics pipeline and adds the necessary rules to ClusterRole.
  # More Info: 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:
    # Configures additional kubelet metrics
    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データを探索する

HyperDX UIにアクセスします。Kubernetesにデプロイしたインスタンス、またはClickHouse Cloud経由のいずれかを使用します。

ClickHouse Cloud の使用

ClickHouse Cloud を使用する場合は、ClickHouse Cloud サービスにログインし、左側のメニューから「HyperDX」を選択するだけです。自動的に認証されるため、ユーザーを作成する必要はありません。

データソースの作成を求められたら、作成モーダル内のデフォルト値はすべてそのままにし、Table フィールドに値 otel_logs を入力してログ用のソースを作成します。その他の設定は自動検出されるため、Save New Source をクリックできます。

トレースとメトリクス用のデータソースも作成する必要があります。

たとえば、トレースおよび OTel メトリクス用のソースを作成するには、上部メニューから Create New Source を選択します。

ここからは、必要なソース種別を選択し、続いて適切なテーブルを選択します。たとえばトレースの場合は、テーブル otel_traces を選択します。すべての設定は自動検出されます。

ソースの相関付け

ClickStack 内の異なるデータソース（ログやトレースなど）は、互いに相関付けることができる点に注意してください。これを有効にするには、各ソースで追加の設定が必要です。たとえばログソースでは、対応するトレースソースを指定でき、逆にトレースソース側でもログソースを指定できます。詳細については「相関ソース」を参照してください。

セルフマネージドデプロイメントを使用する

ローカルにデプロイされた HyperDX にアクセスするには、kubectl port-forward を実行してポートフォワーディングを行い、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

本番環境では、ClickHouse Cloud 上で HyperDX を使用していない場合、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/kubernetes）。

各タブ(ポッド、ノード、ネームスペース)にデータが入力されている必要があります。

前提条件​

デプロイメントのオプション​

cert-managerのインストール（オプション）​

OpenTelemetryデモのデプロイ（オプション）​

デモのアーキテクチャ​

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

ClickStackのデプロイ​

HyperDX UIへのアクセス​

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

API キー Kubernetes Secret の作成​

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

Kubernetesコレクターコンポーネントのデプロイ​

HyperDXでKubernetesデータを探索する​