Kubernetes の監視

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

前提条件

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

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

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

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

• オープンソース版 ClickStack: Kubernetes クラスター内に ClickStack を完全にデプロイします（以下を含む）:

  • ClickHouse
  • HyperDX
  • MongoDB（ダッシュボードの状態および設定に使用）

• マネージド ClickStack: ClickHouse と ClickStack UI（HyperDX）が ClickHouse Cloud 上で管理されます。これにより、クラスター内で 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/

このデモの詳細については、以下を参照してください。

• OpenTelemetry のドキュメント
• ClickStack が保守しているフォーク

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 環境内で実行するか、コレクターのみをデプロイして ClickHouse と UI HyperDX については Managed ClickStack に依存するかを選択できます。

ClickStack オープンソース（セルフマネージド）

次のコマンドは、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 を無効化するには、次の値を設定してください:

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

マネージド ClickStack

Managed ClickStack を利用したい場合は、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 状態であることを確認してください。なお、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

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

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

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

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

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

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にデプロイしたインスタンス、またはManaged ClickStack経由のいずれかを使用します。

マネージド ClickStack

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

ログ、メトリクス、トレース用のデータソースはあらかじめ作成されています。

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 in production

本番環境では、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/kubernetes）。

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