Exportateur de métriques Docker Scout

Table des matières

Docker Scout expose un point de terminaison HTTP de métriques qui vous permet de récupérer des données de vulnérabilité et de politique depuis Docker Scout, en utilisant Prometheus ou Datadog. Avec cela, vous pouvez créer vos propres tableaux de bord Docker Scout auto-hébergés pour visualiser les métriques de chaîne d'approvisionnement.

Métriques

Le point de terminaison de métriques expose les métriques suivantes :

Métrique	Description	Labels	Type
`scout_stream_vulnerabilities`	Vulnérabilités dans un flux	`streamName`, `severity`	Gauge
`scout_policy_compliant_images`	Images conformes pour une politique dans un flux	`id`, `displayName`, `streamName`	Gauge
`scout_policy_evaluated_images`	Total d'images évaluées contre une politique dans un flux	`id`, `displayName`, `streamName`	Gauge

Flux

Dans Docker Scout, le concept de flux est un sur-ensemble des environnements. Les flux incluent tous les environnements d'exécution que vous avez définis, ainsi que le flux spécial latest-indexed. Le flux latest-indexed contient le tag le plus récemment poussé (et analysé) pour chaque dépôt.

Les flux sont principalement un concept interne dans Docker Scout, à l'exception des données exposées par ce point de terminaison de métriques.

Créer un jeton d'accès

Pour exporter les métriques de votre organisation, assurez-vous d'abord que votre organisation est inscrite dans Docker Scout. Ensuite, créez un jeton d'accès personnel (PAT) - un jeton secret qui permet à l'exportateur de s'authentifier avec l'API Docker Scout.

Le PAT ne nécessite aucune permission spécifique, mais il doit être créé par un utilisateur qui est propriétaire de l'organisation Docker. Pour créer un PAT, suivez les étapes dans Créer un jeton d'accès.

Une fois que vous avez créé le PAT, stockez-le dans un emplacement sécurisé. Vous devrez fournir ce jeton à l'exportateur lors de la récupération des métriques.

Prometheus

Cette section décrit comment récupérer le point de terminaison de métriques en utilisant Prometheus.

Ajouter un travail pour votre organisation

Dans le fichier de configuration Prometheus, ajoutez un nouveau travail pour votre organisation. Le travail doit inclure la configuration suivante ; remplacez ORG par le nom de votre organisation :

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

L'adresse dans le champ targets est définie au nom de domaine de l'API Docker Scout, api.scout.docker.com. Assurez-vous qu'il n'y a pas de règle de pare-feu en place empêchant le serveur de communiquer avec ce point de terminaison.

Ajouter l'authentification par jeton bearer

Pour récupérer les métriques du point de terminaison Exportateur Docker Scout en utilisant Prometheus, vous devez configurer Prometheus pour utiliser le PAT comme jeton bearer. L'exportateur nécessite que le PAT soit passé dans l'en-tête Authorization de la requête.

Mettez à jour le fichier de configuration Prometheus pour inclure le bloc de configuration authorization. Ce bloc définit le PAT comme jeton bearer stocké dans un fichier :

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

Le contenu du fichier doit être le PAT en texte brut :

dckr_pat_...

Si vous exécutez Prometheus dans un conteneur Docker ou un pod Kubernetes, montez le fichier dans le conteneur en utilisant un volume ou secret.

Enfin, redémarrez Prometheus pour appliquer les changements.

Projet d'exemple Prometheus

Si vous n'avez pas de serveur Prometheus configuré, vous pouvez exécuter un projet d'exemple en utilisant Docker Compose. L'exemple inclut un serveur Prometheus qui récupère les métriques pour une organisation Docker inscrite dans Docker Scout, avec Grafana avec un tableau de bord pré-configuré pour visualiser les métriques de vulnérabilité et de politique.

