إدارة APISIX بشكل تصريحي باستخدام APISIX Declarative CLI

APISIX يستخدم المستخدمون بشكل أساسي واجهة برمجة التطبيقات الإدارية (Admin API) لتكوين APISIX. ولكن مع زيادة تعقيد التكوينات، يصبح إدارة هذه التكوينات فقط من خلال واجهة برمجة التطبيقات الإدارية أكثر صعوبة.

لتسهيل الأمور، قمنا بتطوير APISIX Declarative CLI، المعروف أيضًا باسم ADC، وهو أداة تتيح لك تعريف تكوينات APISIX بشكل تصريحي.

في هذه المقالة، سنلقي نظرة على كيفية إدارة تكوينات APISIX باستخدام ADC.

نشر APISIX

قبل أن نبدأ، يجب علينا أولاً تشغيل نسخة من APISIX للتفاعل معها وتكوينها. يمكننا تشغيل APISIX في Docker عن طريق تنفيذ الأمر التالي:

curl -sL https://run.api7.ai/apisix/quickstart | sh

راجع وثائق APISIX لمعرفة المزيد حول استخدام APISIX.

تثبيت ADC

يمكنك تثبيت ADC باستخدام أمر go install:

go install github.com/api7/adc@latest

سيؤدي هذا إلى تثبيت ملف adc الثنائي في دليل $GOPATH/bin.

:::ملاحظة

تأكد من إضافة هذا إلى متغير البيئة $PATH:

export PATH=$PATH:$GOPATH/bin

:::

إذا لم يكن لديك Go مثبتًا، يمكنك أيضًا تنزيل أحدث ملف ثنائي لـ adc لنظام التشغيل الخاص بك وإضافته إلى مجلد /bin كما يلي:

wget https://github.com/api7/adc/releases/download/v0.2.0/adc_0.2.0_linux_amd64.tar.gz
tar -zxvf adc_0.2.0_linux_amd64.tar.gz
mv adc /usr/local/bin/adc

يمكنك العثور على الملفات الثنائية لأنظمة التشغيل الأخرى على صفحة الإصدارات. في المستقبل، سيتم نشر هذه الملفات الثنائية على مديري الحزم مثل Homebrew.

للتحقق من تثبيت adc، قم بتنفيذ الأمر التالي:

adc --help

إذا كان كل شيء على ما يرام، ستشاهد قائمة بالأوامر الفرعية المتاحة وكيفية استخدامها.

تكوين ADC مع نسخة APISIX الخاصة بك

لتكوين ADC للعمل مع نسخة APISIX التي قمت بنشرها، يمكنك تنفيذ الأمر التالي:

adc configure

سيطلب منك إدخال عنوان خادم APISIX ('http://127.0.0.1:9180' إذا كنت تتبع الخطوات) والرمز المميز.

إذا كان كل شيء صحيحًا، يجب أن ترى رسالة كما يلي:

تم تكوين ADC بنجاح!
تم الاتصال بـ APISIX بنجاح!

:::نصيحة

يمكنك استخدام الأمر الفرعي ping للتحقق من الاتصال بـ APISIX في أي وقت:

adc ping

:::

التحقق من صحة ملفات تكوين APISIX

لنقم بإنشاء تكوين أساسي لـ APISIX مع مسار يقوم بتوجيه الحركة إلى upstream:

name: "التكوين الأساسي"
version: "1.0.0"
services:
  - name: httpbin-service
    hosts:
      - api7.ai
    upstream:
      name: httpbin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
routes:
  - name: httpbin-route
    service_id: httpbin-service
    uri: "/anything"
    methods:
      - GET

بمجرد اتصال ADC بنسخة APISIX قيد التشغيل، يمكننا استخدامه للتحقق من صحة هذا التكوين قبل تطبيقه عن طريق تنفيذ الأمر التالي:

adc validate -f config.yaml

إذا كان التكوين صالحًا، يجب أن تتلقى استجابة مشابهة:

تم قراءة ملف التكوين بنجاح: اسم التكوين: التكوين الأساسي، الإصدار: 1.0.0، المسارات: 1، الخدمات: 1.
تم التحقق من صحة ملف التكوين بنجاح!

مزامنة التكوين مع نسخة APISIX

يمكنك الآن استخدام ADC لمزامنة التكوين الصالح مع نسخة APISIX المتصلة. للقيام بذلك، قم بتنفيذ الأمر التالي:

adc sync -f config.yaml

سيؤدي هذا إلى إنشاء مسار وخدمة كما أعلنا في ملف التكوين:

