Premiers pas avec la collecte gérée

Ce document explique comment configurer Google Cloud Managed Service pour Prometheus avec la collecte gérée. La configuration est un exemple minimal d'ingestion fonctionnelle utilisant un déploiement Prometheus qui surveille un exemple d'application et stocke les métriques collectées dans Monarch.

Sur cette page, vous allez :

  • Configurer votre environnement et vos outils de ligne de commande
  • Configurer la collecte gérée pour votre cluster.
  • Configurer une ressource pour le scraping et l'ingestion de métriques cibles.
  • Migrer les ressources personnalisées prometheus-operator existantes.

Nous vous recommandons d'utiliser la collecte gérée qui réduit la complexité du déploiement, du scaling, de la segmentation, de la configuration et de la maintenance des collecteurs. La collecte gérée est compatible avec GKE et tous les autres environnements Kubernetes. Pour en savoir plus sur la collecte des données gérée et auto-déployée, consultez la page Collecte des données avec Managed Service pour Prometheus.

Avant de commencer

Cette section décrit la configuration nécessaire pour les tâches décrites dans ce document.

Configurer des projets et des outils

Pour utiliser Google Cloud Managed Service pour Prometheus, vous avez besoin des ressources suivantes :

  • Un projet Google Cloud avec l'API Cloud Monitoring activée.

    • Si vous n'avez pas de projet Cloud, procédez comme suit :

      1. Dans la console Google Cloud, accédez à Nouveau projet :

        Créer un projet

      2. Dans le champ Nom du projet, saisissez un nom pour votre projet, puis cliquez sur Créer.

      3. Accéder à la page Facturation :

        Accéder à Facturation

      4. Sélectionnez le projet que vous venez de créer s'il n'est pas déjà sélectionné en haut de la page.

      5. Vous êtes invité à choisir un profil de paiement existant ou à en créer un.

      L'API Monitoring est activée par défaut pour les nouveaux projets.

    • Si vous disposez déjà d'un projet Cloud, assurez-vous que l'API Monitoring est activée :

      1. Accédez à la page API et services :

        Accéder à API et services

      2. Sélectionnez votre projet.

      3. Cliquez sur Enable APIs and Services (Activer les API et les services).

      4. Recherchez "Monitoring".

      5. Dans les résultats de recherche, cliquez sur "API Cloud Monitoring".

      6. Si l'option "API activée" ne s'affiche pas, cliquez sur le bouton Activer.

  • Un cluster Kubernetes. Si vous ne disposez pas de cluster Kubernetes, suivez les instructions du guide de démarrage rapide pour GKE.

Vous avez également besoin des outils de ligne de commande suivants :

  • gcloud
  • kubectl

Les outils gcloud et kubectl font partie de Google Cloud CLI. Pour en savoir plus sur leur installation, consultez la page Gérer les composants de Google Cloud CLI. Pour afficher les composants de la CLI gcloud que vous avez installés, exécutez la commande suivante :

gcloud components list

Configurer votre environnement

Pour éviter de saisir à plusieurs reprises l'ID de votre projet ou le nom de votre cluster, effectuez la configuration suivante :

  • Configurez les outils de ligne de commande comme suit :

    • Configurez la CLI gcloud pour faire référence à l'ID de votre projet Cloud :

      gcloud config set project PROJECT_ID
      
    • Configurez la CLI kubectl pour utiliser votre cluster :

      kubectl config set-cluster CLUSTER_NAME
      

    Pour en savoir plus sur ces outils, consultez les articles suivants :

Configurer un espace de noms

Créez l'espace de noms Kubernetes gmp-test pour les ressources que vous créez dans le cadre de l'exemple d'application :

kubectl create ns gmp-test

Configurer la collecte gérée

Pour télécharger et déployer la collection gérée sur votre cluster, vous devez appliquer les fichiers manifestes setup et operator pour le service géré. Vous pouvez appliquer les fichiers manifestes à l'aide des éléments suivants :

  • Google Cloud Console pour Google Kubernetes Engine.
  • Google Cloud CLI. Pour utiliser la CLI gcloud, vous devez exécuter GKE version 1.21.4-gke.300 ou une version ultérieure, et vous devez installer le composant beta de la CLI gcloud.
  • Terraform pour Google Kubernetes Engine Pour utiliser Terraform afin d'activer le service géré pour Prometheus, vous devez exécuter GKE version 1.21.4-gke.300 ou ultérieure.
  • La CLI kubectl, pour les environnements Kubernetes non GKE.

