Développement d'un plugin pour Grafana : histoire des obstacles rencontrés

Bonjour à tous ! Il y a quelques mois, nous avons lancé en production notre nouveau projet open-source : un plugin Grafana pour surveiller Kubernetes, que nous avons nommé DevOpsProdigy KubeGraf. Le code source du plugin est disponible dans un dépôt public sur GitHub. Dans cet article, nous souhaitons partager avec vous l'histoire de la création du plugin, les outils que nous avons utilisés et les obstacles que nous avons rencontrés lors du développement. Allons-y !

Partie 0 - Introduction : comment en sommes-nous arrivés là ?

L'idée de créer notre propre plugin pour Grafana nous est venue complètement par hasard. Notre entreprise s'occupe de la surveillance de projets web de divers niveaux de complexité depuis plus de 10 ans. Au cours de cette période, nous avons accumulé une grande expertise, des cas intéressants et de l'expérience avec divers systèmes de surveillance. À un moment donné, nous nous sommes posé la question : « Existe-t-il un outil magique pour surveiller Kubernetes, que l'on puisse simplement installer et oublier ? »... Le standard de fait pour surveiller k8s est bien sûr la combinaison Prometheus + Grafana. Et pour cette pile, il existe un grand nombre d'outils variés : prometheus-operator, un ensemble de dashboards kubernetes-mixin, grafana-kubernetes-app.

L'option qui nous a semblé la plus intéressante était le plugin grafana-kubernetes-app, mais celui-ci n'est plus supporté depuis plus d'un an et, en outre, ne fonctionne pas avec les nouvelles versions de node-exporter et kube-state-metrics. À un moment donné, nous avons décidé : « Pourquoi ne ferions-nous pas notre propre solution ? »

Voici les idées que nous avons décidé de mettre en œuvre dans notre plugin :

• visualisation d'« une carte d'application » : une représentation pratique des applications dans le cluster, regroupées par namespaces, déploiements… ;
• visualisation des relations du type « déploiement — service (+ports) ».
• visualisation de la répartition des applications du cluster par nœuds du cluster.
• collecte de métriques et d'informations provenant de plusieurs sources : Prometheus et k8s api server.
• surveillance à la fois de la partie infrastructure (utilisation du temps processeur, mémoire, sous-système de stockage, réseau) et de la logique des applications — état de santé des pods, nombre de répliques disponibles, informations sur la réussite des tests de liveness/readyness.

Partie 1 : Qu'est-ce qu'un « plugin pour Grafana » ?

D'un point de vue technique, un plugin pour Grafana est un contrôleur Angular qui se trouve dans le répertoire de données de Grafana (/var/grafana/plugins/<your_plugin_name>/dist/module.js) et peut être chargé comme un module SystemJS. Un fichier plugin.json doit également se trouver dans ce répertoire, contenant toutes les métadonnées de votre plugin : nom, version, type de plugin, liens vers le dépôt/site/ licence, dépendances, etc.

module.ts

plugin.json

Comme indiqué sur la capture d'écran, nous avons spécifié plugin.type = app. En effet, les plugins pour Grafana peuvent être de trois types :

panel: le type de plugin le plus répandu — il représente un panneau pour visualiser certaines métriques, utilisé pour construire différents tableaux de bord.
datasource: un plugin-connecteur vers une source de données (par exemple, Prometheus-datasource, ClickHouse-datasource, ElasticSearch-datasource).
app: un plugin vous permettant de construire votre propre application frontale à l’intérieur de Grafana, de créer vos propres pages html et d'accéder manuellement à la source de données pour visualiser diverses données. Des plugins d'autres types (datasource, panel) et différents tableaux de bord peuvent également être utilisés comme dépendances.

Exemple de dépendances d’un plugin avec type = app.

Comme langage de programmation, vous pouvez utiliser à la fois JavaScript et TypeScript (nous avons choisi ce dernier). Vous pouvez trouver des templates pour des plugins hello-world de n'importe quel type à l'adresse suivante: ce dépôt présente un grand nombre de starter-pack (il y a même un exemple expérimental de plugin sur React) avec des build tools préinstallés et configurés.

Partie 2 : préparation de l'environnement local

