Материал подготовлен в соавторстве с пользователем wedmeed
В 2017 году, когда начинался наш проект во Вьетнаме, мы столкнулись с новым для нас зверем IBM DataPower. IBM DataPower – продукт, представляющий собой gateway между клиентами и бэкендами, предназначенный для фильтрации, маршрутизации, обогащения или других преобразований проходящих через него сообщений (далее – запросов). Обучаться нужно было быстро, времени на раскачку не было, поэтому нам было предложено самостоятельно ознакомиться с ним, после чего были многочасовые конференции по скайпу с нашим коллегой из Москвы, который передавал нам свои знания и опыт работы с этим продуктом.
Самостоятельное обучение основывалось на изучении документации и просмотре обучающих видео из интернета – и тут меня ждал подвох. Мне практически не удалось найти информации на русском языке. К слову, мои знания английского языка на тот момент были не на высшем уровне, к тому же это был мой первый проект и, наверное, именно эти факторы усложнили мне жизнь. Это сподвигло меня написать обучающую статью на русском языке и в максимально простом изложении для начинающих разработчиков, которые столкнулись с этим продуктом и пытаются оперативно понять его азы. Статья не освободит вас от чтения документации, но облегчит жизнь на первых этапах понимания «как это работает».
Стоит также заметить, что приведенная в практике структура будет приближена к реальному проекту, что позволит вам использовать ее как базу, расширяя и дополняя под ваши требования. В заключение к разделам «Теория» будет приведено несколько слов об уже реализованном проекте, а также некоторые особенности, на которые стоит обратить внимание.
Часть 1. Установка DataPower средствами Docker Toolbox
Установите и запустите приложение Docker Toolbox. Сразу после запуска вы увидите IP адрес машины, по которому в дальнейшем будет доступен DataPower:
Для запуска образа необходимо изменить некоторые настройки виртуальной машины (актуально для версии IDG.2018.4.1.0) и перезапустить ее:
- Останавливаем докер-машину командой:
docker-machine stop
- Система -> Материнская плата -> Основная память: минимум 4096Mb;
- Система -> Процессор: минимум 2;
- Дисплей -> Экран -> Видеопамять: минимум 128Mb;
- Запускаем докер-машину командой:
docker-machine start
Примечание. Если будет предложено перезапустить «docker-machine env» — выполните:
docker-machine env
- Далее необходимо выкачать образ IBM DataPower:
docker pull ibmcom/datapower
- После чего запустить докер-контейнер следующей командой:
docker run -it -v $PWD/config:/drouter/config -v $PWD/local:/drouter/local -e DATAPOWER_ACCEPT_LICENSE=true -e DATAPOWER_INTERACTIVE=true -p 9090:9090 -p 3630:3630 -p 9022:22 -p 7170:7170 --name idg ibmcom/datapower
- После окончания выполнения команд нажмите Enter и введите в качестве логина и пароля admin/admin
- Для запуска Web Management Interface используйте команды:
co
и
web-mgmt 0 9090
- После всех указанных действий выполните в браузере https://192.168.99.100:9090/
Часть 2. Домены
2.1. Теория
Домены в DataPower позволяют разделить средства администрирования и разработки, а также обеспечить безопасность.
После установки существует только домен default, из которого могут быть созданы домены приложений. Для каждого домена существует своя конфигурация параметров.
Некоторые общие ресурсы и параметры можно определить только в default домене, к ним относятся сетевые интерфейсы, пользователи и управление доступом, домены приложений и другие.
Домен приложений – это раздел разработки для служб, обрабатывающих запросы. Службы, определенные в нём, не могу быть общими с другим доменом приложений. Домены приложений могут перезапускаться отдельно и независимо друг от друга, без необходимости полного перезапуска DataPower.
Вы можете создавать, перезапускать, сбрасывать, приостанавливать, возобновлять или удалять домены. Более подробную информацию обо всех возможностях администрирования вы можете найти в официальной документации.
Немного о реализованном проекте. Мы использовали 3 домена:
- default – домен по умолчанию, содержащий общие ресурсы и параметры;
- trunk – основной домен, содержащий все необходимое для обработки запросов;
- settings – домен настроек и безопасности, в локальных файлах содержится информация о правилах маршрутизации сервисов и параметрах безопасности.
Необходимость перенести все настройки в отдельный домен возникла в связи с поиском более простого пути развертывания. Как и во многих проектах среды dev, test и prod у нас были разделены, а вынос в отдельный домен настроек позволил устанавливать все основные домены из dev среды в других средах посредством экспорта/импорта, без риска потерять настройки среды.
2.2. Практика
- В поле поиска введите «domain», выберите «Application Domain» и нажмите «Добавить»
- Здесь вам необходимо указать название домена, комментарий (при желании) и активировать auditing и logging. Заполните поля и примените изменения
- Аналогично добавьте еще один домен «trunk»
- Перейдите в Review changes
- и сохраните конфигурацию домена
- Проверить состояние созданных объектов вы можете, перейдя в default домене по дереву навигации в Status -> Main -> Object Status
- Выберите View by: types
- Найдите в списке Application Domain и проверьте состояние объектов: каждый из них должен быть сохранен, включен и в состоянии up. Если всё так – переходите к следующей главе
Часть 3. Менеджеры очередей
Менеджер очередей не является обязательным компонентом IBM DataPower, но именно на примере с MQ можно показать всю мощь этого продукта. MQ будем использовать от компании IBM. Во время тестирования, описанного в 6 главе, нам будет необходимо отправлять сообщение в локальный менеджер очередей. В данной статье я сделаю это с помощью утилиты rfhutil, но вы можете использовать любой доступный вам способ. Для тестирования необходимо будет создать коннект из DP к вашему локальному менеджеру очередей с помощью MQ Queue Manager.
3.1. Теория
Менеджер очередей обеспечивает обмен данными между шлюзом и удаленными администраторами очередей.
Вы также можете настроить MQ Queue Manager Group, что позволит повысить отказоустойчивость системы. Это может быть полезно, например, если вы хотите подключать клиента к любому из набора работающих администраторов очередей и еще в ряде случаев, с которыми вы можете ознакомиться в официальной документации.
Из опыта проекта стоит отметить только одну особенность: в свое время мы хотели попробовать реализовать балансировку нагрузки средствами DataPower, в частности, с использованием групп менеджеров очередей, но на практике не обнаружили такой возможности. Альтернативное решение – создание кластера менеджеров очередей.
3.2. Практика
3.2.1. Подготовка
- Установите WebSphere MQ;
- Создайте локальный менеджер очередей LOCAL_DP_QM, доступный по порту 3630;
- Настройте канал DP.SVRCONN;
При создании канала вам могут быть полезны следующие команды:
strmqm LOCAL_DP_QM /*запуск менеджера mq*/ runmqsc LOCAL_DP_QM /*вход в оболочку mq*/ DEFINE CHANNEL (DP.SVRCONN) CHLTYPE(SVRCONN) MCAUSER(‘evlasenko’) /*создание канала*/ SET CHLAUTH(‘DP.SVRCONN’) TYPE(USERMAP) CLNTUSER(‘evlasenko’) USERSRC(channel) ADDRESS(‘*’) ACTION(ADD) /*включение доступа для пользователя со стороны клиента*/ SET CHLAUTH(DP.SVRCONN) TYPE(BLOCKUSER) USERLIST(‘nobody’) /*отключить список блокировки пользователей*/ ALTER LISTENER (SYSTEM.DEFAULT.LISTENER.TCP) TRPTYPE(TCP) PORT(3630) control(QMGR) /*включение автозапуска листенера порт 3630*/ ALTER AUTHINFO (SYSTEM.DEFAULT.AUTHINFO.IDPWOS) AUTHTYPE(IDPWOS) CHCKCLNT(OPTIONAL) /*выключить аутентификацию*/ REFRESH SECURITY TYPE(CONNAUTH) /*обновить настрйоки безопасности*/ endmqm LOCAL_DP_QM /*остановка менеджера mq*/ strmqm LOCAL_DP_QM /*запуск менеджера mq*/ END
- Создайте очереди DP.IIB.REQIN и DP.IIB.RESIN
- Запустите rfhutil под именем пользователя, для которого создавали канал. В строке Queue Manager Name (to connect to) пропишите:
DP.SVRCONN/TCT/127.0.0.1(3630)
- Попытайтесь загрузить список названий очередей, в окне сообщений не должно быть каких-либо ошибок. Проверка соединения с каналом пройдена.
3.2.2. Создание IBM MQ Queue Manager
- Перейдите в домен trunk.
- В поиске наберите MQ, выберите IBM MQ Queue Manager и нажмите добавить.
- Вам необходимо указать название(TEST_QM), хостнейм менеджера очередей, имя менеджера очередей и имя канала, а также таймаут. Выполните настройку и сохраните изменения.
Проверьте состояние объекта менеджера очередей аналогично проверке статуса доменов. Для этого из домена trunk выберите Object Status и фильтр View by: types. В разделе «IBM MQ Queue Manager» отыщите соответствующий объект и проверьте его состояние.
Часть 4. Многопротокольные шлюзы
4.1. Теория
Multi-Protocol Gateway (MPG) – многопротокольный шлюз, позволяющий принимать запросы от клиентов по различным протоколам, а затем по различным протоколам передавать их на удаленный сервер. Протокол, используемый клиентом может не совпадать с протоколом, используемым сервером удаленного доступа.
В основных настройках MPG вы можете определить следующие компоненты:
- XML Manager – управляет компиляцией и кэшированием таблиц стилей(xsl,xslt), кэшированием документов.
- Policy – состоит из правил, каждое из которых определяет набор действий, применяемых к сообщению, проходящему через шлюз.
- Настройки front и back side (настройка url, типов входящего и исходящего сообщений, таймаутов и другого).
Пара слов о проекте:
В реализации проекта используется 4 многопротокольных шлюза (маршрутизирующий, 2 трансформационных для разных конечных систем и дополнительный, предназначенный для получения файлов из домена settings). На схеме ниже представлена общая схема взаимодействия:
Количество MPG может варьироваться в зависимости от архитектуры решения в целом. В нашем случае DataPower стоит перед интеграционной шиной (IIB) и микросервисами, которые имеют существенные различия в интерфейсах(json/http против xml/mq), поэтому трансформационные MPG было решено делать под каждый специфический бэкенд и называть его соответствующе. Для всех клиентов мы работаем по json/http, поэтому маршрутизирующий MPG – один. Основные MPG состоят из 3 правил обработки сообщений – запроса, ответа и ошибок. Каждое правило состоит из необходимых действий, таких как transformation, logging, routing и прочие.
Из особенностей – если в policy вы используете действие ConvertQueryParamToXML, то будьте внимательны к InputConversion. Если вы зададите Default Encoding значение JSON и попытаетесь отправить GET-запрос, то будете удивлены, обнаружив, что сообщение не претерпело никаких трансформаций, указанных вами и не обнаружите никаких его следов. Данную особенность поможет преодолеть создание отдельного правила для GET-запросов.
4.2. Практика
4.2.1. Подготовка
Все необходимые для работы файлы вы можете найти по ссылке https://github.com/EvgenyaVlasenko/IBM_DataPower.git
4.2.1.1. Домен trunk
- Перейдите в домен trunk.
- На панели управления выберите File Management.
- В каталоге local создайте следующую структуру каталогов и поместите в нее соответствующие файлы (в каждом файле содержится краткое описание того, какие функции он выполняет, а также более подробно остановимся на этом далее в статье).
4.2.1.2. Домен settings
- Перейдите в домен settings.
- На панели управления выберите File Management.
- В каталоге local создайте следующую структуру каталогов и поместите в нее соответствующие файлы (внутри файлов также содержится их краткое описание).
4.2.2. Создание GetFileMPG
Для начала создадим простой вспомогательный MPG, который будет возвращать файлы из домена settings.
- Перейдите в домен settings.
- На панели управления выберите Multi-Protocol Gateway и нажмите создать.
- Укажите имя (GetFileMPG), описание(по желанию) и тип бэкенда (dynamic). На самом деле, так как вызова бэкенда фактически не будет, а будет только возвращаться файл из локальной системы, то в данном примере тип бэкенда можно указать любой.
- Задайте типы запроса и ответа. Явное указание типов позволит сократить количество встроенных проверок. Указание типа Pass through позволит не создавать правило (в данном случае для трансформации ответа). В случае, если мы укажем Request Type тоже Pass through, то не сможем никак обработать сообщение. Этот вариант нам не подходит, поэтому ограничиваем тип запроса с помощью Non-XML.
- Нажмите на + и выберите HTTP Handler для создания нового Front Side Protocol.
- Здесь вам следует указать имя, ip-адрес, порт и список разрешенных методов. Следует обратить внимание на ip-адрес. Если указать 0.0.0.0, то обращаться к этому шлюзу могут все. Если 127.0.0.1 – только другие шлюзы внутри этого же DataPower. Так как среди настроек есть параметры безопасности, то используем именно второй вариант. Заполните поля и нажмите «Применить», протокол автоматически добавится в шлюз.
- Нажмите на + для добавления новой политики.
- Заполните имя политики «GetFilePolicy».
- Создайте новое правило, заполните имя и направление правила. Так как бэкенда на самом деле нет, а лишь возвращается нужный файл, то правило будет только одно (client to server).
- Дважды щелкните по Match действию для его настройки, выберите существующее правило и примените изменения. Идеологически правильным здесь было бы установить ограничение для возможности получать только Get-запросы, но в рамках обучающей задачи можно выбрать существующее.
- Добавьте еще одно действие – GatewayScript, перетащив его на правило, и настройте его. В качестве трансформации будет использован подготовленный файл, который в файловой системе local:/// будет находить файл по имени из URI входящего запроса и помещать его в тело сообщения. Результат операции будет передаваться напрямую в выходной буфер правила. Сохраните изменения.
- Окончательный результат политики должен выглядеть следующим образом:
- Создание MPG завершено, сохраните изменения.
- Вы можете проверить успешность его создания с помощью Object Status, аналогично проверке статуса доменов и менеджера очередей. Для этого из домена settings выберите Object Status и фильтр View by: services. В разделе «Multi-Protocol Gateway» отыщите соответствующий объект и проверьте его состояние.
- Вы не сможете вызвать этот MPG извне, так как защитили его с помощью ip. Временно измените ip с 127.0.0.1 на 0.0.0.0 и порт с 7171 на 7170 и выполните следующий запрос:
curl -vv -k "http://192.168.99.100:7170/trunk/route/routeRules.xml"
- Вы должны получить следующий ответ:
- Снова измените ip и порт на исходные 127.0.0.1:7171.
4.2.3. Создание RoutingMPG
Теперь создадим RoutingMPG. На основании входного запроса и правил маршрутизации он определит, куда и с какими параметрами следует отправить запрос.
- Перейдите в домен trunk.
- Создайте новый Multi-Protocol Gateway в соответствии с пунктами 2-10 раздела 4.2.2, используя следующие значения:
- 3 – имя: RoutingMPG, тип бэкенда: Dynamic (для возможности маршрутизации запросов в разные MPG при необходимости).
- 4 – Rq: Non-xml, Rs: Non-xml.
- 6 – имя: RoutingHTTP_FSH, ip: 0.0.0.0, порт: 7170, + Get method.
- 8 – имя: RoutingPolicy.
- 9 – имя: RoutingPolicy_rule_req, направление: Client to Server.
- Добавьте еще одно действие для маршрутизации запроса, для этого перетащите на правило действие «Route», дважды щелкните на нем для настройки, заполните поля и примените изменения. Файл route.xsl получает файл настроек роутинга из домена settings через созданный ранее GetFileMPG. После этого на основании URI выделяются из файла уже те настройки, которые необходимы для данной операции. Часть из них используется для маршрутизации, а часть добавляется в хедеры для использования в других MPG. Параметры input и output определяют способ работы только с телом сообщения и никак не влияют на хедеры и переменные. Поэтому: вход из null – так как для роутинга не используется информация из тела сообщения. Вывод в null – так как результатом трансформации является только изменение служебной информации.
- Аналогично создайте еще 2 правила и сохраните все изменения:
- Направление: Сервер-клиент, имя: RoutingPolicy_rule_resp;
Трансформация: Input INPUT, Output NULL, файл трансформации local:///RoutingMPG/transform/resp.xslt. Файл resp.xslt получает http-статус ответа трансформационного MPG и в явном виде устанавливает его в ответ RoutingMPG. Если этого не сделать, то по умолчанию будет выставлен код 200, даже если в трансформационном MPG возникла ошибка.
- Направление: Error, имя: RoutingPolicy_rule_error;
Трансформация: Input INPUT, Output PIPE(согласно документации, использование PIPE между двумя смежными узлами действий в качестве INPUT и OUTPUT способно устранить дополнительную обработку и снизить объём используемой памяти), файл трансформации local:///RoutingMPG/transform/errors.xsl. Файл errors.xsl получает код и текст ошибки из ответа от трансформационного MPG и формирует JSON-сообщение об ошибке в ожидаемом клиентом формате.
- Направление: Сервер-клиент, имя: RoutingPolicy_rule_resp;
- Окончательный результат политики должен выглядеть следующим образом:
- Создание MPG завершено, сохраните изменения.
- Воспользовавшись, например, утилитой curl выполните следующий запрос:
curl -vv -k "http://192.168.99.100:7170/dp/test/transformMessage"
- Если вы получили следующую ошибку, то всё выполнено верно. Данная ошибка означает, что сообщение успешно получено и обработано, но попытка вызвать бэкенд (в данном случае IIBMPG) была неуспешной. Переходим к следующему шагу.
4.2.4. Создание IIBMPG
Следующий шаг – создание трансформационного MPG. Предположим, внешняя система имеет формат запроса JSON, а внутренняя — XML. Нам необходимо преобразовать входное сообщение так, чтобы его смогла понять внутренняя система. Стоит заметить, что это не всегда простое преобразование сообщения целиком. Часто требуется передать усеченное или дополненное сообщение, иногда с полностью переработанной структурой.
- Перейдите в домен trunk.
- Создайте новый Multi-Protocol Gateway в соответствии с пунктами 2-10 раздела 4.2.2, используя следующие значения:
- 3 – имя: IIBMPG, тип бэкенда: Dynamic
- 4 – Rq: JSON, Rs: XML
- 6 – имя: IIBHTTP_FSH, ip: 127.0.0.1(только запросы с этого же DataPower), порт: 7172, + Get method
- 8 – имя: IIBPolicy
- 9 – имя: IIBPolicy_rule_req, направление: Client to Server
- Добавьте описание. Файл IIBRuleRoute.xsl на основании X-DP-Transform-Name в headers запроса получает из файла local:///IIB/route/IIBRouteRules.xml названия файлов трансформации запроса, ответа и ошибки для этого сервиса и устанавливает их значения в соответствующие контекстные переменные var://context/IIB/reqTransform, var://context/IIB/ansTransform, var://context/IIB/errTransform. Также в контекстные переменные помещаются другие значения из headers(url,uri,expire,timeout).
- Добавьте еще одно действие, перетащив Advanced на ваше правило и, выбрав из списка Convert Query Params to XML, выполните настройку. Вам необходимо добавить новый input conversion map, задав ему имя (cmnJSONParseCNVM) и необходимый тип (JSON).
- Добавьте трансформацию после стандартной конвертации и выполните ее настройку. Для указания файла трансформации в данном случае используется переменная, установленная в предыдущем преобразовании. Это сделано для того, чтобы трансформация была универсальной, и сам файл подставлялся «на лету» в зависимости от входного сообщения. Тело сообщения готово. Следующим действием нам понадобится маршрутизировать сообщение, при этом тело сообщения меняться не будет, поэтому создаем переменную dpvar_1 и сохраняем результат в нее. Именно эту переменную укажем на вход действию Results. Сохраните изменения.
- Добавьте действие маршрутизации и установите следующие параметры. Файл IIBURLRoute.xsl получает значения контекстных переменных, часть из них устанавливает в качестве сервисных переменных запроса, а из остальных формирует URI для запроса в конечную систему, который также сохраняет в сервисную переменную.
- Аналогично создайте еще 2 правила и сохраните все изменения:
- Направление: Сервер-клиент, имя: IIBPolicy_rule_resp;
Трансформация: Input INPUT, Output PIPE, файл трансформации var://context/IIB/ansTransform(контекстная переменная для подстановки трансформации респонса «на лету»). - Направление: Error, имя: IIBPolicy_rule_error;
Трансформация: Input NULL, Output PIPE, файл трансформации var://context/IIB/errTransform(контекстная переменная для подстановки трансформации ошибки «на лету»).
- Направление: Сервер-клиент, имя: IIBPolicy_rule_resp;
- Окончательный результат политики должен выглядеть следующим образом:
- Создание MPG завершено, сохраните изменения.
Часть 5. Тестирование
5.1. Подготовка
- Скачайте, например, утилиту rfhutil для чтения и записи сообщений в очередь;
- Тестовые файлы находятся в папке tests той же директории, что и файлы проекта.
5.2. Проверка работоспособности
- Отправьте запрос помощью утилиты curl (для запроса ниже текущая директория должна быть той же, где лежит example.json).
curl -vv -k "http://192.168.99.100:7170/dp/test/transformMessage" -H "Content-Type: application/json" --data-binary @example.json
- Откройте 2 экземпляра утилиты rfhutil и вычитайте сообщение из очереди DP.IIB.REQIN первым экземпляром;
- Перейдите на вкладку MQMD и скопируйте MessageID;
- Во втором экземпляре откройте файл rs.xml, во вкладке MQMD вставьте идентификатор сообщения в CorrelID и положите сообщение в очередь DP.IIB.RESIN;
- Вы должны получить подобный ответ:
- Повторите шаги 1-3;
- Во втором экземпляре откройте файл rs_error.xml и отправьте сообщение в очередь заполнив correllId;
- Ответ изменится следующим образом
Часть 6. Логирование
6.1. Теория
Log Targets фиксируют различные сообщения, происходящие в системе и сохраняют их в указанном виде.
На проекте мы создали Log Targets для каждого шлюза отдельно. Логи хранятся в текстовом виде, для каждого шлюза отведено по 4 файла для логов объемом 1000Kb, при превышении лимита файлы перезаписываются циклически. При средней активности с такими параметрами информацию о запросе можно извлечь в течение 2-4 дней после его выполнения. В идеале лучше сделать внешние сборщики логов, так как при малейшем повышении нагрузки все перезапишется. Помимо этого, DataPower, как минимум, виртуальный, имеет тенденцию умирать, когда у него закончится место на жестком диске, что можно заметить далеко не сразу, а только когда заполнятся логи какого-нибудь тихого MPG, про который все давно забыли.
6.2. Практика
- Перейдите в домен trunk;
- В поиске наберите Log Target и нажмите добавить;
- На главной вкладке заполните следующие поля:
- Название(IIB_LOG);
- Тип(File);
- Формат (Text);
- Формат timestamp(zulu);
- Имя файла (logtemp:///IIB.log — для IIBMPG);
- Размер файла(1000).
- Добавьте фильтр объектов. В нашем случае мы хотим следить за MPG с именем IIBMPG.
- Добавьте подписку на события, указав категорию и приоритет событий, которые необходимо залогировать (приоритет событий указывает, что будут залогированы события данного приоритета и выше).
- Другие параметры могут быть оставлены в значениях по умолчанию;
- Сохраните конфигурацию всего домена;
- Для просмотра логов откройте указанный вами файл в файловом менеджере.
- По аналогии вы можете создать Log Targets и для других MPG.
- Повторите тестовые запросы:
- В случае успеха вы ничего не увидите в логах или увидите следующие сообщения, означающие, что вы работаете в режиме отладки и вредите производительности.
- А в случае ошибки увидите текст произошедшей ошибки.
- В случае успеха вы ничего не увидите в логах или увидите следующие сообщения, означающие, что вы работаете в режиме отладки и вредите производительности.
Часть 7. Если что-то пошло не так
- Если вам удалось дойти до логирования – вы знаете, где искать логи. Если их недостаточно – логируйте тело, хедеры и все, что могло бы вам как-то указать на причину ошибки.
- Часто не обойтись без системных логов. Перейдите на панели управления в раздел View Logs. Здесь всегда можно найти системные ошибки, вроде «не найден файл», «не удалось распарсить ответ» и всякая всячина подобного рода.
- Для начинающих будет очень полезен режим дебага. Он позволяет пошагово проследить ваше сообщение при прохождении через каждое действие. Для активации перейдите в нужный вам MPG и в верхнем меню справа нажмите Show Probe -> Enable Probe. После отправки запроса обновите список и нажмите на лупу. Переходя через действия, вы можете наблюдать за всеми трансформациями вашего запроса.
- Отключайте режим отладки, когда он вам больше не нужен.
Если ничего не помогло – задавайте вопросы в комментариях.