console Google Cloud

Vous pouvez effectuer les opérations suivantes à l'aide de la console Google Cloud :

  • Appliquer les fichiers manifestes à un cluster GKE existant.
  • Créer un cluster GKE avec les fichiers manifestes appliqués.

Pour mettre à jour un cluster existant avec les fichiers manifestes, procédez comme suit :

  1. Dans la console Google Cloud, sélectionnez Kubernetes Engine ou utilisez le bouton suivant :

    Accéder à Kubernetes Engine

  2. Sélectionnez Clusters.

  3. Cliquez sur le nom du cluster.

  4. Dans la liste Fonctionnalités, recherchez l'option Service géré pour Prometheus. Si elle est désactivée, cliquez sur Modifier, puis sélectionnez Activer le service géré pour Prometheus.

  5. Cliquez sur Enregistrer les modifications.

Pour créer un cluster avec les fichiers manifestes appliqués, procédez comme suit :

  1. Dans la console Google Cloud, sélectionnez Kubernetes Engine ou utilisez le bouton suivant :

    Accéder à Kubernetes Engine

  2. Sélectionnez Clusters.

  3. Cliquez sur Create (Créer).

  4. Cliquez sur Configurer pour l'option GKE Standard et configurez le cluster en utilisant le volet Paramètres de base du cluster.

  5. Dans le panneau de navigation, cliquez sur Fonctionnalités.

  6. Dans la section Opérations, sélectionnez Activer le service géré pour Prometheus.

  7. Cliquez sur Enregistrer.

CLI gcloud

Vous pouvez effectuer les opérations suivantes en utilisant la CLI gcloud :

  • Appliquer les fichiers manifestes à un cluster GKE existant.
  • Créer un cluster GKE avec les fichiers manifestes appliqués.

L'exécution de ces commandes peut prendre jusqu'à cinq minutes.

Pour mettre à jour un cluster existant avec les fichiers manifestes, exécutez l'une des commandes update suivantes selon que votre cluster est zonal ou régional :

  • gcloud beta container clusters update CLUSTER_NAME --enable-managed-prometheus --zone ZONE
    
  • gcloud beta container clusters update CLUSTER_NAME --enable-managed-prometheus --region REGION
    

Pour créer un cluster avec les fichiers manifestes appliqués, exécutez la commande suivante :

gcloud beta container clusters create CLUSTER_NAME --zone ZONE --enable-managed-prometheus

Terraform

Pour obtenir des instructions sur la configuration de la collecte gérée à l'aide de Terraform, consultez le registre Terraform pour google_container_cluster (bêta).

Pour obtenir des informations générales sur l'utilisation de Google Cloud avec Terraform, consultez la page Terraform avec Google Cloud.

CLI kubectl

Pour appliquer les fichiers manifestes lorsque vous utilisez un cluster Kubernetes non GKE, exécutez les commandes suivantes :

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.1/manifests/setup.yaml

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.1/manifests/operator.yaml

Après avoir appliqué les fichiers manifestes, la collecte gérée s'exécute, mais aucune métrique n'est générée pour le moment. Vous devez déployer une ressource PodMonitoring qui extrait un point de terminaison de métriques valide pour afficher toutes les données dans l'interface utilisateur des requêtes.

Pour obtenir une documentation de référence sur l'opérateur du service géré pour Prometheus, consultez la page des fichiers manifestes.

Déployer l'exemple d'application

Le service géré fournit un fichier manifeste pour un exemple d'application qui émet des métriques Prometheus sur le port metrics. L'application utilise trois instances dupliquées.

Pour déployer l'exemple d'application, exécutez la commande suivante :

kubectl -n gmp-test apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.1/examples/example-app.yaml

Configurer une ressource PodMonitoring

Pour ingérer les données de métriques émises par l'exemple d'application, vous utilisez le scraping de données cibles. Le scraping et l'ingestion des métriques cibles sont configurées à l'aide des ressources personnalisées Kubernetes. Le service géré utilise des ressources personnalisées PodMonitoring.

Une RS PodMonitoring ne scrape les cibles que dans l'espace de noms dans lequel la RS est déployée. Pour scraper des cibles dans plusieurs espaces de noms, déployez la même RS PodMonitoring dans chaque espace de noms. Vous pouvez vérifier que la ressource PodMonitoring est installée dans l'espace de noms prévu en exécutant la commande kubectl get podmonitoring -A.