Pour travailler sur le plugin, il nous faudra, bien sûr, un cluster Kubernetes avec tous les outils préinstallés : prometheus, node-exporter, kube-state-metrics, grafana. L'environnement doit se mettre en place rapidement, facilement et de manière fluide, et pour assurer le hot-reload, le répertoire de données de Grafana doit être monté directement depuis la machine du développeur.

À notre avis, le moyen le plus pratique de travailler localement avec Kubernetes est minikube. La prochaine étape consiste à installer Prometheus + Grafana avec l'aide de prometheus-operator. Dans cet article le processus d'installation de prometheus-operator sur minikube est décrit en détail. Pour activer la persistance, il est nécessaire de définir le paramètre persistence: true dans le fichier charts/grafana/values.yaml, d'ajouter votre propre PV et PVC et de les spécifier dans le paramètre persistence.existingClaim

Le script final pour le lancement de minikube ressemble à ceci :

minikube start --kubernetes-version=v1.13.4 --memory=4096 --bootstrapper=kubeadm --extra-config=scheduler.address=0.0.0.0 --extra-config=controller-manager.address=0.0.0.0
minikube mount 
/home/sergeisporyshev/Projects/Grafana:/var/grafana --gid=472 --uid=472 --9p-version=9p2000.L

Partie 3 : développement proprement dit

Modèle d'objet

En préparation pour la mise en œuvre du plugin, nous avons décidé de décrire toutes les entités de base de Kubernetes avec lesquelles nous allons travailler sous forme de classes TypeScript : pod, deployment, daemonset, statefulset, job, cronjob, service, node, namespace. Chacune de ces classes hérite de la classe de base BaseModel, qui décrit le constructeur, le destructeur, ainsi que des méthodes pour la mise à jour et le changement de visibilité. Dans chacune des classes, les relations imbriquées avec d'autres entités sont décrites, par exemple, la liste des pods pour une entité de type deployment.

import {Pod} from './pod';
import {Service} from './service';
import {BaseModel} from './traits/baseModel';

export class Deployment extends BaseModel{
   pods: Array;
   services: Array;

   constructor(data: any){
       super(data);
       this.pods = [];
       this.services = [];
   }
}

Avec les getters et setters, nous pouvons afficher ou définir les métriques nécessaires des entités de manière pratique et lisible. Par exemple, la sortie formatée de l'allocatable cpu d'un nœud :

get cpuAllocatableFormatted(){
   let cpu = this.data.status.allocatable.cpu;
   if(cpu.indexOf('m') > -1){
       cpu = parseInt(cpu)/1000;
   }
   return cpu;
}

Pages

La liste de toutes les pages de notre plugin est initialement décrite dans notre pluing.json dans la section des dépendances :

Dans le bloc pour chaque page, nous devons indiquer le NOM DE LA PAGE (qui sera ensuite converti en slug, par lequel cette page sera accessible) ; le nom du composant responsable du fonctionnement de cette page (la liste des composants est exportée dans module.ts) ; l'indication du rôle de l'utilisateur pour lequel l'accès à cette page et aux paramètres de navigation de la barre latérale est disponible.

Dans le composant responsable du fonctionnement de la page, nous devons définir templateUrl, en passant le chemin vers le fichier html contenant le balisage. À l'intérieur du contrôleur, par le biais de l'injection de dépendance, nous pouvons accéder à 2 services Angular importants :

• backendSrv — service permettant l'interaction avec l'API serveur de Grafana ;
• datasourceSrv — service permettant l'interaction locale avec toutes les sources de données installées dans votre Grafana (par exemple, la méthode .getAll() — renvoie la liste de toutes les sources de données installées ; .get() — retourne l'objet instance d'une source de données spécifique.

Partie 4 : datasource

