CI/CD для API¶

API стали нормой для соединения приложений, сервисов и данных. Организация может иметь несколько сред, таких как разработка, тестирование, QA, подготовка и продакшн, каждая со своим экземпляром API Managers. Поэтому API должны быть доступны в каждой среде после того, как разработчики укажут требуемые условия. Ручное перемещение API между средами — утомительная, подверженная ошибкам и отнимающая много времени задача. Это резко снижает производительность организации.

NEOMSA APIM решает проблему автоматизации API, предоставляя платформенно-независимое, ориентированное на разработчика решение. Инструмент NEOMSA API Controller (apictl) играет ключевую роль в конвейере автоматизации. Он может легко интегрировать конфигурации, связанные со средой, а также создавать проекты API из спецификаций OpenAPI, открывая путь к полностью автоматизированному развертыванию API всего за несколько шагов. Благодаря гибкому инструментарию NEOMSA APIM готов удовлетворить современные требования к автоматизации развертываний API.

Непрерывная интеграция и непрерывное развертывание для API — это открытый сценарий; разные организации по-разному решают эту проблему. На приведенной выше схеме показано общее решение, включающее минимальное количество сторон в организации для автоматизации API. Хотя на схеме показаны три стороны, их может быть больше или меньше в зависимости от структуры организации.

Разработчики API: разрабатывают API и сопутствующие сервисы.
Издатели API: публикация API для пользователей
DevOps: контроль процесса развертывания

Разработчики и издатели API работают с системой контроля версий, которая выступает в качестве единого источника достоверной информации для всего конвейера.

Создание конвейера CI/CD для API с использованием CLI¶

При реализации CI/CD для ваших API вы можете использовать два подхода.

Использование CLI

NEOMSA APIM поддерживает спецификации OpenAPI/Swagger для создания API. NEOMSA API Controller (apictl) может создавать проекты со спецификациями Swagger/OpenAPI без использования API Publisher в NEOMSA APIM . Эту мощную функцию можно использовать для проектирования конвейеров, зависящих от спецификаций Swagger/OpenAPI.

На основе генерации API Project можно разработать мощный пайплайн для автоматизации API с использованием OpenAPI/Swagger. Это позволяет быстро разрабатывать API и повышает продуктивность разработчиков.

Для миграции API с использованием подхода Developer First через CI/CD выполните шаги с 1 по 7 в порядке, который указан в разделе «Структурные элементы для создания конвейера CI/CD».

Использование издателя и CLI

Разработчики API могут использовать API Publisher в NEOMSA APIM для создания API в среде более низкого уровня. CI/CD для NEOMSA APIM опирается на систему контроля версий, которая действует как Single Source of Truth (SSOT) для пайплайна. Поэтому после того, как разработчик API экспортирует API из среды более низкого уровня, разработчик API может зафиксировать экспортированные артефакты API в репозитории управления исходным кодом, запустить тесты в среде более низкого уровня, продвинуть API в среду более высокого уровня и сгенерировать ключи для продвинутых API. Этот процесс плавного продвижения API в несколько сред можно автоматизировать с помощью инструмента apictl и других инструментов CI/CD (например, Jenkins, GitHub). Инструмент apictl упрощает этот процесс, поскольку он обрабатывает конфигурации, связанные с каждой средой.

Для миграции существующих API с помощью API Publisher через CI/CD выполните шаги, указанные в шагах с 1 по 7 данного раздела в последовательном порядке, который указан в разделе «Структурные элементы для создания конвейера CI/CD».

Строительные блоки для создания конвейера CI/CD

Давайте последовательно рассмотрим основные строительные блоки для создания конвейера CI/CD с помощью NEOMSA APIM .

Подготовка среды¶

Загрузите и установите NEOMSA APIM в своих средах.
Загрузите и установите версию apictl
Добавьте среды NEOMSA APIM с помощью команды.add env

Пример

Linux/Unix

apictl add env dev \
            --apim https://localhost:9443

apictl add env prod \
            --apim https://localhost:9444

Примечание. Команда apictl add-env устарела с версии apictl 4.0.0. Вместо этого используйте, apictl add env как показано выше.

Создание, развертывание и публикация API в тестовой среде¶

Теперь вы добавили две разные среды. Наша конечная цель — автоматизировать миграцию API между средами dev и prod. Поэтому сначала необходимо создать API с соответствующей информацией, создать новую ревизию, развернуть ревизию в соответствующих шлюзах и опубликовать в среде dev с помощью API Publisher в NEOMSA APIM . Для получения дополнительной информации о развертывании API в NEOMSA APIM .

Для этого примера воспользуемся Swagger Petstore - OpenAPI 3.0 .

Войдите в систему NEOMSA API Publisher.

https://<hostname>:9443/publisher (например, https://localhost:9443/publisher)

Нажмите «Создать API» , а затем нажмите «Импортировать открытый API» .