Pour obtenir une documentation de référence sur toutes les ressources personnalisées Managed Service pour Prometheus, consultez la documentation prometheus-engine/doc/api reference.

Le fichier manifeste suivant définit une ressource PodMonitoring, prom-example, dans l'espace de noms gmp-test. La ressource utilise un sélecteur de libellés Kubernetes pour rechercher tous les pods de l'espace de noms portant le libellé app avec la valeur prom-example. Les pods correspondants sont récupérés sur un port nommé metrics, toutes les 30 secondes, sur le chemin HTTP /metrics.

apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: prom-example
spec:
  selector:
    matchLabels:
      app: prom-example
  endpoints:
  - port: metrics
    interval: 30s

Pour appliquer cette ressource, exécutez la commande suivante :

kubectl -n gmp-test apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.1/examples/pod-monitoring.yaml

Votre collecteur géré scrape désormais les pods correspondants.

Pour configurer la collecte horizontale qui s'applique à une plage de pods sur tous les espaces de noms, utilisez la ressource ClusterPodMonitoring. La ressource ClusterPodMonitoring fournit la même interface que la ressource PodMonitoring, mais ne limite pas les pods détectés à un espace de noms donné.

Si vous utilisez GKE, vous pouvez procéder comme suit :

Si vous procédez à l'exécution en dehors de GKE, vous devez créer un compte de service et l'autoriser à écrire vos données de métrique, comme décrit dans la section suivante.

Fournir des identifiants de manière explicite

Lors de l'exécution sur GKE, le serveur Prometheus de collecte récupère automatiquement les identifiants de l'environnement en fonction du compte de service Compute Engine par défaut ou de la configuration de Workload Identity.

Dans les clusters Kubernetes non GKE, les identifiants doivent être explicitement fournis via la ressource OperatorConfig dans l'espace de noms gmp-public.

  1. Créez un compte de service :

    gcloud iam service-accounts create gmp-test-sa
    

  2. Accordez les autorisations requises au compte de service :

    gcloud projects add-iam-policy-binding PROJECT_ID\
      --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
      --role=roles/monitoring.metricWriter
    

  3. Créez et téléchargez une clé pour le compte de service :

    gcloud iam service-accounts keys create gmp-test-sa-key.json \
      --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
    
  4. Ajoutez le fichier de clé en tant que secret à votre cluster non-GKE :

    kubectl -n gmp-public create secret generic gmp-test-sa \
      --from-file=key.json=gmp-test-sa-key.json
    

  5. Ouvrez la ressource OperatorConfig pour la modifier :

    kubectl -n gmp-public edit operatorconfig config
    

  6. Ajoutez le texte affiché en gras à la ressource :

    apiVersion: monitoring.googleapis.com/v1
    kind: OperatorConfig
    metadata:
      namespace: gmp-public
      name: config
    collection:
      credentials:
        name: gmp-test-sa
        key: key.json
    
    Veillez également à ajouter ces identifiants à la section rules pour que l'évaluation des règles gérées fonctionne.

  7. Enregistrez le fichier et fermez l'éditeur. Une fois la modification appliquée, les pods sont recréés et commencent à s'authentifier auprès du backend de métrique avec le compte de service donné.

Autres sujets sur la collecte gérée

Cette page explique comment effectuer les opérations suivantes :

  • Configurer la récupération cible à l'aide de Terraform
  • Récupérer les métriques Kubelet et cAdvisor.
  • Filtrez les données que vous exportez vers le service géré.
  • Convertissez vos ressources prom-operator existantes pour les utiliser avec le service géré.

Configurer la récupération cible à l'aide de Terraform

Vous pouvez automatiser la création et la gestion de ressources PodMonitoring et ClusterPodMonitoring à l'aide du type de ressource Terraform kubernetes_manifest ou du type de ressource Terraform kubectl_manifest, qui vous permettent de spécifier des ressources personnalisées arbitraires.

Pour obtenir des informations générales sur l'utilisation de Google Cloud avec Terraform, consultez la page Terraform avec Google Cloud.

Récupérer les métriques Kubelet et cAdvisor

