PrometheusとGrafanaによるHarbor Container Registry監視ガイド

Monitoring tutorial - IT technology blog
Monitoring tutorial - IT technology blog

深夜2時の悪夢:Harborのディスクが枯渇したとき

午前2時15分、携帯電話のアラートが一斉に鳴り響きました。当直チームから送られてきたCI/CDパイプラインのスクリーンショットは真っ赤に染まり、Error: write /var/lib/docker/tmp/docker-builder...: no space left on device というエラーを出力していました。それに伴い、本番Kubernetesクラスタ上の40近いデプロイメントが次々と ImagePullBackOff に陥っていきました。

急いでHarborの管理ダッシュボードを開いたものの、画面は読み込みのまま応答しません。アーティファクト保管用の2TBストレージは使用率99.8%に達していました。さらに最悪なことに、DR(ディザスタリカバリ)用バックアップクラスタへのレプリケーション処理が6時間も停止していたにもかかわらず、どのアラートチャネルにも通知が飛んでいませんでした。

60人以上のエンジニアが利用するコンテナレジストリをメトリクスなしで運用するのは、明かりを持たずに夜道を歩くようなものです。重大なインシデントが発生してからテキストログを掘り起こしても、すでに手遅れなのです。

Harborはどのようにメトリクスを公開しているか?

Harborはバージョン2.2以降、ネイティブなPrometheusエンドポイントを標準搭載しています。外部のエクスポーターを追加インストールする必要はありません。

メトリクスは主に以下の2系統に分かれています:

  • Harbor Core Metrics: プロジェクトのクォータ状態、実際のストレージ使用量、アーティファクト数、レプリケーションタスクの進捗などをレポートします。
  • Registry Metrics: HTTPステータス(200、404、500)のトラフィック、レイテンシ、そして docker push や docker pull の実行頻度を記録します。

Harborはこれらの情報をデフォルトでポート9090の /metrics パスに集約します。Prometheusが定期的にデータをスクレイピングしてTSDBに格納し、Grafanaがそのデータを読み取ってダッシュボードに可視化します。

Prometheus & Grafana 連携のステップ

ステップ1: harbor.yml でメトリクスエンドポイントを有効化する

Harborがインストールされているサーバーにアクセスし、設定ディレクトリに移動します:

cd /opt/harbor
sudo vim harbor.yml

metric ブロックを見つけ、以下のように編集します:

metric:
  enabled: true
  port: 9090
  path: /metrics

ファイルを保存し、コンテナの設定を再反映します:

sudo ./prepare
sudo docker compose down
sudo docker compose up -d

ローカルホストで curl コマンドを実行し、エクスポーターをテストします:

curl -s http://127.0.0.1:9090/metrics | head -n 20

ターミナルに # HELP harbor_... で始まるプレフィックスが出力されれば、エンドポイントは正常に動作しています。

ステップ2: Prometheus にスクレイプターゲットを設定する

監視サーバー上の prometheus.yml を開き、新しいジョブを追加します:

scrape_configs:
  - job_name: 'harbor-monitoring'
    scrape_interval: 15s
    scrape_timeout: 10s
    static_configs:
      - targets: ['192.168.10.20:9090']
        labels:
          env: 'production'
          service: 'registry-harbor'

プロセスを停止せずにPrometheusの設定をリロードします:

curl -X POST http://localhost:9090/-/reload

PrometheusのWeb UIで Status > Targets メニューを開きます。ターゲット harbor-monitoring のステータスが緑色の UP に変わっていれば準備完了です。

ステップ3: 重要なPromQLクエリを設定する

Grafanaダッシュボードに必ず組み込んでおくべき3つの主要クエリを紹介します。

1. プロジェクトごとのストレージクォータ使用率

単一のリポジトリが急激に肥大化してクラスタ全体を巻き込む事態を防ぎます。使用済み容量の割合を算出するクエリ:

# プロジェクトごとのストレージ使用率(%)
(harbor_project_quota_used_bytes / harbor_project_quota_total_bytes) * 100

プロジェクトに固定クォータを設定していない場合は、実際の消費容量をギガバイト(GB)単位で監視するように切り替えます:

# 消費容量をGB単位に換算
harbor_project_quota_used_bytes{project_name="core-banking"} / 1024 / 1024 / 1024

2. イメージのPull / Push頻度

このメトリクスにより、CI/CDのエラーループや、特定ワーカーノードによる無限イメージPullの発生を早期に検知できます:

# イメージのPullレート(req/s)
sum(rate(harbor_registry_http_requests_total{handler="/v2/{name:.*}/manifests/{reference:.*}", method="GET"}[5m]))

# 新規イメージのPushレート(req/s)
sum(rate(harbor_registry_http_requests_total{handler="/v2/{name:.*}/blobs/uploads/{uuid:.*}", method="PUT"}[5m]))

3. クラスタ間のレプリケーションステータス

予備のDRクラスタへ同期する際、いずれかのタスクが失敗した場合は即座に検知する必要があります:

# 直近10分間で失敗したレプリケーションタスク数
increase(harbor_replication_task_total{status="failed"}[10m])

ステップ4: アラートルールの設定とアラート疲れ対策

アラートが頻発しすぎると、オンコール担当者の対応が形骸化してしまいます。当初、筆者はストレージ使用率80%・待機時間 for: 1m でアラートを設定していました。その結果、開発者がマルチステージビルドを実行したりキャッシュクリアを行ったりするたびに深夜のTelegramが鳴り響き、メンバーは疲弊して通知をミュートするようになってしまいました。

解決策は、適切な待機時間を設けて2段階のしきい値に分けることです:

groups:
  - name: harbor_alerts
    rules:
      - alert: HarborStorageQuotaWarning
        expr: (harbor_project_quota_used_bytes / harbor_project_quota_total_bytes) * 100 > 85
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "Harborプロジェクト {{ $labels.project_name }} のストレージ使用率が85%に到達しました"
          description: "プロジェクトの容量が30分連続して85%を超えています。アーティファクトのクリーンアップを計画してください。"

      - alert: HarborStorageQuotaCritical
        expr: (harbor_project_quota_used_bytes / harbor_project_quota_total_bytes) * 100 > 95
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Harborプロジェクト {{ $labels.project_name }} のディスクが溢れそうです"
          description: "容量が95%を超過しました。直ちに古いイメージを削除するか、クォータを拡張してください。"

      - alert: HarborReplicationFailed
        expr: increase(harbor_replication_task_total{status="failed"}[5m]) > 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "レプリケーションタスクが失敗しました"
          description: "DRクラスタへのイメージ同期に失敗しました。ネットワーク接続または認証トークンを確認してください。"

85%の警告判定に30分の猶予を設けることで、一時的なビルド負荷による誤検知を排除できます。一方で95%の危険水準は5分で発火させ、システム停止のリスクが迫った際にはオンコールエンジニアを即座に叩き起こします。

まとめ

Dockerデーモンが no space left on device エラーを吐き出してから慌てて不要ファイルの削除に追われてはいけません。ストレージクォータ、リクエストレート、レプリケーション状態のメトリクス監視は、わずか20分ほどの設定で構築できます。これによりストレージ基盤の健全性を完全に把握し、CI/CDパイプラインを常に安定稼働させることが可能になります。

Share: