PmaControl REST API: البنية التحتية كرمز لـ MariaDB / MySQL

لماذا API REST؟

بدأت PmaControl كأداة تعتمد على الويب. نضيف خادم MariaDB / MySQL من خلال النقر على الأزرار، ونقوم بتكوين العلامات باستخدام الماوس، وندير البيئات في النماذج.

هذا يعمل لمدة 10 خوادم. في الخمسين، الأمر مؤلم. عند 200، هذا مستحيل.

يقوم API REST الخاص بـ PmaControl بتحويل الأداة إلى منصة قابلة للبرمجة. يمكن الوصول إلى كل إجراء متاح في واجهة الويب عبر نقطة نهاية JSON. يؤدي هذا إلى فتح الباب أمام البنية التحتية كرمز: وصف مخزون قاعدة البيانات الخاصة بك في ملفات YAML أو JSON، وتطبيقه تلقائيًا.

المصادقة

يستخدم API مصادقة مستخدم خدمة الويب. إنه حساب PmaControl مخصص، دون الوصول إلى واجهة الويب، ويعمل رمزه المميز كمفتاح API.

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     https://pmacontrol.example.com/api/v1/servers

يرث مستخدم خدمة الويب قوائم ACL من ملفه الشخصي. يمكن لملف التعريف "للقراءة فقط" أن يسرد الموارد فقط. يمكن لملف تعريف "المسؤول" إنشاء وتعديل وحذف.

موارد API

العلامات

العلامات هي نظام تصنيف PmaControl. يمكن لكل خادم أن يحمل علامة واحدة أو أكثر (الإنتاج، التدريج، Client-Ame، DC-Paris، وما إلى ذلك).

# Lister tous les tags
GET /api/v1/tags

# Créer un tag
POST /api/v1/tags
{"name": "production", "color": "#22c55e"}

# Modifier un tag
PUT /api/v1/tags/42
{"name": "prod", "color": "#22c55e"}

# Supprimer un tag
DELETE /api/v1/tags/42

العلامات هي لبنة بناء التنظيم. إنها تسمح لك بتصفية لوحات المعلومات وتنبيهات النطاق وتقييد الوصول حسب الملف الشخصي.

العملاء

يمثل العملاء المؤسسات أو المشاريع التي تمتلك خوادم.

# Lister les clients
GET /api/v1/clients

# Créer un client
POST /api/v1/clients
{"name": "Acme Corp", "contact_email": "dba@acme.com"}

# Modifier un client
PUT /api/v1/clients/7
{"name": "Acme Corporation"}

# Supprimer un client
DELETE /api/v1/clients/7

البيئات

تتمتع البيئات (الإنتاج، والتجهيز، والتطوير، وما إلى ذلك) بسياسة حذف خاصة: عند حذف بيئة ما، لا يتم تدمير خوادمها ولكن يتم إعادة تعيينها إلى بيئة افتراضية.

# Lister les environnements
GET /api/v1/environments

# Créer un environnement
POST /api/v1/environments
{"name": "staging", "description": "Pre-production environment"}

# Supprimer — les serveurs sont réaffectés
DELETE /api/v1/environments/3
# Réponse : {"reassigned_servers": 12, "target_environment": "default"}

تمنع هذه السياسة عمليات الحذف غير المقصودة للخادم عند إعادة تنظيم البيئات.

الأسماء المستعارة

تسمح لك الأسماء المستعارة بالإشارة إلى الخادم باسم قابل للقراءة بدلاً من عنوان IP الداخلي أو اسم المضيف.

# Lister les alias
GET /api/v1/aliases

# Créer un alias
POST /api/v1/aliases
{"alias": "db-writer-prod", "server_id": 42}

مناطق التخزين

تمثل مناطق التخزين مناطق التخزين (مراكز البيانات والمناطق السحابية وما إلى ذلك).

# Lister les storage areas
GET /api/v1/storage-areas

# Créer une storage area
POST /api/v1/storage-areas
{"name": "dc-paris-1", "provider": "OVH", "location": "Paris, France"}

مفاتيح SSH

يستخدم PmaControl مفاتيح SSH للاتصال بالخوادم وجمع المقاييس. يتيح لك API إدارة دورة حياة المفتاح.

# Lister les clés SSH
GET /api/v1/ssh-keys

# Créer une clé SSH
POST /api/v1/ssh-keys
{
  "name": "pmacontrol-collector-2026",
  "public_key": "ssh-ed25519 AAAA...",
  "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
}

# Supprimer une clé
DELETE /api/v1/ssh-keys/5

ملاحظة أمنية: يتم تشفير المفاتيح الخاصة في قاعدة البيانات PmaControl. لا يقوم API أبدًا بإرجاع المفتاح الخاص أثناء عملية GET.

