Docker Scout 指標匯出器

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

指標

指標端點會公開以下指標：

指標名稱	描述	Labels	類型
`scout_stream_vulnerabilities`	串流 (Stream) 中的弱點	`streamName`, `severity`	Gauge (測量值)
`scout_policy_compliant_images`	串流中符合政策的映像檔	`id`, `displayName`, `streamName`	Gauge (測量值)
`scout_policy_evaluated_images`	串流中針對某項政策評估的總映像檔數	`id`, `displayName`, `streamName`	Gauge (測量值)

串流 (Streams)
在 Docker Scout 中，「串流」概念是環境的超集。串流包含您定義的所有執行階段環境，以及特殊的 latest-indexed 串流。latest-indexed 串流包含每個儲存庫中最近推送（且已分析）的標籤 (Tag)。
除了透過此指標端點公開的資料外，串流在 Docker Scout 中主要是一個內部概念。

建立存取權杖

若要從您的組織匯出指標，請先確保您的組織已註冊 Docker Scout。接著，建立個人存取權杖 (PAT) —— 這是一個讓匯出工具能夠驗證 Docker Scout API 的秘密權杖。

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

建立 PAT 後，請將其儲存在安全的地方。您在抓取指標時需要將此權杖提供給匯出工具。

Prometheus

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

為您的組織新增任務 (Job)

在 Prometheus 設定檔中，為您的組織新增一個任務 (job)。該任務應包含以下設定；將 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 Token) 驗證

若要使用 Prometheus 從 Docker Scout 匯出工具端點抓取指標，您需要設定 Prometheus 使用 PAT 作為持有人權杖 (Bearer Token)。匯出工具要求在請求的 Authorization 標頭中傳遞 PAT。

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

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

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

dckr_pat_...

如果您在 Docker 容器或 Kubernetes Pod 中執行 Prometheus，請使用 Volume 或 Secret 將該檔案掛載到容器中。

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

Prometheus 範例專案

如果您沒有設定 Prometheus 伺服器，可以使用 Docker Compose 執行範例專案。該範例包含一個 Prometheus 伺服器，可為已註冊 Docker Scout 的 Docker 組織抓取指標，並附帶 Grafana 及預先設定好的儀表板，以視覺化弱點和政策指標。

複製啟動模板，以引導用於抓取和視覺化 Docker Scout 指標端點的一組 Compose 服務：

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

建立 Docker 存取權杖，並將其儲存在模板目錄下 /prometheus/prometheus/token 的純文字檔案中。
token
$ echo $DOCKER_PAT > ./prometheus/token

在 /prometheus/prometheus/prometheus.yml 的 Prometheus 設定檔中，將第 6 行 metrics_path 屬性中的 ORG 取代為您 Docker 組織的命名空間。

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

啟動服務後，您可以造訪 https://:9090 來存取 Prometheus 表達式瀏覽器。Prometheus 伺服器在 Docker 容器中執行，並可在連接埠 9090 上存取。

幾秒鐘後，您應該會在 Prometheus UI 的 https://:9090/targets 中看到指標端點作為一個目標。

Docker Scout metrics exporter Prometheus target — Docker Scout 指標匯出工具 Prometheus 目標

在 Grafana 中檢視指標

若要檢視 Grafana 儀表板，請前往 https://: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 的設定：

指定目標為 dockerscoutpolicy Docker 組織的 OpenMetrics 端點
所有收集的指標都將具有 namespace 前綴
您希望代理程式抓取的 指標 (scout_*)
一個 auth_token 區段，供 Datadog 代理程式透過使用 Docker PAT 作為持有人權杖來驗證指標端點。

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 代理程式設定時，請務必透過將 dockerscoutpolicy 取代為您 Docker 組織的命名空間，來編輯 openmetrics_endpoint 屬性以指向您的組織。

Datadog 範例專案

如果您沒有設定 Datadog 伺服器，可以使用 Docker Compose 執行範例專案。該範例包含一個以容器方式執行的 Datadog 代理程式，可為已註冊 Docker Scout 的 Docker 組織抓取指標。此範例專案假設您擁有 Datadog 帳戶、API 金鑰和 Datadog 站點。

複製啟動模板，以引導用於抓取 Docker Scout 指標端點的 Datadog Compose 服務：

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

建立 Docker 存取權杖，並將其儲存在模板目錄下 /datadog/token 的純文字檔案中。
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 Socket 掛載到容器中。這是以容器方式執行時取得正確主機名稱的必要條件（更多詳情請見此處）。

它還會掛載代理程式的設定檔和 Docker 存取權杖。

編輯 /datadog/config.yaml 檔案，將 openmetrics_endpoint 屬性中的 <ORG> 佔位符取代為您想要收集指標的 Docker 組織命名空間。

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

啟動 Compose 服務：
docker compose up -d

如果設定正確，當您執行代理程式的狀態命令時，您應該會在「正在執行的檢查」(Running Checks) 下看到 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_metrics_exporter 命名空間下收集所有以 scout_ 開頭的公開指標。

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

圖表中線條看起來平坦的原因，在於弱點本身的性質（它們不會頻繁變更）以及日期選擇器中所選擇的短時間間隔。

抓取間隔 (Scrape interval)

預設情況下，Prometheus 和 Datadog 以 15 秒的間隔抓取指標。由於弱點資料本身的性質，透過此 API 公開的指標不太可能以高頻率變更。因此，指標端點預設有 60 分鐘的快取，這意味著建議採用 60 分鐘或更長的抓取間隔。如果您將抓取間隔設定為少於 60 分鐘，您將會在該時間範圍內的多個抓取中看到相同的指標資料。

若要變更抓取間隔：

Prometheus：在 Prometheus 設定檔的全域或任務級別中設定 scrape_interval 欄位。
Datadog：在 Datadog 代理程式設定檔中設定 min_collection_interval 屬性，請參閱 Datadog 文件。

撤銷存取權杖

如果您懷疑您的 PAT 已外洩或不再需要，您可以隨時撤銷它。若要撤銷 PAT，請按照建立與管理存取權杖中的步驟操作。

撤銷 PAT 會立即使該權杖失效，並阻止 Prometheus 使用該權杖抓取指標。您將需要建立一個新的 PAT，並更新 Prometheus 設定以使用新權杖。