إنشاء الخدمة: "httpbin-service"
إنشاء المسار: "httpbin-route"
الملخص: تم إنشاء 2، تم تحديث 0، تم حذف 0

للتحقق مما إذا تم إنشاء المسارات بشكل صحيح، دعنا نحاول إرسال طلب:

curl localhost:9080/anything -H "host:api7.ai"

إذا كان كل شيء صحيحًا، ستتلقى استجابة من httpbin.org.

مقارنة التكوين المحلي مع التكوين قيد التشغيل

الآن دعنا نقوم بتحديث التكوين المحلي في ملف config.yaml بإضافة مسار آخر:

name: "التكوين الأساسي"
version: "1.0.0"
services:
  - name: httpbin-service
    hosts:
      - api7.ai
    upstream:
      name: httpbin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
routes:
  - name: httpbin-route-anything
    service_id: httpbin-service
    uri: "/anything"
    methods:
      - GET
  - name: httpbin-route-ip
    service_id: httpbin-service
    uri: "/ip"
    methods:
      - GET

قبل مزامنة هذا التكوين مع APISIX، يتيح لك ADC التحقق من الاختلافات بينه وبين تكوين APISIX الحالي. يمكنك القيام بذلك عن طريق تنفيذ الأمر التالي:

adc diff -f config.yaml

ستتمكن من رؤية الإضافات والحذف في التكوين وفهم ما تغير قبل تطبيقه.

تحويل تعريفات OpenAPI إلى تكوين APISIX

يدعم ADC أيضًا العمل مع تعريفات OpenAPI بشكل أساسي. يتيح لك ADC تحويل التعريفات بتنسيق OpenAPI إلى تكوين APISIX.

على سبيل المثال، إذا كنت قد وثقت API الخاص بك بتنسيق OpenAPI كما يلي:

openapi: 3.0.0
info:
  title: httpbin API
  description: Routes for httpbin API
  version: 1.0.0
servers:
  - url: http://httpbin.org
paths:
  /anything:
    get:
      tags:
        - default
      summary: Returns anything that is passed in the request data
      operationId: getAnything
      parameters:
        - name: host
          in: header
          schema:
            type: string
          example: "{{host}}"
      responses:
        "200":
          description: Successfully return anything
          content:
            application/json: {}
  /ip:
    get:
      tags:
        - default
      summary: Returns the IP address of the requester
      operationId: getIP
      responses:
        "200":
          description: Successfully return IP
          content:
            application/json: {}

يمكنك استخدام الأمر الفرعي openapi2apisix لتحويل هذا إلى تكوين APISIX كما يلي:

adc openapi2apisix -o config.yaml -f openAPI.yaml

سيؤدي هذا إلى إنشاء ملف تكوين مثل هذا:

name: ""
routes:
- desc: Returns anything that is passed in the request data
  id: ""
  methods:
  - GET
  name: getAnything
  uris:
  - /anything
- desc: Returns the IP address of the requester
  id: ""
  methods:
  - GET
  name: getIP
  uris:
  - /ip
services:
- desc: Routes for httpbin API
  id: ""
  name: httpbin API
  upstream:
    id: ""
    name: ""
    nodes: null
version: ""

كما ترى، التكوين غير مكتمل، وستحتاج إلى إضافة الكثير من التكوينات يدويًا. نحن نعمل على تحسين ADC لسد هذه الفجوة بين تعريفات OpenAPI وما يمكن تعيينه مباشرة إلى تكوين APISIX.

نصيحة: استخدام الإكمال التلقائي

يمكنك القيام بالكثير باستخدام ADC، ومن المتوقع أن تزداد قائمة الميزات. لمعرفة كيفية استخدام أي أمر فرعي، يمكنك استخدام العلم --help أو -h، والذي سيظهر وثائق الأمر الفرعي.

لتسهيل الأمور أكثر، يمكنك إنشاء نص إكمال تلقائي لبيئة shell الخاصة بك باستخدام الأمر الفرعي completion. على سبيل المثال، إذا كنت تستخدم shell zsh، يمكنك تنفيذ الأمر التالي:

adc completion zsh

يمكنك بعد ذلك نسخ ولصق المخرجات في ملف .zshrc الخاص بك، وسيبدأ في عرض التلميحات عند استخدام adc.

ADC لا يزال في مراحله الأولى ويتم تحسينه باستمرار. لمعرفة المزيد عن المشروع، الإبلاغ عن الأخطاء، أو اقتراح ميزات، قم بزيارة github.com/api7/adc.