واجهة سطر الأوامر لمسؤول Awanio (awadm) - دليل المستخدم

يشرح هذا الدليل كيفية تثبيت وتكوين واستخدام awadm — واجهة سطر الأوامر (CLI) الخاصة بالمسؤول لإدارة عناقيد Awanio (واجهة بديلة للوحة تحكم Awanio Dashboard).

أنظمة التشغيل المدعومة: macOS/Linux. تفترض الأوامر أدناه استخدام غلاف POSIX (bash/zsh).

1. التثبيت

الملف البرمجي المجمع مسبقًا (مثال لنظام Linux amd64):

curl -O https://storage.awan.io/assets/awadm-linux-amd64.tar.gz
tar -xvf awadm-linux-amd64.tar.gz
chmod +x ./awadm
sudo mv ./awadm /usr/local/bin/
awadm --version

2. التكوين

يقوم awadm بقراءة بيانات الاعتماد من ملف awanconfig. افتراضيًا يستخدم:

• المسار الافتراضي: ~/.awan/config
• التجاوز باستخدام: --awanconfig /path/to/config

طريقتان للتكوين:

أ) تدفق تسجيل الدخول (موصى به)

• يقوم بتبادل اسم المستخدم/كلمة المرور الخاصة بلوحة التحكم مقابل بيانات اعتماد API ويككتب awanconfig.

مثال:

awadm config clusters login \
  --name dev3 \
  --username awanio \
  --url https://0.0.0.0/v2
# يطالب بكلمة المرور إذا تم إغفال --password

ب) الإعداد اليدوي أنشئ ~/.awan/config مع محتوى YAML التالي:

apiVersion: v1
clusters:
  dev-cluster:
    server: https://0.0.0.0/v2
    access-key: sa-xxxxxx
    access-secret: yyyyyy
  demo-cluster:
    server: https://192.168.1.10/v2
    access-key: sa-aaaaaa
    access-secret: bbbbbb
contexts:
  current-context: dev-cluster

أوامر التكوين المفيدة:

• عرض السياق الحالي: awadm config context
• تعيين السياق الحالي: awadm config context set <cluster-name>
• عرض قائمة العناقيد: awadm config clusters
• حذف عنقود من التكوين: awadm config clusters delete <cluster-name>
• عرض مسار ملف التكوين ومحتواه: awadm config info

ملاحظة: يتطلب تدفق تسجيل الدخول أن يكون المستخدم عضوًا في المؤسسة "root" لإنشاء حسابات الخدمة (service accounts) تلقائيًا.

3. مرجع أوامر awadm

الأعلام العامة (Global flags):

• --awanconfig string المسار إلى ملف التكوين (افتراضيًا: ~/.awan/config)
• -o, --output string تدعم بعض الأوامر تنسيق الإخراج (table أو json)

3.1 الأجهزة الافتراضية (Virtual Machines)

• عرض قائمة VMs:

awadm vm --size-per-page 100 --sort-by id --order desc --page 1 [--search <kw>]

الأعمدة: uuid, Title, Status, Organization, CPU, Ram

• تفاصيل VM حسب UUID:

awadm vm get <vuid> [-o json]

• مقاييس VM (آخر 60 دقيقة، خطوة كل 10 دقائق):

awadm vm metric <vuid> --since-x-minute-ago 60 --minute-step 10

• تصدير مقاييس VM إلى CSV:

awadm vm metric <vuid> --since-x-minute-ago 120 --minute-step 10 --export-path vm_metrics.csv --export-format csv

• مخرجات JSON:

awadm vm metric <vuid> --since-x-minute-ago 60 --minute-step 10 -o json

• مخرجات OID بنمط SNMP:

awadm vm metric <vuid> --since-x-minute-ago 60 --minute-step 10 --output snmp --snmp-base-oid .1.3.6.1.4.1.99999.1

3.2 المجلدات (Volumes)

• عرض قائمة المجلدات:

awadm volume

الأعمدة: uuid, Title, Size, Backend Storage

• تفاصيل المجلد حسب UUID:

awadm volume get <uuid> [-o json]

3.3 العقد (Nodes)

• عرض قائمة العقد:

awadm nodes

الأعمدة: name, status, internal_ip, network, mem_ok, disk_ok, pid_ok

أعلام تقسيم الصفحات (Pagination flags):

• -p, --page string الصفحة الحالية في الترقيم (افتراضيًا: 1)
• -s, --size-per-page string الحد الأقصى لعدد العناصر في قائمة الإخراج (افتراضيًا: 15)

مثال مع ترقيم الصفحات:

awadm nodes -p 2 -s 20

• مقاييس العقدة (استخدام CPU والذاكرة):

awadm nodes metric <node-name> --since-x-minute-ago 60 --minute-step 10

الأعلام:

• --since-x-minute-ago int عدد الدقائق الماضية من الآن لبدء النطاق (متعارض مع start/end)
• --start string وقت البدء بتنسيق '2006-01-02 15:04:05'
• --end string وقت الانتهاء بتنسيق '2006-01-02 15:04:05'
• --minute-step int خطوة تجميع الدقائق
• -o, --output string تنسيق الإخراج: table أو json أو snmp (افتراضيًا: table)
• --snmp-base-oid string OID الأساسي لنمط إخراج SNMP (افتراضيًا .1.3.6.1.4.1.99999.2)
• --export-path string مسار الملف الاختياري لتصدير السلاسل الزمنية للمقاييس
• --export-format string تنسيق التصدير: csv أو spreadsheet (افتراضيًا csv)

أمثلة:

# الجدول (افتراضي)
awadm nodes metric awid5

# مخرجات JSON
awadm nodes metric awid5 -o json

# مخرجات OID بنمط SNMP
awadm nodes metric awid5 -o snmp --snmp-base-oid .1.3.6.1.4.1.99999.2

# تصدير السلاسل الزمنية إلى CSV
awadm nodes metric awid5 --export-path ./node_metrics_awid5.csv

# نطاق زمني محدد
awadm nodes metric awid5 --start "2025-08-10 12:00:00" --end "2025-08-10 14:00:00" --minute-step 5

ملاحظات:

• تحتوي استجابات API لمقاييس العقد على هيكل JSON مختلف عن مقاييس VM؛ تقوم CLI بتسوية ذلك داخليًا حتى تكون المخرجات والتصديرات متسقة.

• معرّفات Fibre Channel WWIDs:

awadm nodes storages fibre-channel

الأعمدة: wwid, wwn, size

3.4 حسابات الخدمة (Service Accounts)

• عرض قائمة حسابات الخدمة:

awadm service-accounts

الأعمدة: uuid, AccesKey, Status

• إنشاء حساب خدمة:

awadm service-accounts create --name <name> --org-uid <organization-uuid>

الأعلام:

• --name (مطلوب): 6–20 حرفًا؛ أحرف، أرقام، شرطة (-)، شرطة سفلية (_)، نقطة (.)

• --org-uid (مطلوب): UUID للمؤسسة

• حذف حسابات الخدمة بواسطة UUID(s):

awadm service-accounts delete <uuid> [<uuid> ...]

3.5 التراخيص (Licenses)

• عرض قائمة التراخيص المطبقة:

awadm license

الأعمدة: license key, cluster id, features, maximum cpu socket, expired date

• إضافة مفتاح ترخيص جديد:

awadm license add <license-key>

4. أمثلة

• البدء السريع: تسجيل الدخول وعرض قائمة VMs

awadm config clusters login --name dev --username admin --url https://0.0.0.0/v2
awadm vm --search web
awadm vm get 00000000-0000-0000-0000-000000000000

• تبديل السياق وعرض قائمة المجلدات

awadm config context set demo-cluster
awadm volume

• إنشاء حساب خدمة عبر تدفق تسجيل الدخول، ثم إنشاء وعرض SAs

awadm config clusters login --name demo --username admin --url https://192.168.1.10/v2
awadm service-accounts create --name sa-demo --org-uid 00000000-0000-0000-0000-000000000000
awadm service-accounts

5. الإخراج والتنسيق

• الإخراج في جدول هو الافتراضي لعروض القوائم والتفاصيل.
• يمكن طلب إخراج JSON لبعض أوامر التفاصيل عبر -o json.

6. استكشاف الأخطاء وإصلاحها

• وصول غير مصرح به أو غير صالحة:

  • تأكد من أن awanconfig يحتوي على access-key و access-secret صالحة للسياق المحدد.
  • تحقق من أن URL الـ server صحيح ويمكن الوصول إليه.

• شهادات SSL/TLS:

  • إذا كانت بيئتك تستخدم شهادات ذاتية التوقيع (self-signed)، فتأكد من أن شهادة الخادم موثوقة في نظام التشغيل لديك. قد يتجاوز العميل التحقق من TLS في بعض المكالمات، ولكن يوصى بالتكوينات الآمنة.

• فشل تدفق تسجيل الدخول:

  • تأكد من صحة بيانات اعتماد لوحة التحكم.
  • يجب أن ينتمي المستخدم إلى المؤسسة "root" لإنشاء حسابات الخدمة.

• الحقول الفارغة أو المفقودة في إخراج الجدول:

  • تحمي CLI من الحقول المفقودة (مثل Status و Organization و Backend Storage)، حيث تعرض - إذا كانت غير متوفرة.

7. ملاحظات أمنية

• قم بتخزين ومشاركة awanconfig بحذر؛ فهو يحتوي على بيانات اعتماد API.
• يفضل اتباع نهج الصلاحيات الأدنى (least-privilege) لحسابات الخدمة.

8. الإصدار والمساعدة

• عرض الإصدار:
  • awadm --version
• عرض تعليمات الأوامر:
  • awadm --help أو awadm <command> --help