Clonez le modèle de démarrage pour amorcer un ensemble de services Compose pour récupérer et visualiser le point de terminaison de métriques Docker Scout :
$ git clone [email protected]:dockersamples/scout-metrics-exporter.git $ cd scout-metrics-exporter/prometheus
Créez un jeton d'accès Docker et stockez-le dans un fichier texte brut à /prometheus/prometheus/token sous le répertoire du modèle.
token
$ echo $DOCKER_PAT > ./prometheus/token

Dans le fichier de configuration Prometheus à /prometheus/prometheus/prometheus.yml, remplacez ORG dans la propriété metrics_path à la ligne 6 par l'espace de noms de votre organisation 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

Démarrez les services compose.
docker compose up -d
Cette commande démarre deux services : le serveur Prometheus et Grafana. Prometheus récupère les métriques du point de terminaison Docker Scout, et Grafana visualise les métriques en utilisant un tableau de bord pré-configuré.

Pour arrêter la démo et nettoyer toutes les ressources créées, exécutez :

docker compose down -v

Accès à Prometheus

Après avoir démarré les services, vous pouvez accéder au navigateur d'expressions Prometheus en visitant http://localhost:9090. Le serveur Prometheus s'exécute dans un conteneur Docker et est accessible sur le port 9090.

Après quelques secondes, vous devriez voir le point de terminaison de métriques comme cible dans l' interface utilisateur Prometheus à http://localhost:9090/targets.

Cible de l'exportateur de métriques Docker Scout Prometheus

Visualiser les métriques dans Grafana

Pour voir les tableaux de bord Grafana, allez à http://localhost:3000/dashboards, et connectez-vous en utilisant les identifiants définis dans le fichier Docker Compose (nom d'utilisateur : admin, mot de passe : grafana).

Tableau de bord de vulnérabilité dans Grafana

Tableau de bord de politique dans Grafana

Les tableaux de bord sont pré-configurés pour visualiser les métriques de vulnérabilité et de politique récupérées par Prometheus.

Datadog

Cette section décrit comment récupérer le point de terminaison de métriques en utilisant Datadog. Datadog tire des données pour la surveillance en exécutant un agent personnalisable qui récupère les points de terminaison disponibles pour toutes les métriques exposées. Les vérifications OpenMetrics et Prometheus sont incluses dans l'agent, donc vous n'avez pas besoin d'installer autre chose sur vos conteneurs ou hôtes.

Ce guide suppose que vous avez un compte Datadog et une clé API Datadog. Consultez la documentation Datadog pour commencer.

Configurer l'agent Datadog

Pour commencer à collecter les métriques, vous devrez éditer le fichier de configuration de l'agent pour la vérification OpenMetrics. Si vous exécutez l'agent comme un conteneur, ce fichier doit être monté à /etc/datadog-agent/conf.d/openmetrics.d/conf.yaml.

L'exemple suivant montre une configuration Datadog qui :

Spécifie le point de terminaison OpenMetrics ciblant l'organisation Docker dockerscoutpolicy
Un namespace avec lequel toutes les métriques collectées seront préfixées
Les métriques que vous voulez que l'agent récupère (scout_*)
Une section auth_token pour l'agent Datadog pour s'authentifier au point de terminaison des métriques, en utilisant un PAT Docker comme jeton Bearer.

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

Ne remplacez pas le <TOKEN> placeholder dans l'exemple de configuration précédent. Il doit rester tel quel. Assurez-vous simplement que le PAT Docker est correctement monté dans l'agent Datadog dans le chemin de fichier spécifié. Enregistrez le fichier sous le nom conf.yaml et redémarrez l'agent.

Lors de la création d'une configuration d'agent Datadog personnalisée, assurez-vous de mettre à jour le openmetrics_endpoint property pour cibler votre organisation, en remplaçant dockerscoutpolicy par l'espace de noms de votre organisation Docker.

Projet d'exemple Datadog

Si vous n'avez pas de serveur Datadog configuré, vous pouvez exécuter un projet d'exemple en utilisant Docker Compose. L'exemple inclut un agent Datadog, en cours d'exécution comme conteneur, qui récupère les métriques pour une organisation Docker inscrite dans Docker Scout. Ce projet d'exemple suppose que vous avez un compte Datadog, une clé API, et un site Datadog.

