Что нового в ADC 0.8, 0.9 и 0.10?

Введение

ADC (APISIX Declarative CLI) — это инструмент декларативной конфигурации, представленный компанией API7.ai, который предоставляет удобный набор инструментов для реализации GitOps. Пользователи могут легко интегрировать его в свои CI/CD-процессы для управления полным жизненным циклом API, завершая обновления и выпуски API. После выпуска версии 0.7, ADC выпустил три новые версии: 0.8, 0.9 и 0.10, с оптимизациями и обновлениями в функциональности, производительности и пользовательском опыте.

Новые функции ADC

Улучшения в детекторе изменений ресурсов: Differ

Эти изменения были представлены в версиях 0.8 и 0.9.

Мы представили новую версию детектора изменений ресурсов Differ, v3, которая имеет значительные улучшения в функциональности и качестве кода.

1. Новый Differ вводит механизм слияния значений по умолчанию для локальных ресурсов, гарантируя, что значения по умолчанию на стороне сервера не влияют на проверку изменений ресурсов ADC.

   Когда клиент отправляет запрос на создание ресурса через API7 или APISIX Admin API, сервер выполняет проверку схемы (Schema validation) для отправленного запроса. В этом процессе некоторые поля, которые имеют значения по умолчанию, отмеченные в схеме, но не отправленные клиентом, автоматически добавляются к отправленному ресурсу. В результате, когда мы читаем ресурс из API, он будет отличаться от первоначальной отправки.

   Предыдущие версии ADC помечали такие ресурсы как "измененные" и отправляли запросы на обновление через Admin API. Это поведение вносило некоторую неопределенность для ADC, и эта проблема была решена с помощью Differ.

2. Механизм слияния значений по умолчанию был реализован в бэкенде API7, гарантируя, что различия в ресурсах считаются изменениями только тогда, когда пользователь изменил локальную конфигурацию YAML.

3. Уточнена детализация проверки Differ: ADC теперь выполняет проверку изменений ресурсов отдельно на уровне тела ресурса и плагинов, что помогает снизить аномалии при проверке.

4. Оптимизировано качество кода, упрощены избыточные части кода для улучшения читаемости и исправлены некоторые ошибки.

Фильтры ресурсов

Мы добавили два механизма фильтрации ресурсов на основе меток и типов ресурсов. Они могут использоваться для исключения ненужных ресурсов во время операций получения, проверки различий и синхронизации.

Фильтр по меткам ресурсов

Эта функция была представлена в версии 0.8.

Этот фильтр выполняет фильтрацию на основе поля labels ресурсов. Пользователи могут включить фильтр, используя параметр --label-selector key=value в командной строке. Он поддерживает настройку нескольких условий фильтрации, и только удаленные ресурсы, которые одновременно соответствуют этим правилам, будут считаться существующими, а локальные ресурсы будут автоматически дополнены этими метками.

Это гарантирует, что мы выполняем проверку и синхронизацию ресурсов в узкой области, что помогает разделить задачи, выполняемые в CI/CD-процессе, и предотвратить случайную синхронизацию, которая может повредить ресурсы, не требующие изменений.

Фильтр по типу ресурсов

Эта функция была представлена в версии 0.9.

Мы добавили два новых параметра командной строки: --include-resource-type <type> и --exclude-resource-type <type>, которые могут быть настроены несколько раз, но параметры включения и исключения взаимоисключают друг друга.

С помощью этих параметров мы можем фильтровать определенные типы ресурсов из текущей операции. Например, использование include-resource-type позволяет установить белый список и выбрать типы ресурсов, которые будут включены в операцию; в то время как exclude-resource-type определяет типы ресурсов, которые будут исключены из операции.

Это помогает нам лучше обрабатывать ресурсы, которые не требуют частых изменений, такие как метаданные плагинов и глобальные правила плагинов.

Улучшения командной строки

Эти улучшения были представлены в версии 0.9.

Настройка TLS-сертификатов

Мы добавили ряд параметров, связанных с TLS, в командную строку, таких как:

• --ca-cert-file для указания файла CA-сертификата сервера
• --tls-skip-verify для отключения проверки сертификата сервера TLS
• --tls-client-cert-file и --tls-client-key-file для указания файлов клиентского сертификата mTLS

Эти параметры помогают ADC установить безопасное зашифрованное соединение и предотвратить атаки "человек посередине".