Le Kubelet expose des métriques sur lui-même ainsi que des métriques cAdvisor sur les conteneurs s'exécutant sur son nœud. Elles peuvent être ingérées en mettant à jour l'objet OperatorConfig.

  1. Ouvrez la ressource OperatorConfig pour la modifier :

    kubectl -n gmp-public edit operatorconfig config
    
  2. Ajoutez la section collection suivante, affichée en gras, à la ressource :

    apiVersion: monitoring.googleapis.com/v1
    kind: OperatorConfig
    metadata:
      namespace: gmp-public
      name: config
    collection:
      kubeletScraping:
        interval: 15s
    
  3. Enregistrez le fichier et fermez l'éditeur.

Après un court laps de temps, les points de terminaison des métriques Kubelet seront récupérés et les métriques seront disponibles pour interrogation dans le service géré pour Prometheus.

Filtrer les métriques exportées

Si vous collectez une grande quantité de données, vous pouvez empêcher l'envoi de certaines séries temporelles au service géré pour Prometheus afin de limiter les coûts.

Pour filtrer les métriques exportées, vous pouvez configurer un ensemble de sélecteurs de séries PromQL dans la ressource OperatorConfig. Une série temporelle est exportée vers le service géré pour Prometheus si elle répond à au moins l'un des sélecteurs. En d'autres termes, lors de la détermination de l'éligibilité, les conditions d'un même sélecteur sont combinées à l'opérateur AND, tandis que les conditions des sélecteurs distincts sont combinées à l'opérateur OR. Par défaut, aucun sélecteur n'est spécifié et toutes les séries temporelles sont exportées. L'exemple suivant utilise deux sélecteurs :

  1. Ouvrez la ressource OperatorConfig pour la modifier :

    kubectl -n gmp-public edit operatorconfig config
    
  2. Ajoutez un filtre collection à la ressource, comme indiqué en gras ci-dessous. La section de configuration filter.matchOneOf possède la même sémantique que les paramètres match[] pour la fédération Prometheus.

    Cet exemple de filtre entraîne uniquement l'exportation des métriques de la tâche "prometheus", ainsi que les métriques générées par les règles d'enregistrement agrégées au niveau de la tâche à exporter (en suivant les bonnes pratiques de dénomination). Les échantillons de toutes les autres séries temporelles sont filtrés :

    apiVersion: monitoring.googleapis.com/v1
    kind: OperatorConfig
    metadata:
      namespace: gmp-public
      name: config
    collection:
      filter:
        matchOneOf:
        - '{job="prometheus"}'
        - '{__name__=~"job:.+"}'
    
  3. Enregistrez le fichier et fermez l'éditeur.

Convertir les ressources prometheus-operator existantes

Vous pouvez généralement convertir vos ressources d'opérateur Prometheus en ressources PodMonitoring et ClusterPodMonitoring de la collection gérée des services gérés pour Prometheus.

Par exemple, la ressource ServiceMonitor définit la surveillance d'un ensemble de services. La ressource PodMonitoring diffuse un sous-ensemble des champs diffusés par la ressource ServiceMonitor. Vous pouvez convertir une ressource personnalisée ServiceMonitor en ressource personnalisée PodMonitoring en mappant les champs comme décrit dans le tableau suivant :

monitoring.coreos.com/v1
ServiceMonitor
Compatibilité
 
monitoring.googleapis.com/v1
PodMonitoring
.ServiceMonitorSpec.Selector Identiques .PodMonitoringSpec.Selector
.ServiceMonitorSpec.Endpoints[] .TargetPort correspond à .Port
.Path: compatible
.Interval: compatible
.Timeout: compatible
.PodMonitoringSpec.Endpoints[]
.ServiceMonitorSpec.TargetLabels PodMonitor doit spécifier :
.FromPod[].From libellé du pod
.FromPod[].To libellé cible
.PodMonitoringSpec.TargetLabels

Voici un exemple de ressource personnalisée ServiceMonitor ; le contenu en gras est remplacé dans la conversion, et le contenu en italique est mappé directement :

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: example-app
spec:
  selector:
    matchLabels:
      app: example-app
  endpoints:
  - targetPort: web
    path: /stats
    interval: 30s
  targetLabels:
  - foo

Voici la ressource personnalisée PodMonitoring analogue, en supposant que votre service et ses pods possèdent le libellé app=example-app. Si cette hypothèse ne s'applique pas, vous devez utiliser les sélecteurs de libellés de la ressource de service sous-jacente.

Le contenu en gras a été remplacé dans la conversion :

apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: example-app
spec:
  selector:
    matchLabels:
      app: example-app
  endpoints:
  - port: web
    path: /stats
    interval: 30s
  targetLabels:
    fromPod:
    - from: foo # pod label from example-app Service pods.
      to: foo

