Разработка на плъгин за Grafana: история на натрупаните опити

Здравейте на всички! Преди няколко месеца пуснахме в продукция новия си open-source проект — Grafana плъгин за мониторинг на Kubernetes, който нарекохме DevOpsProdigy KubeGraf. Изходният код на плъгина е достъпен в публичен репозитори на GitHub. В тази статия искаме да споделим с вас историята за това как създавахме плъгина, какви инструменти използвахме и с какви трудности се сблъскахме по време на разработката. Нека да започнем!

Част 0 — Въведение: как стигнахме дотук?

Идеята да напишем собствен плъгин за Grafana се появи случайно. Нашата компания се занимава с мониторинг на уеб проекти с различна сложност вече повече от 10 години. През това време натрупахме значителен опит, интересни казуси и опити с различни мониторингови системи. И в един момент си зададохме въпроса: 'Съществува ли магически инструмент за мониторинг на Kubernetes, който, както казват, 'да го поставиш и да забравиш'?... Стандартът за мониторинг на k8s, естествено, отдавна е комбинацията Prometheus + Grafana. И за този стек съществува голям набор от различни инструменти: prometheus-operator, набор от оперативни дашбордове kubernetes-mixin, grafana-kubernetes-app.

Най-интригуващият вариант за нас се оказа плъгинът grafana-kubernetes-app, но той не е поддържан вече повече от година и освен това не работи с новите версии на node-exporter и kube-state-metrics. В определен момент решихме: 'А не да направим ли наше собствено решение?'

Какви идеи решихме да реализираме в нашия плъгин:

• визуализация на 'карта на приложението': удобно представяне на приложенията в клъстера, групирани по namespace, deployments…;
• визуализация на отношения от типа 'deployment — service (+ports)'.
• визуализация на разпределението на приложенията в клъстера по nod'ове на клъстера.
• събиране на метрики и информация от няколко източника: Prometheus и k8s API сървър.
• мониторинг както на инфраструктурната част (употреба на процесорно време, памет, дискова подсистема, мрежа), така и на логиката на приложенията — health-status на pod'овете, брой налични реплики, информация за преминаването на liveness/readiness проверки.

Част 1: Какво е 'плъгин за Grafana'?

От техническа гледна точка, плъгин за Grafana е Angular контролер, който се съхранява в data директорията на Grafana (/var/grafana/plugins/<your_plugin_name>/dist/module.js) и може да бъде зареден като SystemJS-модул. Също така, в тази директория трябва да се намира файлът plugin.json, съдържащ цялата метаинформация за вашия плъгин: име, версия, тип плъгин, връзки към хранилище/сайт/лиценз, зависимости и така нататък.

module.ts

plugin.json

Както се вижда от екранната снимка, указахме plugin.type = app. Защото плъгините за Grafana могат да бъдат от три вида:

panel: най-разпространеният тип плъгини - представлява панел за визуализация на определени метрики, използва се за изграждане на различни дашбордове.
datasource: плъгин-конектор към определен източник на данни (например, Prometheus-datasource, ClickHouse-datasource, ElasticSearch-datasource).
app: плъгин, който ви позволява да изградите собственото си фронтенд приложение в Grafana, да създавате свои собствени html-страници и ръчно да се свързвате с datasource за визуализация на различни данни. Също така, като зависимости могат да се използват плъгини от друг тип (datasource, panel) и различни дашбордове.

Пример за зависимости на плъгин с type = app.

Като език за програмиране можете да използвате както JavaScript, така и TypeScript (ние избрахме него). Шаблоните за hello-world плъгини от всякакъв тип можете да намерите на връзката: в този репозиторий е представен голям брой starter-pack’ове (има дори експериментален пример на плъгин на React) с предварително инсталирани и настроени сборки.

Част 2: подготовка на локална среда

За работа по плъгина, разбира се, ще ни е необходим kubernetes-клъстер с всички предварително инсталирани инструменти: prometheus, node-exporter, kube-state-metrics, grafana. Околната среда трябва да бъде настроена бързо, лесно и безпроблемно, а за осигуряване на hot-reload директорията на данни на Grafana трябва да се монтира директно от машината на разработчика.

Най-удобният, на нашия поглед, начин за работа локално с kubernetes е minikube. Следващата стъпка е да инсталираме връзката Prometheus + Grafana с помощта на prometheus-operator. В тази статия подробно е описан процесът на инсталиране на prometheus-operator на minikube. За да включим персистентността, е необходимо да зададете параметъра persistence: true в файла charts/grafana/values.yaml, да добавите собствен PV и PVC и да ги укажете в параметъра persistence.existingClaim

Крайният скрипт за стартиране на minikube изглежда по следния начин:

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

Част 3: непосредствена разработка

Обектна модел

В подготовка за реализация на приставката решихме да опишем всички основни същности на Kubernetes, с които ще работим, във вид на TypeScript класове: pod, deployment, daemonset, statefulset, job, cronjob, service, node, namespace. Всеки от тези класове наследява общия клас BaseModel, в който са описани конструктор, деструктор, методи за обновление и промяна на видимостта. В всеки от класовете са описани вложени отношения с други същности, например списък на pod'овете за същността от тип 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 = [];
   }
}

С помощта на getter'и и setter'и можем да извеждаме или задаваме нужните ни метрики на съществата в удобен и четим вид. Например форматирано извеждане на allocatable cpu на нода:

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

Страници