D'un point de vue de Grafana, une source de données est un plugin comme tous les autres : elle a son propre point d'entrée module.js et un fichier de métadonnées plugin.json. Lors de la création d'un plugin avec type = app, nous pouvons interagir avec les sources de données existantes (par exemple, prometheus-datasource) ainsi qu'avec nos propres sources de données, que nous pouvons stocker directement dans le répertoire du plugin (dist/datasource/*) ou installer comme dépendance. Dans notre cas, la source de données est fournie avec le code du plugin. Il est également impératif d'avoir un modèle config.html et un contrôleur ConfigCtrl, qui seront utilisés pour la page de configuration de l'instance de la source de données et le contrôleur Datasource, dans lequel la logique de fonctionnement de votre source de données est réalisée.

Dans le plugin KubeGraf, d'un point de vue interface utilisateur, une source de données représente une instance d'un cluster kubernetes, qui dispose des capacités suivantes (le code source est disponible via le lien):

• récupération des données de l'api-server k8s (obtention de la liste des namespaces, des déploiements…)
• proxy des requêtes vers prometheus-datasource (qui est sélectionné dans les paramètres du plugin pour chaque cluster spécifique) et formatage des réponses pour utiliser les données à la fois dans les pages statiques et dans les tableaux de bord.
• actualisation des données sur les pages statiques du plugin (avec un temps de rafraîchissement défini).
• traitement des requêtes pour générer la liste des templates dans grafana-dashboards (méthode .metriFindQuery())

• test de connexion avec le cluster k8s cible.

testDatasource(){
   let url = '/api/v1/namespaces';
   let _url = this.url;
   if(this.accessViaToken)
       _url += '/__proxy';
   _url += url;
   return this.backendSrv.datasourceRequest({
       url: _url,
       method: "GET",
       headers: {"Content-Type": 'application/json'}
   })
       .then(response => {
           if (response.status === 200) {
               return {status: "success", message: "La source de données est OK", title: "Succès"};
           }else{
               return {status: "error", message: "La source de données n'est pas OK", title: "Erreur"};
           }
       }, error => {
           return {status: "error", message: "La source de données n'est pas OK", title: "Erreur"};
       })
}

Un point particulièrement intéressant, à notre avis, est la mise en œuvre du mécanisme d'authentification et d'autorisation pour le datasource. En général, pour configurer l'accès à la source de données finale, nous pouvons utiliser le composant intégré de Grafana — datasourceHttpSettings. Avec ce composant, nous pouvons configurer l'accès à la source de données http en spécifiant l'url et les paramètres d'authentification/autorisation de base : identifiant-mot de passe, ou client-cert/client-key. Pour permettre la configuration d'accès à l'aide d'un jeton bearer (un standard de fait pour k8s), il a fallu bricoler un peu.

Pour résoudre ce problème, nous pouvons utiliser le mécanisme intégré de Grafana «Plugin Routes» (voir plus sur la page officielle de documentation). Dans les paramètres de notre datasource, nous pouvons déclarer un ensemble de règles de routage qui seront traitées par le serveur proxy de Grafana. Par exemple, pour chaque endpoint, il est possible de spécifier des en-têtes ou des url avec des options de template, dont les données peuvent être extraites des champs jsonData et secureJsonData (pour stocker des mots de passe ou des jetons sous forme cryptée). Dans notre exemple, les requêtes du type /__proxy/api/v1/namespaces seront proxyées vers une url du type
/api/v1/namespaces avec l'en-tête Authorization: Bearer.

Naturellement, pour travailler avec l'api-server k8s, nous avons besoin d'un utilisateur avec des accès en lecture seule, et vous pouvez également trouver les manifestes pour sa création dans le code source du plugin.

Partie 5 : sortie

Après avoir écrit votre propre plugin pour Grafana, vous voudrez naturellement le rendre public. Dans Grafana, il existe une bibliothèque de plugins disponible à l'adresse grafana.com/grafana/plugins

Pour que votre plugin soit disponible dans la boutique officielle, vous devez faire une PR dans ce dépôt, en ajoutant dans le fichier repo.json un contenu du type :

où version — version de votre plugin, url — lien vers le dépôt, et commit — hash du commit par lequel une version spécifique du plugin sera disponible.

Et à la fin, vous verrez une belle image du type :

Les données pour cela seront automatiquement extraites de votre Readme.md, Changelog.md et du fichier plugin.json décrivant le plugin.

Partie 6 : en guise de conclusion

Nous n'avons pas arrêté le développement de notre plugin après sa sortie. Nous travaillons actuellement sur une surveillance précise de l'utilisation des ressources des nœuds du cluster, l'ajout de nouvelles fonctionnalités pour améliorer l'expérience utilisateur, et nous traitons un grand nombre de retours reçus après l'installation du plugin, tant de nos clients que des issues sur GitHub (si vous laissez votre issue ou pull request, je serai très heureux 🙂 ).

Nous espérons que cet article vous aidera à mieux comprendre cet outil merveilleux qu'est Grafana et, peut-être, à rédiger votre propre plugin.

Merci !)

Source : habr.com