Clonez le modèle de démarrage pour amorcer un service Compose Datadog pour récupérer le point de terminaison de métriques Docker Scout :
$ git clone [email protected]:dockersamples/scout-metrics-exporter.git $ cd scout-metrics-exporter/datadog
Créez un jeton d'accès Docker et stockez-le dans un fichier texte brut à /datadog/token sous le répertoire du modèle.
token
$ echo $DOCKER_PAT > ./token

Dans le fichier /datadog/compose.yaml, mettez à jour les variables d'environnement DD_API_KEY et DD_SITE avec les valeurs pour votre déploiement 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

La section volumes monte le socket Docker du host vers le conteneur. Cela est nécessaire pour obtenir un nom d'hôte précis lors de l'exécution en tant que conteneur (plus de détails ici).

Il monte également le fichier de configuration de l'agent et le jeton d'accès Docker.

Modifiez le fichier /datadog/config.yaml en remplaçant le placeholder <ORG> dans la propriété openmetrics_endpoint par l'espace de noms de la Docker organisation que vous souhaitez collecter des métriques pour.
instances: - openmetrics_endpoint: "https://api.scout.docker.com/v1/exporter/org/<<ORG>>/metrics" namespace: "scout-metrics-exporter" # ...
Démarrez les services Compose.
docker compose up -d

Si configuré correctement, vous devriez voir la vérification OpenMetrics sous Running Checks lorsque vous exécutez la commande d'état de l'agent dont la sortie devrait ressembler à :

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)

Pour une liste complète des options, consultez ce fichier de configuration d'exemple pour la vérification OpenMetrics générique.

Visualiser vos données

Une fois que l'agent est configuré pour récupérer les métriques Prometheus, vous pouvez les utiliser pour construire des graphiques, tableaux de bord et alertes Datadog complets.

Allez dans votre page de résumé des métriques pour voir les métriques collectées de cet exemple. Cette configuration collectera toutes les métriques exposées commençant par scout_ sous l'espace de noms scout_metrics_exporter.

Les captures d'écran suivantes montrent des exemples de tableau de bord Datadog contenant graphiques sur la vulnérabilité et la conformité de la politique pour un flux spécifique.

La raison pour laquelle les lignes dans les graphiques apparaissent plates est due à la propre nature des vulnérabilités (elles ne changent pas trop souvent) et à l'intervalle de temps court sélectionné dans le sélecteur de date.

Intervalle de récupération

Par défaut, Prometheus et Datadog récupèrent les métriques à un intervalle de 15 secondes. Étant donné la propre nature des données de vulnérabilité, les métriques exposées via cette API sont peu susceptibles de changer à une fréquence élevée. Pour cette raison, le point de terminaison de métriques a une mise en cache de 60 minutes par défaut, ce qui signifie qu'un intervalle de récupération de 60 minutes ou plus est recommandé. Si vous définissez l'intervalle de récupération sur moins de 60 minutes, vous verrez les mêmes données dans les métriques pour plusieurs récupérations pendant cette fenêtre de temps.

Pour changer l'intervalle de récupération :

Prometheus : définissez le champ scrape_interval dans le fichier de configuration Prometheus au niveau global ou de travail.
Datadog : définissez la propriété min_collection_interval dans le fichier de configuration de l'agent, voir documentation Datadog.

Révoquer un jeton d'accès

Si vous soupçonnez que votre PAT a été compromis ou n'est plus nécessaire, vous pouvez le révoquer à tout moment. Pour révoquer un PAT, suivez les étapes dans Créer et gérer des jetons d'accès.

Révoquer un PAT invalide instantanément le jeton et empêche Prometheus de récupérer des métriques en utilisant ce jeton. Vous devrez créer un nouveau PAT et mettre à jour la configuration Prometheus pour utiliser le nouveau jeton.