Vous pouvez toujours utiliser vos ressources d'opérateur et configurations de déploiement Prometheus existantes à l'aide de collecteurs auto-déployés plutôt que de collecteurs gérés. Vous pouvez interroger les métriques envoyées par les deux types de collecteurs. Il est donc préférable d'utiliser des collecteurs auto-déployés pour vos déploiements Prometheus existants tout en utilisant des collecteurs gérés pour les nouveaux déploiements Prometheus.

Suppression

Pour désactiver la collecte gérée déployée à l'aide de gcloud ou de l'interface utilisateur de GKE, exécutez la commande suivante :

gcloud beta container clusters update CLUSTER_NAME --disable-managed-prometheus

Pour désactiver la collecte gérée déployée à l'aide de kubectl, exécutez la commande suivante :

kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.1/manifests/operator.yaml

Exécuter une collecte gérée en dehors de GKE

Dans les environnements GKE, vous pouvez exécuter la collecte gérée sans configuration supplémentaire. Dans d'autres environnements Kubernetes, vous devez fournir explicitement les identifiants, une valeur project-id pour contenir vos métriques, une valeur location (région Google Cloud) où vos métriques seront stockées et une valeur cluster pour enregistrer le nom du cluster dans lequel le collecteur s'exécute.

Comme gcloud ne fonctionne pas en dehors des environnements Google Cloud, vous devez déployer à l'aide de kubectl. Contrairement à gcloud, le déploiement d'une collecte gérée à l'aide de kubectl ne met pas automatiquement à niveau votre cluster lorsqu'une nouvelle version est disponible. N'oubliez pas de consulter la page des versions pour connaître les nouvelles versions, et effectuez une mise à niveau manuelle en exécutant à nouveau les commandes kubectl avec la nouvelle version.

Vous pouvez fournir une clé de compte de service en modifiant la ressource OperatorConfig dans operator.yaml, comme décrit dans la section Fournir des identifiants explicitement. Vous pouvez fournir les valeurs project-id, location et cluster en les ajoutant en tant que args à la ressource Deployment dans operator.yaml.

Nous vous recommandons de choisir project-id en fonction de votre modèle de location planifié pour les lectures. Choisissez un projet dans lequel stocker les métriques en fonction de la manière dont vous envisagez d'organiser les lectures par la suite via des champs d'application de métriques. Si cela n'a aucune importance pour vous, vous pouvez tout regrouper dans un même projet.

Pour location, nous vous recommandons de choisir la région Google Cloud la plus proche de votre déploiement. Plus la région Google Cloud choisie est éloignée de votre déploiement, plus la latence d'écriture sera importante, et plus vous risquez d'être affecté par d'éventuels problèmes de réseau. Vous pouvez consulter cette liste des régions couvrant plusieurs clouds. Si cela n'a pas d'importance à vos yeux, vous pouvez tout déployer dans une seule région Google Cloud. Vous ne pouvez pas utiliser global comme emplacement.

Pour cluster, nous vous recommandons de choisir le nom du cluster dans lequel l'opérateur est déployé.

Lorsqu'elle est correctement configurée, votre ressource OperatorConfig doit ressembler à ceci :

    apiVersion: monitoring.googleapis.com/v1
    kind: OperatorConfig
    metadata:
      namespace: gmp-public
      name: config
    collection:
      credentials:
        name: gmp-test-sa
        key: key.json
    rules:
      credentials:
        name: gmp-test-sa
        key: key.json

Votre ressource Deployment doit ressembler à ceci :

apiVersion: apps/v1
kind: Deployment
...
spec:
  ...
  template:
    ...
    spec:
      ...
      containers:
      - name: operator
        ...
        args:
        - ...
        - "--project-id=PROJECT_ID"
        - "--cluster=CLUSTER_NAME"
        - "--location=ZONE"

Cet exemple suppose que vous avez défini la variable ZONE sur une valeur telle que us-central1-b.

L'exécution du service géré pour Prometheus en dehors de Google Cloud entraîne des frais d'entrée de données et peut entraîner des frais de sortie de données s'il est exécuté sur un autre cloud.

Documentation complémentaire sur les ressources personnalisées des collections gérées

Pour obtenir une documentation de référence sur toutes les ressources personnalisées Managed Service pour Prometheus, consultez la documentation prometheus-engine/doc/api reference.

Étape suivante