Docker Scout 지표 내보내기

Docker Scout 지표 내보내기 (metrics exporter)

Docker Scout는 Prometheus나 Datadog를 사용해 Docker Scout에서 취약점·정책 데이터를 스크래핑할 수 있는 지표 HTTP 엔드포인트를 제공해요. 이를 통해 공급망 지표를 시각화하는 자체 호스팅 Docker Scout 대시보드를 만들 수 있어요.

지표 (Metrics)

지표 엔드포인트는 다음 지표를 노출해요.

지표 (Metric)	설명 (Description)	라벨 (Labels)	타입 (Type)
`scout_stream_vulnerabilities`	스트림의 취약점	`streamName`, `severity`	Gauge
`scout_policy_compliant_images`	스트림에서 정책에 부합하는 이미지	`id`, `displayName`, `streamName`	Gauge
`scout_policy_evaluated_images`	스트림에서 정책에 대해 평가된 총 이미지	`id`, `displayName`, `streamName`	Gauge

스트림 (Streams)

Docker Scout에서 스트림 개념은 환경(environments)의 상위 집합이에요. 스트림은 정의한 모든 런타임 환경과 특별한 latest-indexed 스트림을 포함해요. latest-indexed 스트림은 각 저장소에 대해 가장 최근에 push(그리고 분석)된 태그를 포함해요.