Управление тайм-аутом

Мы добавили параметр --timeout <duration> для управления длительностью тайм-аута вызовов API, поддерживая синтаксис, например, 1m30s. Когда вызов Admin API занимает слишком много времени или зависает, механизм тайм-аута срабатывает, чтобы предотвратить бесконечное ожидание.

Режим отладки

Эта функция была представлена в версии 0.9.

Когда ADC выполняет внутренние операции с ресурсами, ему необходимо вызывать большое количество API. Иногда нам может потребоваться проверить эти вызовы API, чтобы проанализировать, правильно ли они отправляются, или убедиться, что ответы сервера соответствуют ожиданиям. Хотя для этого можно использовать захват пакетов, эта операция неудобна, и возникают значительные трудности при включении TLS.

Поэтому мы добавили встроенный режим отладки в ADC, который можно включить с помощью параметра --verbose <integer>. Когда этот параметр установлен на 2, ADC будет выводить запросы и ответы каждого внутреннего вызова API для помощи в отладке.

Этот параметр также можно использовать для скрытия логов. Когда этот параметр установлен на 0, ADC скрывает все общие логи, кроме ошибок.

Усиление обработки удаленных ресурсов

Эта функция была представлена в версии 0.9.

Поскольку ADC — не единственный способ настройки сервисов, маршрутов и т.д., пользователи также могут использовать панель управления API7 Enterprise для этого через простые операции. Это привело к проблеме: операции на панели управления используют случайно сгенерированные идентификаторы ресурсов, в то время как ADC использует имя ресурса в конфигурации YAML для генерации фиксированного идентификатора ресурса для точного определения ресурса.

Это означает, что если пользователь создает ресурс на панели управления, ADC не сможет найти его по идентификатору ресурса. ADC не может изменять или удалять ресурсы, созданные на панели управления, но эти ресурсы все равно будут отображаться при проверке изменений, но не могут быть корректно обработаны.

Поэтому мы оптимизировали соответствующую логику бэкенда API7 ADC. Если удаленные и локальные ресурсы содержат ресурсы с одинаковыми именами, но идентификаторы не совпадают, ADC может корректно удалить удаленный ресурс и создать новый на основе локальной конфигурации, в этом случае идентификатор будет сгенерирован ADC на основе имени ресурса и может использоваться для последующего поиска ресурса. Пользователи панели управления API7 не будут затронуты, и ресурсы, созданные ADC, все равно будут видны на панели управления.

Поддержка расширенных полей ADC в конвертере OpenAPI

Эта функция была представлена в версии 0.10.

Для создания согласованного процесса от OpenAPI к ADC и API7, конвертер OpenAPI должен вставлять необходимые поля в файл конфигурации ADC YAML в соответствии с нашими потребностями.

Например, чтобы изменить поле pass_host в upstream сервиса, ранее мы могли только вручную использовать конвертер для преобразования OpenAPI в файл конфигурации ADC, вручную изменить поле pass_host, а затем отправить измененный файл в репозиторий Git для выполнения синхронизации ADC в CI/CD-процессе. Этот процесс не является согласованным и требует большого количества ручного вмешательства.

Теперь, благодаря введенным расширениям x-adc, пользователям достаточно записать расширенные поля в определенных местах документа OpenAPI, и ADC корректно запишет эти поля в сгенерированный файл конфигурации. С помощью этих расширений пользователи могут напрямую изменять любое содержимое конфигурации ADC в OpenAPI, например, добавлять метки, добавлять плагины и переопределять конфигурацию по умолчанию для сервисов/upstreams/маршрутов.

В результате, поддерживая только один файл OpenAPI, можно реализовать процесс OpenAPI-ADC-API7 в одном месте, что значительно упрощает рабочий процесс GitOps для конфигурации API-шлюза.

Заключение

Инструмент декларативной конфигурации ADC, запущенный API7.ai, помогает предприятиям реализовать управление API-шлюзами через GitOps. В новых версиях 0.8, 0.9 и 0.10 инструмент был функционально оптимизирован и обновлен, добавлены такие функции, как мониторинг изменений ресурсов и фильтрация. Эти новые функции вносят новый импульс в управление полным жизненным циклом API.

Эти новые возможности позволяют ADC лучше удовлетворять потребности предприятий в управлении API-шлюзами через GitOps, повышая эффективность и гибкость управления API.