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

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

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

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

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

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

• визуализация на „карта на приложението“: удобно представяне на приложенията в кластера, групирани по namespaces, deployment-и…;
• визуализация на връзки от типа „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 data-директорията на 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 файла с разметка. Вътре в контролера, чрез инжектиране на зависимости, можем да получим достъп до 2 важни angular услуги:

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

Част 4: datasource

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

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

• извличане на данни от api-server’а k8s (получаване на списък с namespace’и, deployment’и…)
• проксириране на запитвания към prometheus-datasource (който се избира в настройките на плъгина за всеки конкретен клъстер) и форматиране на отговорите за използване на данните както в статични страници, така и в табла за управление.
• актуализиране на данните на статичните страници на плъгина (с определен интервал на обновяване).
• обработка на запитвания за генериране на шаблонен списък в 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 можем да обявим набор от правила за роутинг, които ще бъдат обработвани от proxy-сервера на grafana. Например, за всеки отделен endpoint съществува възможност за задаване на заглавки или url с възможност за шаблонизация, данни за които могат да бъдат извлечени от полетата jsonData и secureJsonData (за съхранение на пароли или токени в криптиран вид). В нашия пример, заявки от вида /__proxy/api/v1/namespaces ще бъдат проксирни на url от вида
/api/v1/namespaces с задаване на заглавка Authorization: Bearer.

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

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

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

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

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

И накрая, ще видите чудесна картинка от вида:

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

Част 6: вместо заключения

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

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

Благодаря!)

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