Укажите URL-адрес OpenAPI ( https://petstore3.swagger.io/api/v3/openapi.json) и перейдите к следующему шагу.
Определите имя API как SwaggerPetstore и версию как 1.0.0 и нажмите кнопку «Создать»

Перейдите в раздел «Конфигурации API» > «Конечные точки» и введите URL-адреса внутренних сред для производственной и песочницы.

Для этого примера давайте воспользуемся следующими конечными точками.

Production: https://dev.<domain name>.com
Sandbox: https://dev.<domain name>.com

Перейдите в раздел «Конфигурации портала» > «Подписки» , выберите «Business Plain» и сохраните API.

Для этого примера выберем план Gold .

Разверните и опубликуйте API.

Экспорт API из тестовой среды¶

apictl может экспортировать API в виде архива из тестовой среды (например, dev), который содержит всю информацию для воссоздания API в другой более высокой среде (например, prod).

Войдите в NEOMSA API-M в тестовой среде через apictl.

Пример

apictl login dev -u admin -p admin

Совет. Пользователь с ролью Internal/devops или ролью admin может экспортировать API.

Экспортируйте последнюю версию API из тестовой среды с помощью export api команды.

Пример

apictl export api -e dev -n SwaggerPetstore -v 1.0.0 --provider admin --latest

Примечание

- Здесь мы предполагаем, что последняя ревизия актуальна со всеми изменениями. При необходимости вы можете снять –latest флаг и экспортировать рабочую копию без информации о развертывании.

- Команда apictl export-api устарела с версии apictl 4.0.0 и далее. Вместо этого используйте, apictl export api как показано выше.

Извлеките содержимое (API будет экспортировано как архив в каталог <USER_HOME>/.wso2apictl/exported/apis/dev/). После извлечения вы найдете каталог с именем SwaggerPetstore-1.0.0.

Инициализация проекта с использованием спецификации Swagger/OpenAPI¶

Выполните следующую команду, чтобы напрямую сгенерировать PetstoreAPI проект с использованием спецификации Swagger/OpenAPI. (Вы можете загрузить спецификацию Swagger/OpenAPI здесь .

Пример

apictl init SwaggerPetstore-1.0.0 --oas path/to/openapi.json

Это создает проект API в каталоге SwaggerPetstore-1.0.0, используя предоставленную спецификацию. Этот проект может быть напрямую импортирован в NEOMSA API-M.
Apictl позволяет дополнительно настраивать инициализацию проекта с помощью файла шаблона. Общие сведения, характерные для организации, можно добавлять в этот файл шаблона и делиться ими с разработчиками для повышения производительности.
Для дальнейшей тонкой настройки создания API можно использовать дополнительный файл определения API. Этот файл определения поддерживает обнаружение переменных среды в процессе создания. Его можно объединить со скриптами для разработки мощных инструментов для автоматизации создания проекта API.
Используя этот метод, спецификация Swagger/OpenAPI становится single source of truth для развертывания API. Объединив шаблоны и файл определения, серверы автоматизации могут быть настроены для инициализации проектов API на основе спецификаций Swagger/OpenAPI и также иметь пользовательские файлы параметров. Это снижает вмешательство человека и повышает производительность.
Например, если организация использует микросервисную архитектуру, этот метод можно использовать для создания автоматизированного конвейера для переноса спецификаций Swagger/OpenAPI в среды более высокого уровня.

Откройте файлы api.yaml и api_meta.yaml внутри репозитория SwaggerPetstore-1.0.0 в текстовом редакторе и измените name и version на SwaggerPetstore и 1.0.0 соответственно в каждом файле для удобства.

Подготовка проекта API для CI/CD¶

Создайте два (2) репозитория в вашей системе контроля версий. Вы можете дать этим репозиториям любые имена, но в этом примере мы назовем их Source и Deployment.

Скопируйте созданный/экспортированный проект API в репозиторий исходного кода.
- Если вы используете подход Dev First — скопируйте инициализированный каталог проекта.
- Если вы используете подход на основе Publisher — скопируйте извлеченный каталог проекта.
Если вы хотите определить детали среды для API, выполните следующие действия.
- Создайте каталог артефактов развертывания для проекта API с помощью следующей команды.
```
apictl gen deployment-dir -s path/to/Source/SwaggerPetstore-1.0.0 -d path/to/Deployment
```

Сгенерированный индивидуальный репозиторий развертывания с именем DeploymentArtifacts_SwaggerPetstore-1.0.0 можно найти внутри репозитория развертывания.

В этом примере давайте определим URL-адреса бэкенда, используя файл параметров внутри сгенерированного репозитория развертывания.

- Откройте params.yaml внутри DeploymentArtifacts\_SwaggerPetstore-1.0.0 в текстовом редакторе и определите prod.example.local и prod.sandbox.example.local как внутренние URL-адреса.

Пример

environments:
    - name: dev
      configs:
          endpoints:
              production:
                  url: 'https://dev.example.local'
              sandbox:
                  url: 'https://dev.sandbox.example.local'
    - name: prod
      configs:
          endpoints:
              production:
                  url: 'https://prod.example.local'
              sandbox:
                  url: 'https://prod.sandbox.example.local'

Информация

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

    - Apictl поддерживает обнаружение определенных переменных среды. Если переменная среды не задана, инструмент не сработает. Кроме того, система запросит у пользователя набор требуемых переменных среды, чтобы гарантировать, что информация не будет упущена в процессе миграции.

    - Рекомендуется хранить параметры API и среды, специфичные для отдельных сред, в отдельных репозиториях (например, Source и Deployment).

Зафиксируйте изменения в системе контроля версий.

Импорт API в продуктивную среду¶

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

Для начала процесса необходимо установить инструмент apictl на серверах автоматизации. Поскольку инструмент поддерживает различные платформы, включая Linux, Windows и macOS, это можно сделать довольно легко.

а. Продвижение API в Git-репозитории в продуктивные среды через CI/CD

Репозитории (Source и Deployment), в которые вы коммитили файлы проекта на предыдущем шаге 5, необходимо клонировать в экземпляр, выполняющий процесс CI/CD. Инструмент apictl имеет встроенную поддержку интеграции с системами управления версиями на базе Git. Он предоставляет единый командный интерфейс vcs deploy для развертывания любого типа проекта (например, API, API Products и Applications).

Установите пути к директориям Исходного и Деплоймент репозиториев.
```
$ apictl set --vcs-source-repo-path path/to/Source
$ apictl set --vcs-deployment-repo-path path/to/Deployment
```

Примечание

- Установка пути к репозиторию Source обязательна перед выполнением vcs deploy на последних шагах.

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

- Если вы не задали путь к репозиторию развертывания, то при выполнении команды vcs deploy в среду будут учитываться только артефакты, находящиеся в исходном репозитории.

Перейдите в исходный каталог.
```
$ cd path/to/Source
```
Поскольку репозиторий Source впервые используется для интеграции с Git функционалом apictl, выполните команду vcs init для инициализации репозитория с apictl. Эту команду нужно выполнить только один раз для репозитория.

Пример

$ apictl vcs init
Successfully initialized GIT repository

После выполнения команды vcs init в корневом каталоге репозитория будет создан новый файл vcs.yaml.

Обязательно сохраните этот файл в репозитории.

Совет. vcs.yaml будет содержать уникальный идентификатор репозитория, который используется для хранения метаинформации, связанной с развернутыми коммитами.

Выполните команду vcs status, чтобы увидеть доступные изменения, которые необходимо развернуть в производственной среде (вы можете сделать то же самое, перейдя и выполнив приведенную ниже команду в репозитории развертывания).

Пример

$ apictl vcs status -e prod
Projects to Deploy (1)

APIs (1) ...
1: [save]       SwaggerPetstore-1.0.0: (SwaggerPetstore-1.0.0)

Если у вас есть репозиторий развертывания, выполните шаги a(2) - a(4) и для него.
Импортируйте API SwaggerPetstore в производственную среду, выполнив следующую команду.

Совет

- Убедитесь, что вы уже вошли в среду prod.

- Пользователь с ролью Internal/devops или admin может импортировать API.

Пример

$ apictl vcs deploy -e prod
Deploying Projects (1)...

APIs (1) ...
1: SwaggerPetstore-1.0.0: (SwaggerPetstore-1.0.0)
Successfully imported API.

Приведенная выше команда обнаружит целевую среду и предоставит ей API.

Если вы снова выполните команду vcs deploy, вы увидите следующий вывод, указывающий на то, что развертывание уже актуально..

Пример

$ apictl vcs deploy -e prod
Everything is up-to-date

Добавление нового API в репозиторий Git

Несколько API могут быть продвинуты через CI/CD, если соответствующие проекты API и артефакты развертывания будут зафиксированы в репозиториях.

- Создайте еще один проект API ( Pizzashack-1.0.0 ).

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

- Зафиксируйте все новые изменения в репозиториях Source и Deployment.

- Перейдите в репозиторий Source и выполните команду vcs status, чтобы проверить добавление нового проекта (то же самое можно сделать, перейдя в репозиторий Deployment).

    ```bash
    $ apictl vcs status -e prod
    Projects to Deploy (1)

    APIs (1) ...
    1: [save]       Pizzashack-1.0.0: (Pizzashack-1.0.0)
    ```

- Выполните команду vcs deploy для развертывания нового API в производственной среде.

    ```bash
    $ apictl vcs deploy -e prod
    Deploying Projects (1)...

    APIs (1) ...
    1: Pizzashack-1.0.0: (Pizzashack-1.0.0)
    Successfully imported API.
    ```

Здесь apictl развернет только новый API Pizzashack-1.0.0 без повторного развертывания другого неизменного API SwaggerPetstore-1.0.0

Важно

Для развертывания API с помощью команды vcs deploy:

- Проекты API обязательно должны находиться в системе контроля версий на базе Git..

- Каталоги в репозитории Source должны иметь формат именования &lt;API\_Name&gt;-&lt;API\_Version&gt;.

- Каталоги в репозитории Deployment должны иметь формат именования DeploymentArtifacts\_&lt;API\_Name&gt;-&lt;API\_Version&gt;.

- Обязательно наличие файла api\_meta.yaml либо внутри проекта Soure API (он создается по умолчанию при экспорте API с помощью export api или инициализации проекта API с помощью init), либо внутри индивидуального репозитория развертывания (он создается при генерации индивидуального репозитория развертывания с помощью команды apictl gen deployment-dir).

- Во время развертывания vcs, если api\_meta.yaml находится и в исходном проекте API, и в индивидуальном репозитории развертывания, приоритет будет отдан файлу, находящемуся в индивидуальном репозитории развертывания.

- Для развертывания API используется следующий раздел конфигурации в файле api\_meta.yaml.

    ```yaml
    deploy:
        import:
            preserveProvider: true
            rotateRevision: false
            update: true
    ```

Вы можете изменить указанные выше поля соответствующим образом.

Поле	Описание
preserveProvider	Сохраните существующего поставщика API после его импорта
rotateRevision	При импорте (обновлении) API несколько раз, если достигнут максимальный лимит ревизий, удалить самую старую ревизию и создайте новую
update	Указывает, следует ли обновлять API, если он уже существует во время развертывания.

б) Продвижение одного API через CI/CD в продуктивные среды

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

Импортируйте API SwaggerPetstore в производственную среду и протестируйте его, выполнив следующую команду.

Пример

apictl import api -f path/to/Source/SwaggerPetstore-1.0.0 -e prod --preserve-provider=false --update=true --rotate-revision --params path/to/Deployment/DeploymentArtifacts_SwaggerPetstore-1.0.0

Примечание

- Если присутствует флаг –update, NEOMSA APIM попытается обновить существующую версию API с тем же именем и версией. Здесь текущая версия API (рабочая копия) будет обновлена. Тем временем, если вы указали информацию о средах целевых шлюзов развертывания (т.е., если файл deployment\_environments.yaml указан внутри исходного проекта, или если вы упомянули эти данные в файле параметров в репозитории развертывания), новая ревизия будет создана во время импорта Если количество ревизий для API достигает максимального значения (5) и присутствует флаг \`--rotate-revision\`, самая ранняя ревизия этого API будет удалена, и будет создана новая ревизия.

- Команда импорта подготавливает API Project для NEOMSA APIM , обрабатывая файл параметров. Она определяет, какую конфигурацию следует обработать для создания API Project, обнаруживая среду, которая использовалась для его импорта. Обратите внимание, что если вам не нужно перезаписывать параметры с помощью репозитория развертывания, нет необходимости указывать путь params к файлу.

- Команда apictl import-api была объявлена устаревшей начиная с версии apictl 4.0.0. Вместо этого используйте команду apictl import api, как показано выше.

Приведенная выше команда обнаружит целевую среду и предоставит ей API.

Войдите в систему NEOMSA API Publisher.

(например, https://localhost:9444/publisher)

Проверьте детали API.

Вы увидите, что API был импортирован с правильными данными, специфичными для определенной вами среды.

- Если вы выполнили шаги 1 , 2 , 3 , 5 , 6 и 7 , то вы увидите, что ваш API находится в состоянии PUBLISHED.

- Если вы выполнили шаги 1 , 4 , 5 , 6 и 7 , то вы увидите, что ваш API находится в состоянии CREATED.

Информация

При экспорте API инструмент apictl также экспортирует статус жизненного цикла API. При импорте в другую среду этот статус жизненного цикла будет сохранен. Это гарантирует, что API будет иметь одинаковое состояние во всех средах.
Например, если API находится в состоянии PUBLISHED в среде разработки, то он также будет в том же состоянии в среде тестирования. Это поведение по умолчанию можно изменить с помощью инструмента apictl, который назначает API состояние после CREATED импорта.

Получите ключи для API/API-Product¶

Следуйте инструкциям ниже, чтобы сгенерировать токен JWT/OAuth для тестирования с помощью apictl, чтобы вызвать API или продукт API , подписавшись на него с помощью нового приложения, созданного apictl.

Совет

Убедитесь, что NEOMSA APIM запущен и apictl настроен.
Вам следует войти в среду NEOMSA APIM .

Выполните любую из следующих команд apictl, чтобы получить ключи для API/API Product.

Команда

apictl get keys -n <API or API Product name> -v <API version> -r <API or API Product provider> -e <environment>
apictl get keys --name <API or API Product name> --version <API version> --provider <API or API Product provider> --environment <environment>

Пример

apictl get keys -n PizzaShackAPI -e dev

Пример

apictl get keys -n PizzaShackAPI -v 1.0.0 -e dev  -r admin -t https://localhost:9443/oauth2/token

Информация

- Требуется:<br>--environment или -e: Среда генерации ключей<br>--name или -n: API или API-продукт для генерации ключей

- Необязательно:<br>--token или -t: Новая конечная точка токена среды (это переопределяет ранее предоставленную конечную точку токена, которая была предоставлена с помощью команды add env)<br>--provider или -r: Поставщик API или продукта API<br>--version или -v: Версия API (в настоящее время продукты API не имеют версий)

Примечание

- Оба флага (--name( -n) и --environment(-e)) являются обязательными.

- Вы можете переопределить заданный эндпоинт токена или конечную точку токена по умолчанию, используя необязательный флаг --token(-t) вместе с новым эндпоинтом токена.

- Команда apictl get-keys устарела с API Controller 4.0.0 и далее. Вместо этого используйте, apictl get keys как показано выше.

Информация

После выполнения приведенной выше команды инструмент apictl создаст в среде приложение по умолчанию, подпишется на API и сгенерирует ключи на основе типа токена, определенного в файле <USER_HOME>/.wso2apictl/main-config.yaml файле.
С помощью инструмента apictl можно настроить и изменить тайм-аут HTTP-запроса и каталог экспорта.
При запуске вышеуказанной команды, если вы не указали --version (-v), инструмент по умолчанию будет считать версию 1.0.0. Если вы указали версию, то будет учитываться именно это значение.

Расширение конвейера CI/CD для поддержки продуктов API¶

Рассмотрим пример, когда в среде разработки (development) имеется API продукт под названием PetsInfo, который включает в себя подмножество операций API SwaggerPetstore.

Экспортируйте API продукт с помощью команды export api-product из среды разработки (dev

$ apictl export api-product -n PetsInfo -v 1.0.0 -e dev --latest

Successfully exported API Product!
Find the exported API Product at /home/wso2user/.wso2apictl/exported/api-products/dev/PetsInfo_1.0.0.zip

Извлеките экспортированный проект продукта API.
Аналогично API, выполните шаги из пункта 5, чтобы скопировать созданный проект в исходный репозиторий и при необходимости сгенерировать отдельный репозиторий развертывания.
Зафиксируйте все новые изменения в исходном и развертываемом репозиториях.
Выполните команду vcs status, чтобы увидеть доступные изменения, которые необходимо развернуть в производственной среде.

Пример

$ apictl vcs status -e prod
Projects to Deploy (1)

API Products (1) ...
1: [save]       PetsInfo-1.0.0: (PetsInfo-1.0.0)

Важно

Если вы не инициализировали репозиторий с помощью API Controller, вы получите следующую ошибку.

$ apictl vcs status -e prod
apictl: The repository info: vcs.yaml is not found in the repository root. If this is the first time you are using this repo, please initialize it with 'vcs init'.
Exit status 1

обязательно следуйте шагу 6 пункт 2 «Продвижение API в репозитории Git в продуктивные среды через CI/CD», чтобы инициализировать репозиторий.

Импортируйте продукт PetsInfo в производственную среду, выполнив следующую команду.

Пример

$ apictl vcs deploy -e prod
Deploying Projects (1)...

API Products (1) ...
1: PetsInfo-1.0.0: (PetsInfo-1.0.0)
Successfully imported API Product

Приведенная выше команда определит целевую среду и создаст продукт PetsInfo в целевой среде.

Важно

Для развертывания API используйте команду vcs deploy:

- Обязательно наличие ваших проектов API продукта в системе управления версиями на основе Git..

- Директории внутри репозитория исходного кода должны иметь формат именования &lt;API\_Product\_Name&gt;-&lt;API\_Product\_Version&gt; (поскольку у API продуктов нет версии, версия API продукта должна по умолчанию быть 1.0.0).

- Директории внутри репозитория развертывания должны иметь формат именования DeploymentArtifacts\_&lt;API\_Product\_Name&gt;-&lt;API\_Product\_Version&gt;.

- Обязательно наличие файла api\_product\_meta.yaml либо внутри проекта продукта API Soure (он создается по умолчанию при экспорте API с помощью export api product), либо внутри индивидуального репозитория развертывания (он создается при создании индивидуального репозитория развертывания с помощью команды apictl gen deployment-dir ).

- Во время развертывания vcs deploy, если файл api\_product\_meta.yaml находится как в проекте исходного API продукта, так и в отдельном репозитории развертывания, приоритет будет отдан файлу, находящемуся в отдельном репозитории развертывания.

- Следующий раздел конфигурации в файле api\_product\_meta.yaml используется для развертывания API-продукта.

    ```yaml
    deploy:
        import:
            importApis: true
            preserveProvider: true
            rotateRevision: false
            updateApiProduct: true
    ```

Вы можете изменить указанные выше поля соответствующим образом.

Поле	Описание
importApis	Импортировать зависимые API вместе с API продуктом, если зависимые API недоступны в целевой среде
preserveProvider	Сохранить существующего провайдера API продукта после его импорта
rotateRevision	При многократном импорте (обновлении) API продукта, если достигнут максимальный лимит ревизий, удалить старейшую ревизию и создать новую.
updateApiProduct	Используется для указания необходимости обновления API продукта, если он уже существует во время развертывания

Совет. Несколько проектов продуктов API можно продвигать с помощью CI/CD, помещая их в один и тот же репозиторий.

Расширение конвейера CI/CD для поддержки приложений¶

Предположим, что приложение PetsApp находится в среде разработки (dev) и уже подписано на API SwaggerPetstore.

Экспортируйте приложение с помощью команды export app из среды разработки (dev). Обратите внимание, что эта опция --with-keys используется для экспорта подписок и ключей (если таковые имеются) приложения.
```
$ apictl export app --name PetsApp --owner david -e dev --with-keys

Successfully exported Application!
Find the exported Application at /home/wso2user/.wso2apictl/exported/apps/dev/david_PetsApp.zip
```

Примечание. Команда apictl export-app устарела с версии API Controller 4.0.0. Вместо этого используйте apictl export app, как показано выше.

Извлеките экспортированный проект приложения.
Зафиксируйте проект в том же репозитории git.
Выполните команду vcs status, чтобы увидеть доступные изменения, которые необходимо развернуть в производственной среде.

Пример

$ apictl vcs status -e prod
Projects to Deploy (1)

Applications (1) ...
1: [save]       PetsApp: (PetsApp)

Важно. Если вы не инициализировали репозиторий с помощью API Controller, вы получите следующую ошибку.

$ apictl vcs status -e prod
apictl: The repository info: vcs.yaml is not found in the repository root. If this is the first time you are using this repo, please initialize it with 'vcs init'.
Exit status 1

обязательно следуйте шагу 6 пункт 2 «Продвижение API в репозитории Git в продуктивные среды через CI/CD», чтобы инициализировать репозиторий.

Импортируйте приложение PetsApp в производственную среду, выполнив следующий команду.

Пример

$ apictl vcs deploy -e prod
Deploying Projects (1)...

Applications (1) ...
1: PetsApp: (PetsApp)
Successfully imported Application

Приведенная выше команда обнаружит целевую среду и создаст приложение в целевой среде.

Важно

Для развертывания приложения используйте команду vcs deploy:

- Обязательно наличие ваших проектов приложений в системе управления версиями на основе Git.

- Обязательно наличие файла application\_params.yaml внутри каждого проекта приложения. Этот файл создается по умолчанию при экспорте приложения с помощью команды export app. Следующий раздел конфигурации в файле application\_params.yaml используется для развертывания приложения.

    ```yaml
    deploy:
        import:
            update: true
            preserveOwner: true
            skipSubscriptions: false
            skipKeys: true
    ```

Вы можете изменить указанные выше поля соответствующим образом.

Поле	Описание
update	Используется для указания необходимости обновления приложения, если оно уже существует во время развертывания.
preserveOwner	Сохранить существующего владельца приложения после его импорта
skipSubscriptions	Указывает, следует ли импортировать подписки приложения.
skipKeys	Указывает, следует ли импортировать учетные данные приложения.

Совет. Несколько приложений можно продвигать с помощью CI/CD, помещая проекты этих приложений в один и тот же репозиторий.

Теперь вы знаете основные элементы создания CI/CD пайплайна с использованием apictl. Используя вышеописанное, вы можете создать автоматизированный пайплайн для продвижения API между средами, используя один из упомянутых подходов.

Создание конвейера CI/CD для API с использованием Jenkins¶

В современной цифровой эпохе многие организации внедряют технологии цифровой трансформации, чтобы не отставать от изменений. API являются одним из основных строительных блоков, используемых в организациях, ориентированных на цифровые технологии. Когда количество API, управляемых организацией, увеличивается, необходимо иметь автоматизированный процесс для обработки быстрого процесса разработки API. Наличие правильного процесса непрерывной интеграции и непрерывного развертывания (CI/CD) дает вашей организации дополнительное преимущество

В этом разделе вы узнаете, как настроить автоматизированный процесс с использованием NEOMSA API Controller (apictl) с NEOMSA API Manager (NEOMSA APIM ). Вы увидите, как решение создается с использованием системы контроля версий (Github), репозитория артефактов (JFrog Artifactory) и инструмента CI/CD (Jenkins).

Настройка среды¶

Настройка Jenkins¶

Прежде чем начать, вам необходимо установить сервер Jenkins на удаленной машине с публичным доступом. Для использования вебхуков в Github и репозитории Artifactory для запуска задач Jenkins вам нужен URL-адрес сервера Jenkins, доступный из интернета. Если вы пытаетесь сделать это на локальной машине, вам может понадобиться использовать такие инструменты, как socketxp, для создания туннеля.

В этом разделе инструкции проверены на сервере Ubuntu, настроенном по адресу https://cloud.google.com/compute .

Войдите на сервер и установите следующее.

Установите jq с помощью команды, указанной ниже.
```
sudo apt-get install jq
```
Установите apictl tool. Извлеките в место, которое далее будет называться CTL_HOME.
Установить Java.
Настройте сервер Jenkins, следуя инструкциям, приведенным здесь . Вы можете выбрать установку предлагаемых плагинов по умолчанию. Это установит часто используемые плагины.

Зарегистрируйте вебхук в репозитории JForg Artifact для уведомления об изменениях. Чтобы перехватывать эти события и запускать Jenkins, установите плагин generic-webhook-trigger.

Настройте apictl home как переменную среды. Перейдите в раздел Manage Jenkins и выберите Configure System.

В разделе «Global properties» выберите «Environment variables», задайте домашнюю папку APICTL, как показано ниже, и нажмите «Save».

Теперь сервер Jenkins настроен.

Создание репозиториев Github¶

В этом разделе создадим два репозитория, чтобы проиллюстрировать этот сценарий.

Исходный Репозиторий -https://github.com/chamilaadhi/poc-cicd-source-repo
Репозиторий развертывания -https://github.com/chamilaadhi/poc-cicd-deployment-repo

Исходный репозиторий содержит файлы и метаданные, связанные с API. Репозиторий развертывания содержит конфигурации, связанные с каждой средой, в которой развертывается этот API.

Настройка исходного репозитория¶

В этом разделе показано, как запустить Jenkins при внесении изменений в репозиторий. Давайте используем веб-хуки Github для запуска задания Jenkins.

Перейдите в исходный репозиторий и в разделе «Settings » выберите «Webhooks» и добавьте веб-хук на сервер Jenkins.

В качестве URL-адреса используйте URL-адрес вашего сервера Jenkins (например, http://<public_ip>:8080/github-webhook/), а в качестве Content type — application/json.
В разделе Which events would you like to trigger this webhook? выберите Let me select individual events, а затем выберите pull request и pushes.

Исходный репозиторий теперь настроен.

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

Примечание. Если вы еще не настроили API Controller, настройте его с помощью инструмента apictl.

Клонируйте исходный репозиторий. Перейдите в папку репозитория.
```
$ git clone https://github.com/chamilaadhi/poc-cicd-source-repo.git
$ cd poc-cicd-source-repo
```

Выполните следующую команду.

$ apictl vcs init

Это создаст файл vcs.yaml в репозитории. Зафиксируйте его в исходном репозитории.Теперь исходный репозиторий настроен.

Настройка репозитория развертывания¶

Репозиторий развертывания будет использоваться для сбора конфигураций для каждого развертывания. Чтобы отделить конфигурацию, мы будем использовать ветки git. Создайте ветку с именем 'dev', чтобы сохранить конфигурацию, связанную со средой разработки.

Настройка JFrog Artifactory¶

Прежде чем начать. Создайте бесплатный облачный репозиторий с помощью https://jfrog.com/start-free/#saas. После завершения регистрации войдите в систему https://<name>.jfrog.io/ui/

Создайте пользователя для загрузки артефактов. Войдите с учетными данными администратора, перейдите в раздел Identity and Access → Users и создайте пользователя. В этом сценарии выбраны все роли.

Сделайте репозиторий общедоступным. Перейдите в Security → Settings и выберите Allow Anonymous Access

Создайте репозиторий для загрузки артефактов. Перейдите в раздел Repositories и выберите Add Repositories. Выберите Тип Generic и введите имя (например, myrepo).

После сохранения вы сможете получить доступ https://<your_org>.jfrog.io/artifactory/<repo_name>/.

Попробуйте загрузить образец ресурса. Пример приведен ниже.

$ touch resource.txt
$ curl -u repouser:<password> -X PUT https://xxxx.jfrog.io/artifactory/myrepo/ -T resource.txt

Чтобы увидеть ресурс, перейдите по URL-адресу репозитория.

Настройте веб-хук для запуска задания Jenkins.

Создайте вебхук для запуска задания Jenkins при загрузке нового ресурса в репозиторий. Перейдите в раздел General → Webhooks и создайте новый.

URL-адрес -http://<jenkins_host>:8080/generic-webhook-trigger/invoke?token=123**

Добавьте Event set поскольку Artifact was deployed.

В открывшемся новом окне выберите репозиторий.

Настройка экземпляров API-M¶

Загрузите NEOMSA APIM 4.6.0 и запустите экземпляр. Установите это в отдельном экземпляре как dev экземпляр.

Настройка заданий Jenkins¶

Настройка глобальных переменных¶

Как показано в разделе «Setup Jenkins», перейдите в раздел «Manage Jenkins» и выберите «Configure System». В разделе «Global properties» выберите «Environment variables» и задайте следующие переменные с данными, связанными с вашей средой.

Переменная	Описание
APIM_DEV_HOST	IP или имя хоста экземпляра dev (например, apim-dev.example.local)
APIM_PROD_HOST	IP или имя хоста экземпляра prod (например, apim-prod.example.local)
ARTIFACTORY_HOST	Имя хоста Artifactory (например: testrepo.jfrog.io)
ARTIFACTORY_PWD	Пароль пользователя загрузки артефакта
ARTIFACTORY_REPO	Имя репозитория (например: myrepo)
ARTIFACTORY_USER	Имя пользователя, загружающего артефакт

Настройка задания по сборке и загрузке артефакта¶

Создайте проект Jenkins Pipeline.

Используйте этот скрипт для пайплайна.

Примечание. URL-адрес рабочей области сервера Jenkins по умолчанию — /var/lib/jenkins/workspace/. Если вы установили сервер Jenkins в другом месте, измените этот путь в скрипте соответствующим образом.

В разделе «Build Triggers» установите триггер GitHub для GITScm polling.
Сохраните конфигурацию. Теперь задание Jenkins настроено на прослушивание любых изменений в исходном репозитории и загрузку любых новых обновлений в репозиторий артефактов.

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

Настройка задания по развертыванию артефакта¶

Задание по развертыванию артефакта будет прослушивать все новые обновления в репозитории Artifactory и развертывать артефакт с конфигурациями в репозитории git Deployment в dev среде APIM.

Создайте пайплайн Jenkins с помощью этого скрипта.
Сохраните скрипт и выполните сборку для настройки. Обратите внимание, что это задание также завершится неудачей.

Чтобы проверить, работает ли веб-хук между Artifactory и заданием Jenkins, вы можете выполнить тот же тест загрузки, который мы выполняли в разделе «Настройка JFrog Artifactory».
```
$ touch resource.txt
$ curl -u repouser:<password> -X PUT https://xxxxx.jfrog.io/artifactory/myrepo/ -T resource.txt
```

Если конфигурация работает, это запустит новую сборку.

Тестовые сценарии

Чтобы протестировать эту настройку, используйте метод создания API на основе определений OpenAPI.

Создать API с помощью определения OAS. Это создаст проект с именем PetstoreAPI . Пример команды приведен ниже.
```
$apictl init PetstoreAPI --oas https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/yaml/petstore.yaml
```

Создайте ресурс развертывания с помощью команды, указанной ниже.

$apictl gen deployment-dir --source /Path/To/PetstoreAPI --destination <deployment_repo_path>/poc-cicd-deployment-repo

Вы увидите ресурсы, созданные со следующей структурой.

├── DeploymentArtifacts_SwaggerPetstore-1.0.0
│   ├── api_meta.yaml
│   ├── certificates
│   └── params.yaml

Откройте файл params.yaml и обновите его содержимое, используя код, указанный ниже.

environments:
  - name: dev
    configs:
      endpoints:
          production:
              url: 'https://petstore.swagger.io/v2/'
      deploymentEnvironments:
          - displayOnDevportal: true
            deploymentEnvironment: Default
            deploymentVhost : localhost

Имя среды установлено как dev. Эта конфигурация будет использоваться для среды dev.

Зафиксируйте это в dev-ветке в репозитории развертывания.
Скопируйте папку PetstoreAPI в git исходного репозитория.
Создайте файл с именем meta.yaml внутри папки PetstoreAPI и добавьте версию, аналогичную следующей.
```
version: 1.0.0
```

Эта версия используется для развертывания пакета, созданного с помощью API PetstoreAPI в репозитории Artifactory.

Ниже представлено содержимое PetstoreAPI. Зафиксируйте все файлы в репозитории git

├── PetstoreAPI
│   ├── Definitions
│   │   └── swagger.yaml
│   ├── README.md
│   ├── api.yaml
│   ├── api_meta.yaml
│   ├── deployment_environments.yaml
│   └── meta.yaml

При фиксации в исходном репозитории сначала сработает CICD_ARTIFACT_UPLOAD и загрузит собранный компонент в Artifactory. Это отображается в журнале консоли задания Jenkins.

Как только пакет будет загружен в репозиторий Artifactory, сработает задание Jenkins по развертыванию. Развертывание пакета в API-M отображается в логах.

Войдите в API Manager, и вы увидите, что API создан.

Давайте обновим API и посмотрим изменения. API находится в состоянии CREATED. Давайте опубликуем этот API, выполнив шаги, указанные ниже.

Откройте файл PetstoreAPI/api.yaml и измените lifeCycleStatus на PUBLISHED.
Откройте файл PetstoreAPI/meta.yaml и измените версию на какое-то новое значение (например, 1.0.1).

Закоммитите оба файла.

После того, как вы закоммитите изменения в исходном репозитории, вы увидите, как запускаются задания jenkins. Войдите в портал издателя и проверьте изменения.

Если вы зайдете в репозиторий artifactory и проверите PetstoreAPI, вы увидите в репозитории две версии.