스트림은 이 지표 엔드포인트를 통해 노출된 데이터를 제외하면 대체로 Docker Scout 내부 개념이에요. { #stream }

액세스 토큰 만들기

조직에서 지표를 내보내려면 먼저 조직이 Docker Scout에 등록되어 있는지 확인하세요. 그 다음 Personal Access Token(PAT)을 만드세요. PAT는 exporter가 Docker Scout API로 인증할 수 있게 하는 시크릿 토큰이에요.

PAT는 특정 권한이 필요하지 않지만, Docker 조직의 소유자(owner)인 사용자가 만들어야 해요. PAT를 만들려면 액세스 토큰 만들기의 단계를 따르세요.

PAT를 만들면 안전한 위치에 저장하세요. 지표를 스크래핑할 때 exporter에 이 토큰을 제공해야 해요.

Prometheus

이 섹션은 Prometheus로 지표 엔드포인트를 스크래핑하는 방법을 설명해요.

조직용 작업(job) 추가

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 토큰으로 사용하도록 구성해야 해요. exporter는 요청의 Authorization 헤더에 PAT가 전달되도록 요구해요.

authorization 구성 블록을 포함하도록 Prometheus 구성 파일을 갱신하세요. 이 블록은 파일에 저장된 bearer 토큰으로 PAT를 정의해요.

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

파일 내용은 PAT를 평문으로 담고 있어야 해요.

dckr_pat_...

Prometheus를 Docker 컨테이너나 Kubernetes pod에서 실행한다면 볼륨이나 시크릿으로 파일을 컨테이너에 마운트하세요.

마지막으로 변경 사항을 적용하려면 Prometheus를 재시작하세요.

Prometheus 샘플 프로젝트

Prometheus 서버가 설정돼 있지 않다면 Docker Compose로 샘플 프로젝트를 실행할 수 있어요. 샘플에는 Docker Scout에 등록된 Docker 조직의 지표를 스크래핑하는 Prometheus 서버와, 취약점·정책 지표를 시각화하도록 사전 구성된 대시보드를 갖춘 Grafana가 포함돼요.

Docker Scout 지표 엔드포인트를 스크래핑·시각화하는 Compose 서비스 집합을 부트스트랩하기 위한 스타터 템플릿을 클론하세요.
```
$ git clone [email protected]:dockersamples/scout-metrics-exporter.git
$ cd scout-metrics-exporter/prometheus
```
Docker 액세스 토큰을 만들고 템플릿 디렉토리 아래 /prometheus/prometheus/token에 평문 파일로 저장하세요.
```
$ echo $DOCKER_PAT > ./prometheus/token
```

/prometheus/prometheus/prometheus.yml의 Prometheus 구성 파일에서 6행 metrics_path 속성의 ORG를 Docker 조직의 네임스페이스로 바꾸세요.

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:9090을 방문해 Prometheus 표현식 브라우저(expression browser)에 접근할 수 있어요. Prometheus 서버는 Docker 컨테이너에서 실행되며 포트 9090으로 접근 가능해요.

몇 초 후 http://localhost:9090/targets의 Prometheus UI에서 지표 엔드포인트를 대상(target)으로 볼 수 있어요.

Grafana에서 지표 보기

Grafana 대시보드를 보려면 http://localhost:3000/dashboards로 이동해 Docker Compose 파일에 정의된 자격 증명(사용자 이름: admin, 비밀번호: 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
에이전트가 스크래핑하려는 metrics(scout_*)
Datadog 에이전트가 Docker PAT를 Bearer 토큰으로 사용해 Metrics 엔드포인트에 인증하는 auth_token 섹션

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>

[!IMPORTANT]

이전 구성 예시의 <TOKEN> 자리 표시자를 바꾸지 마세요. 그대로 두어야 해요. Docker PAT가 지정된 파일시스템 경로에 Datadog 에이전트로 올바르게 마운트되었는지만 확인하세요. 파일을 conf.yaml로 저장하고 에이전트를 재시작하세요.

자체 Datadog 에이전트 구성을 만들 때 openmetrics_endpoint 속성을 편집해 dockerscoutpolicy를 Docker 조직의 네임스페이스로 바꿔 조직을 대상으로 하게 하세요.

Datadog 샘플 프로젝트

Datadog 서버가 설정돼 있지 않다면 Docker Compose로 샘플 프로젝트를 실행할 수 있어요. 샘플은 컨테이너로 실행되는 Datadog 에이전트를 포함하며, Docker Scout에 등록된 Docker 조직의 지표를 스크래핑해요. 이 샘플 프로젝트는 Datadog 계정, API 키, Datadog 사이트가 있다고 가정해요.

Docker Scout 지표 엔드포인트를 스크래핑하는 Datadog Compose 서비스를 부트스트랩하기 위한 스타터 템플릿을 클론하세요.
```
$ git clone [email protected]:dockersamples/scout-metrics-exporter.git
$ cd scout-metrics-exporter/datadog
```
Docker 액세스 토큰을 만들고 템플릿 디렉토리 아래 /datadog/token에 평문 파일로 저장하세요.
```
$ echo $DOCKER_PAT > ./token
```

/datadog/compose.yaml 파일에서 DD_API_KEY와 DD_SITE 환경 변수를 Datadog 배포 값으로 갱신하세요.

  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 소켓을 컨테이너로 마운트해요. 컨테이너로 실행할 때 정확한 호스트 이름을 얻는 데 필요해요 (자세한 내용). 에이전트 구성 파일과 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 그래프, 대시보드, 알림을 만들 수 있어요.

Metric summary 페이지로 가서 이 예시에서 수집된 지표를 확인하세요. 이 구성은 scout_로 시작하는 모든 노출 지표를 scout_metrics_exporter 네임스페이스 아래에서 수집해요.

datadog_metrics_summary

다음 스크린샷은 특정 스트림에 대한 취약점·정책 준수 그래프를 포함한 Datadog 대시보드 예시를 보여 줘요.

datadog_dashboard_1 datadog_dashboard_2

그래프의 선이 평평해 보이는 이유는 취약점의 특성상(자주 바뀌지 않음)과 날짜 선택기에서 선택한 짧은 시간 간격 때문이에요.

스크래핑 간격 (Scrape interval)

기본적으로 Prometheus와 Datadog는 15초 간격으로 지표를 스크래핑해요. 취약점 데이터의 특성 때문에 이 API를 통해 노출되는 지표는 높은 빈도로 바뀔 가능성이 낮아요. 그렇기 때문에 지표 엔드포인트는 기본적으로 60분 캐시가 있어서 60분 이상의 스크래핑 간격을 권장해요. 스크래핑 간격을 60분 미만으로 설정하면 그 시간 창 동안 여러 스크래핑에서 지표에 같은 데이터가 보일 거예요.

스크래핑 간격을 바꾸려면:

Prometheus: Prometheus 구성 파일의 전역 또는 작업 수준에서 scrape_interval 필드를 설정하세요.
Datadog: Datadog 에이전트 구성 파일에서 min_collection_interval 속성을 설정하세요. Datadog 문서 참고.

액세스 토큰 폐기 (Revoke an access token)

PAT가 손상됐다고 의심되거나 더 이상 필요 없으면 언제든지 폐기할 수 있어요. PAT를 폐기하려면 액세스 토큰 생성·관리의 단계를 따르세요.

PAT를 폐기하면 토큰이 즉시 무효화되고 Prometheus가 그 토큰으로 지표를 스크래핑하지 못하게 돼요. 새 PAT를 만들고 새 토큰을 사용하도록 Prometheus 구성을 갱신해야 해요.