Списъкът на всички страници на нашата приставка първоначално се описва в нашия pluing.json в секцията за зависимости:

В блока за всяка страница трябва да посочим НАЗВАНИЕТО НА СТРАНИЦАТА (то след това ще бъде конвертирано в slug, по който тази страница ще бъде достъпна); името на компонента, отговарящ за работата на тази страница (списъкът на компонентите се експортира в module.ts); указание за роля на потребителя, за който е налична работата с тази страница и настройки на навигацията за страничната лента.

В компонента, отговарящ за работата на страницата, трябва да зададем templateUrl, предавайки там пътя до html файла с разметката. Вътре в контролера, чрез dependency injection, можем да получим достъп до 2 важни angular услуги:

• backendSrv — услуга, осигуряваща взаимодействие с api-сервера на Grafana;
• datasourceSrv — услуга, осигуряваща локално взаимодействие с всички datasource, инсталирани във вашата Grafana (например метод .getAll() — връща списък на всички инсталирани datasource; .get() — връща обект-инстанс на конкретния datasource.

Част 4: datasource

От гледна точка на Grafana, datasource представлява точно такъв плъгин, какъвто са и всички останали: той има своя точка на вход module.js, има файл с метаинформация plugin.json. При разработката на плъгин с тип = app можем да взаимодействаме както с вече съществуващи datasource-и (например, prometheus-datasource), така и със своите собствени, които можем да съхраняваме директно в директорията на плъгина (dist/datasource/*) или да инсталираме като зависимост. В нашия случай datasource се предлага заедно с кода на плъгина. Също така е задължително наличието на шаблон config.html и контролер ConfigCtrl, които ще се използват за страницата за конфигуриране на екземпляра на datasource и контролер Datasource, в който се реализира логиката на работа на вашия datasource.

В плъгина KubeGraf, от гледна точка на потребителския интерфейс, datasource представлява екземпляр на kubernetes-кластера, в който са реализирани следните възможности (изходният код е наличен на линка):

• вземане на данни от api-server-a на k8s (получаване на списък с namespace-ове, deployment-и…)
• проксиране на заявки към prometheus-datasource (който се избира в настройките на плъгина за всеки конкретен кластер) и форматиране на отговорите за използване на данни както в статични страници, така и в табла за управление.
• обновяване на данните на статичните страници на плъгина (с установено време за опресняване).
• обработка на заявки за създаване на template-списък в grafana-dashboards (метод .metriFindQuery())

• тест на връзката с крайния k8s-кластер.

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: "Data source is OK", title: "Success"};
           }else{
               return {status: "error", message: "Data source is not OK", title: "Error"};
           }
       }, error => {
           return {status: "error", message: "Data source is not OK", title: "Error"};
       })
}

Отделният интересен момент, от наша гледна точка, е реализирането на механизма за автентикация и авторизация за datasource. Обикновено, от кутията, за конфигуриране на достъпа до крайния източник на данни можем да използваме вградения компонент на Grafana — datasourceHttpSettings. Чрез този компонент можем да настроим достъпа до http-източника на данни, като посочим url и основните настройки за автентикация/авторизация: потребителско име-парола, или client-cert/client-key. За да реализираме възможността за конфигуриране на достъпа с помощта на bearer-токен (де факто стандарт за k8s), се наложи да направим малко „пипане“.

За решаването на този проблем може да се използва вграденото механизъм на Grafana „Plugin Routes“ (повече на официалната страница на документацията). В настройките на нашия datasource можем да обявим набор от правила за маршрутиране, които ще бъдат обработвани от прокси-сервера на Grafana. Например, за всеки отделен endpoint има възможност за задаване на заглавия или url с възможност за шаблонизиране, данните за които могат да бъдат извлечени от полетата jsonData и secureJsonData (за съхранение на пароли или токени в криптиран вид). В нашия пример заявките от вида /__proxy/api/v1/namespaces ще бъдат проксирани на url от вида
/api/v1/namespaces с добавяне на заглавие Authorization: Bearer.

Естествено, за работа с api-сервера на k8s ни е необходим потребител с readonly достъпи, манифестите за създаването на който можете също да намерите в изходния код на плъгина.

Част 5: издание

След като напишете свой собствен плъгин за Grafana, естествено ще искате да го публикувате публично. В Grafana това е библиотека от плъгини, достъпна на адрес grafana.com/grafana/plugins

За да направите вашия плъгин достъпен в официалния магазин, трябва да направите PR в този репозиторий, добавяйки в файла repo.json съдържание от вида:

където version — версия на вашия плъгин, url — връзка към репозитория, а commit — hash на комита, по който ще бъде достъпна конкретната версия на плъгина.

И накрая ще видите страхотна картина от вида:

Данните за нея ще бъдат автоматично извлечени от вашия Readme.md, Changelog.md и файла plugin.json с описание на плъгина.

Част 6: вместо изводи

Не сме спирали разработката на нашия плъгин след пускането му. В момента работим върху правилния мониторинг на използването на ресурсите на клъстера, внедряването на нови функции за подобряване на UX и обработваме голямо количество обратна връзка, получена след инсталацията на плъгина както от нашите клиенти, така и от issues в GitHub (ако оставите свое issue или pull request, ще бъда много щастлив 🙂 ).

Надяваме се, че тази статия ще ви помогне да разберете този чудесен инструмент като Grafana и, възможно, да напишете свой собствен плъгин.

Благодаря!)

Източник: habr.com