Docker Scout 指標匯出器

目錄

Docker Scout 公開了一個指標 HTTP 端點，讓您可以使用 Prometheus 或 Datadog 從 Docker Scout 抓取弱點和策略資料。藉此，您可以建立自己的 Docker Scout 自我託管儀表板，以視覺化供應鏈指標。

指標

指標端點公開以下指標

指標說明標籤類型
scout_stream_vulnerabilities串流中的弱點streamName、severityGauge (計量器)
scout_policy_compliant_images串流中符合策略的映像檔id、displayName、streamNameGauge (計量器)
scout_policy_evaluated_images針對串流中的策略評估的映像檔總數id、displayName、streamNameGauge (計量器)

串流

在 Docker Scout 中，串流概念是環境的超集合。串流包含您定義的所有執行階段環境，以及特殊的 `latest-indexed` 串流。 `latest-indexed` 串流包含每個儲存庫中最新推送（和分析）的標籤。

除了透過此指標端點公開的資料外，串流主要是一個 Docker Scout 內部的概念。

建立存取權杖

要從您的組織匯出指標，首先請確認您的組織已註冊 Docker Scout。然後，建立個人存取權杖 (PAT) - 一個允許匯出器向 Docker Scout API 進行驗證的密鑰。

PAT 不需要任何特定權限，但它必須由 Docker 組織的擁有者建立。要建立 PAT，請按照建立存取權杖中的步驟操作。

建立 PAT 後，將其儲存在安全的位置。抓取指標時，您需要將此權杖提供給匯出器。

Prometheus

本節說明如何使用 Prometheus 抓取指標端點。

為您的組織新增作業

在 Prometheus 設定檔中，為您的組織新增一個新的作業。該作業應包含以下設定；將 `ORG` 替換為您的組織名稱

scrape_configs:
  - job_name: <ORG>
    metrics_path: /v1/exporter/org/<ORG>/metrics
    scheme: https
    static_configs:
      - targets:
          - api.scout.docker.com

`targets` 欄位中的地址設定為 Docker Scout API 的網域名稱 `api.scout.docker.com`。請確定沒有任何防火牆規則阻止伺服器與此端點通訊。

新增 Bearer 權杖驗證

要使用 Prometheus 從 Docker Scout Exporter 端點抓取指標，您需要將 Prometheus 設定為使用 PAT 作為 Bearer 權杖。匯出器要求在請求的 `Authorization` 標頭中傳遞 PAT。

更新 Prometheus 設定檔以包含 `authorization` 設定區塊。此區塊將 PAT 定義為儲存在檔案中的 Bearer 權杖

scrape_configs:
  - job_name: $ORG
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/token

檔案的內容應為純文字格式的 PAT

dckr_pat_...

如果您在 Docker 容器或 Kubernetes Pod 中執行 Prometheus，請使用磁碟區或密钥將檔案掛載到容器中。

最後，重新啟動 Prometheus 以套用變更。

Prometheus 範例專案

如果您沒有設定 Prometheus 伺服器，您可以使用 Docker Compose 執行範例專案

$ git clone git@github.com:dockersamples/scout-metrics-exporter.git
$ cd scout-metrics-exporter/prometheus

  • 建立 Docker 存取權杖並將其儲存在範本目錄下 `/prometheus/prometheus/token` 的純文字檔案中。

    權杖
    $ echo $DOCKER_PAT > ./prometheus/token

  • 在 Prometheus 設定檔 `/prometheus/prometheus/prometheus.yml` 中，將第 6 行 `metrics_path` 屬性中的 `ORG` 替換為您的 Docker 組織的命名空間(namespace)。

    prometheus/prometheus.yml
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

    global:
  scrape_interval: 60s
  scrape_timeout: 40s