الخوادم

المورد الرئيسي. CRUD الكامل لمثيلات MariaDB / MySQL الخاضعة للإشراف.

# Lister tous les serveurs
GET /api/v1/servers

# Lister avec filtres
GET /api/v1/servers?tag=production&environment=staging

# Détail d'un serveur
GET /api/v1/servers/42

# Créer un serveur
POST /api/v1/servers
{
  "hostname": "db-prod-01.acme.com",
  "ip": "10.0.1.10",
  "port": 3306,
  "ssh_key_id": 5,
  "client_id": 7,
  "environment_id": 1,
  "tags": ["production", "galera", "dc-paris"]
}

# Modifier un serveur
PUT /api/v1/servers/42
{"port": 3307}

# Assigner des tags
POST /api/v1/servers/42/tags
{"tags": ["production", "critical"]}

# Assigner une clé SSH
PUT /api/v1/servers/42/ssh-key
{"ssh_key_id": 5}

# Supprimer un serveur
DELETE /api/v1/servers/42

سير عمل البنية التحتية كرمز

الاهتمام الرئيسي لـ API هو القدرة على وصف المخزون الكامل في ملف تم إصداره وتطبيقه تلقائيًا.

مثال: ملف مخزون YAML

# pmacontrol-inventory.yaml
tags:
  - name: production
    color: "#22c55e"
  - name: staging
    color: "#f59e0b"
  - name: galera
    color: "#14b8a6"

environments:
  - name: production
  - name: staging
  - name: development

ssh_keys:
  - name: collector-2026
    public_key_file: ./keys/collector-2026.pub

servers:
  - hostname: db-prod-01.acme.com
    ip: 10.0.1.10
    port: 3306
    ssh_key: collector-2026
    environment: production
    tags: [production, galera]

  - hostname: db-prod-02.acme.com
    ip: 10.0.1.11
    port: 3306
    ssh_key: collector-2026
    environment: production
    tags: [production, galera]

  - hostname: db-staging-01.acme.com
    ip: 10.0.2.10
    port: 3306
    ssh_key: collector-2026
    environment: staging
    tags: [staging]

البرنامج النصي للتطبيق

يقرأ البرنامج النصي Python أو Bash هذا الملف ويستدعي API PmaControl لمزامنة الحالة:

#!/bin/bash
API="https://pmacontrol.example.com/api/v1"
TOKEN="your-webservice-token"

# Créer les tags
for tag in production staging galera; do
  curl -s -X POST "$API/tags" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"$tag\"}"
done

# Créer les serveurs
curl -s -X POST "$API/servers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @server-prod-01.json

تكامل CI/CD

النمط الطبيعي هو دمج هذا في خط أنابيب CI/CD:

1. يقوم DBA بتعديل ملف pmacontrol-inventory.yaml في Git
2. تتم مراجعة طلب الدمج من قبل الفريق
3. يتحقق خط أنابيب CI من صحة بناء الجملة والقيود (لا توجد عناوين IP مكررة، ومفاتيح SSH صالحة)
4. يطبق مسار القرص المضغوط التغييرات عبر API PmaControl
5. PmaControl يبدأ بمراقبة الخوادم الجديدة تلقائيًا

العجز الجنسي

جميع نقاط نهاية الإنشاء غير فعالة: إذا كان المورد موجودًا بالفعل (نفس اسم المضيف ونفس عنوان IP)، فسيقوم API بإرجاع المورد الموجود بدلاً من إنشاء نسخة مكررة. يتيح لك ذلك إعادة تشغيل البرنامج النصي للمخزون دون آثار جانبية.

# Premier appel : crée le serveur, retourne 201
POST /api/v1/servers  → 201 Created

# Deuxième appel identique : retourne le serveur existant, 200
POST /api/v1/servers  → 200 OK (existing)

رموز العودة

الحدود الحالية

يغطي API v1 عمليات CRUD في المخزون. وهي لا تغطي بعد:

• المقاييس (قراءة السلاسل الزمنية) — مخطط لها في الإصدار الثاني
• التنبيهات (تكوين الحد الأدنى) — مخطط لها للإصدار 2
• النسخ الاحتياطية (التشغيل والحالة) — مخطط لها للإصدار 2
• تصدير التكوين (قواعد my.cnf، ProxySQL) - قيد المناقشة

الخلاصة

يعمل API REST لـ PmaControl على تحويل إدارة أسطول MariaDB / MySQL من عملية يدوية إلى سير عمل قابل للبرمجة وإصدار.

قم بوصف المخزون الخاص بك في Git. قم بتطبيقه عبر API. اسمح لـ PmaControl بالإشراف تلقائيًا. يتم تطبيق البنية التحتية كرمز على مراقبة قاعدة البيانات.