scrape_configs:
  - job_name: Docker Scout policy
    metrics_path: /v1/exporter/org/<ORG>/metrics
    scheme: https
    static_configs:
      - targets:
          - api.scout.docker.com
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/token

  • 啟動 Compose 服務。

    docker compose up -d

    此命令會啟動兩項服務：Prometheus 伺服器和 Grafana。Prometheus 從 Docker Scout 端點抓取指標，Grafana 使用預先設定的儀表板將指標視覺化。

    • 要停止展示並清除建立的任何資源，請執行

    docker compose down -v

    存取 Prometheus

    啟動服務後，您可以透過造訪http://localhost:9090http://localhost:9090/targets。

    Docker Scout metrics exporter Prometheus target
    Docker Scout 指標匯出器 Prometheus 目標

    在 Grafana 中檢視指標

    要檢視 Grafana 儀表板，請前往 http://localhost:3000/dashboards，並使用 Docker Compose 檔案中定義的憑證登入（使用者名稱：admin，密碼：grafana）。

    Vulnerability dashboard in Grafana
    Grafana 中的漏洞儀表板
    Policy dashboard in Grafana
    Grafana 中的策略儀表板

    儀表板已預先設定為可視化 Prometheus 所擷取的漏洞和策略指標。

    Datadog

    本節說明如何使用 Datadog 擷取指標端點。Datadog 會透過執行可自訂的 代理程式 來提取監控資料，該代理程式會擷取任何公開指標的可用端點。OpenMetrics 和 Prometheus 檢查都包含在代理程式中，因此您不需要在容器或主機上安裝任何其他軟體。

    本指南假設您擁有 Datadog 帳戶和 Datadog API 金鑰。請參閱 Datadog 文件設定 Datadog 代理程式

    要開始收集指標，您需要編輯 OpenMetrics 檢查的代理程式設定檔。如果您將代理程式作為容器執行，則必須將該檔案掛載到 /etc/datadog-agent/conf.d/openmetrics.d/conf.yaml。

    以下範例顯示 Datadog 設定，該設定

    instances:
  - openmetrics_endpoint: "https://api.scout.docker.com/v1/exporter/org/dockerscoutpolicy/metrics"
    namespace: "scout-metrics-exporter"
    metrics:
      - scout_*
    auth_token:
      reader:
        type: file
        path: /var/run/secrets/scout-metrics-exporter/token
      writer:
        type: header
        name: Authorization
        value: Bearer <TOKEN>

    **重要**

    請勿取代先前設定範例中的 <TOKEN> 預留位置。它必須保持原樣。只需確保 Docker PAT 正確掛載到指定檔案系統路徑中的 Datadog 代理程式即可。將檔案儲存為 conf.yaml 並重新啟動代理程式。

    建立您自己的 Datadog 代理程式設定時，請務必編輯 openmetrics_endpoint 屬性以將您的組織設為目標，方法是將 dockerscoutpolicy 替換為 Docker 組織的命名空間。

    Datadog 範例專案

    如果您沒有設定 Datadog 伺服器，您可以使用 Docker Compose 執行 範例專案

    $ git clone git@github.com:dockersamples/scout-metrics-exporter.git
$ cd scout-metrics-exporter/datadog

  • 建立 Docker 存取權杖 並將其儲存在範本目錄下 /datadog/token 的純文字檔案中。

    權杖
    $ echo $DOCKER_PAT > ./token

  • 在 /datadog/compose.yaml 檔案中，使用 Datadog 部署的值更新 DD_API_KEY 和 DD_SITE 環境變數。

      datadog-agent:
    container_name: datadog-agent
    image: gcr.io/datadoghq/agent:7
    environment:
      - DD_API_KEY=${DD_API_KEY} # e.g. 1b6b3a42...
      - DD_SITE=${DD_SITE} # e.g. datadoghq.com
      - DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./conf.yaml:/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml:ro
      - ./token:/var/run/secrets/scout-metrics-exporter/token:ro

    volumes 區段會將主機上的 Docker 通訊端掛載到容器。作為容器執行時，這是取得準確主機名稱的必要條件（更多詳細資訊請參閱此處

    instances:
  - openmetrics_endpoint: "https://api.scout.docker.com/v1/exporter/org/<<ORG>>/metrics"
    namespace: "scout-metrics-exporter"
# ...

  • 啟動 Compose 服務。

    docker compose up -d

    • 如果設定正確，當您執行代理程式的狀態命令時，您應該會在「執行中檢查」下看到 OpenMetrics 檢查，其輸出應該類似於

    openmetrics (4.2.0)
-------------------
  Instance ID: openmetrics:scout-prometheus-exporter:6393910f4d92f7c2 [OK]
  Configuration Source: file:/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml
  Total Runs: 1
  Metric Samples: Last Run: 236, Total: 236
  Events: Last Run: 0, Total: 0
  Service Checks: Last Run: 1, Total: 1
  Average Execution Time : 2.537s
  Last Execution Date : 2024-05-08 10:41:07 UTC (1715164867000)
  Last Successful Execution Date : 2024-05-08 10:41:07 UTC (1715164867000)

    如需選項的完整清單，請查看此 範例設定檔 以了解通用 OpenMetrics 檢查。

    將您的資料視覺化

    代理程式設定好抓取 Prometheus 指標後，您就可以使用它們來建置完整的 Datadog 圖表、儀表板和警報。

    前往您的 指標摘要頁面 以查看從此範例收集的指標。此設定將收集所有以 scout_ 開頭且命名空間為 scout_metrics_exporter 的公開指標。

    datadog_metrics_summary

    以下螢幕截圖顯示 Datadog 儀表板的範例，其中包含特定 串流 的弱點和政策合規性圖表。

    datadog_dashboard_1
    datadog_dashboard_2

    圖表中的線條看起來很平坦的原因是由於弱點本身的性質（它們不會經常變化）以及日期選擇器中選擇的短時間間隔。

    抓取間隔

    根據預設，Prometheus 和 Datadog 每 15 秒抓取一次指標。由於弱點資料本身的性質，透過此 API 公開的指標不太可能頻繁變更。因此，指標端點預設具有 60 分鐘的快取，這表示建議的抓取間隔為 60 分鐘或更長。如果您將抓取間隔設定為少於 60 分鐘，您將在該時間範圍內看到多個抓取的指標中的相同資料。

    要更改抓取間隔