Msa

Расскажу о нашем опыте автоматического документирования 150+ микросервисов в системе LeanIX Enterprise Architecture Managment. Многое получилось, как мы и хотели, для чего-то пришлось делать специальные доработки, часть вопросов не смогли решить. Но в любом случае мы получили опыт и готовы им поделиться.

Начну статью с оговорки, что это результат прототипа или исследования. Попытка ответить на вопрос: "Возможно ли использовать системы описания архитектуры предприятия для описания системы построенной на микросервисном подходе?"

Для чего вообще нужно описывать ландшафт предприятия?

Короткий ответ для поддержания процессов управления архитектурой предприятия (Enterprise Architecture Management / EAM).

Более полный ответ уже заключен в самой дисциплине EAM это системная концепция для разработки и развития IT-ландшафта в соответствии с бизнес-возможностями и процессами, а также оргструктурой организации. Бизнес-возможности (business capabilities) в свою очередь являются основой, на которой предприятие строит свои текущие и будущие бизнес-процессы.

EAM включает в себя набор сценариев использования каталога IT-систем, вот основные:

• Управление знаниями
• Управление рисками
• Управление жизненным циклом IT приложения
• Планирование трансформации и изменений в ландшафте
• Еще кейсы можно посмотреть тут https://erwin.com/blog/use-cases-for-enterprise-architecture-architect-everything/

Cценарии выше релевантны не только для архитекторов предприятия (Enterprise Architect), но и для системных архитекторов (System Architect) и архитекторов решений (Solution Architects). Сам по себе каталог IT-систем особенно полезен на этапе интеграции приложений и отслеживания зависимостей. Тем более, что в большинстве организаций такой каталог является "Single Point of Truth".

Актуальность такого каталога необходимо постоянно поддерживать, либо тратя на это много времени сил, либо автоматизируя наполнение.
Эта проблема особенно ощутима, если хотя бы часть ландшафта предприятия построена на микросервисной архитектуре. В этом случае каталог будет содержать уже не 100-500 систем, а 500-1000 (и даже большое) компонентов.

Вот и у нас есть устоявшийся ландшафт на 500+ IT-систем (на диаграмме разбивка на отделы), и уже сейчас поддержка единой базы IT-приложений требует существенных трудозатрат (каталог самих приложений, их связей с бизне- функциями, связи между собой, roadmap каждого приложения и т.п.).

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

Соответственно, возникает вопрос как с этим всем жить?

• Самое простое решение не документировать в центральном каталоге каждый микросервис. Такой вариант не является совсем уж неверным: сами микросервисы не настолько интересны для бизнес-анализа ландшафта, а группы микросервисов можно объединить в "приложения"/"системы"/"домены" и документировать уже приложения. У этого решения, естественно, есть очень приятный плюс "сокращение трудозатрат" поддержки EAM каталога. Но если каждая система в каталоге будет представлять собой "черный ящик", то теряется прозрачность работы и взаимодействия внутренних компонентов. Также каждая IT-система в рамках своих проектов должна изобретать способ документирования своего каталога микросервисных компонентов, потому что при разработке все равно необходим общей список всех микросервисов приложения.

  
  

• Второе решение автоматизировать документирование микросервисов в каталоге IT-ландшафта. Вот с этим мы и поэкспериментируем.

  
  

Текущий ландшафт у нас описан в системе, построенной на платформе Alfabet. Сейчас мы активно анализируем EAM решение от компании LeanIX как потенциального преемника.

LeanIX относительно молодой продукт, поэтому с моей точки зрения, в нем пока мало "унаследовательности", и он достаточно гибок и обладает современными возможностями для интеграции, и что немаловажно, опять же по моему мнению, у него довольно удобный и приятный пользовательский интерфейс.
Даже Gartner в 2019 году назвал LeanIX одним из Visionaries.

Можно долго перечислять причины выбора именно LeanIX (мы действительно проводили RFI/RFP процесс), но не надо забывать что одним из основных инвесторов компании LeanIX является Deutsche Telekom Capital Partners, то есть мы сами заинтересованы в развитии продуктов LeanIX.

Разработчики системы LeanIX EAM изначально заложили в продукт возможность документирования микросервисов. Попытались они это сделать на основе подхода, предложенного проектом Pivio ( http://pivio.io/)

Сам по себе "Pivio-подход" работает следующим образом: рядом с исходным кодом компонента (микросервиса) размещается yaml файл с метаинформацией о компоненте, который
посредством Pivio Client загружается в Pivio Server.

Cервер хранит информацию в ElasticSearch и предоставляет API для ваших инструментов.
Также существует Pivio Webview c очень ограниченными возможностями поиска и визуализации каталога (видимо, это как раз та часть проекта Pivio, которую вы должны были сами расширять для своих потребностей).

Вызов Pivio Client может быть частью процесса сборки или деплоймента компонента.

Естественно, для загрузки документов в Pivio Client они должны быть определенного формата. (см. http://pivio.io/docs/)

Под спойлером пример такого документа:

id: next-generation-print-2342-2413-9189-1990name: Next Generation Print Serviceshort_name: NGPStype: serviceowner: Team Goldfingerdescription: Prints all kinds of things. Now with 3D printing support.vcsroot: git://git.vcs.local/UBPcontact: Auric Goldfingerlifecycle: productiontags:- Old- Demolinks:homepage: http://wiki.local/ubpbuildchain: http://ci.local/ubpapi_docs: http://docs.local/ubp-apiservice:provides:- description: REST APIservice_name: uber-bill-print-serviceprotocol: httpsport: 8443transport_protocol: tcppublic_dns:- api.demo-company.com- soap.demo-company.io- description: SOAP API (legacy)service_name: print-serviceprotocol: httpsport: 80transport_protocol: tcpdepends_on:internal:- service_name: print-servicewhy: need to print- service_name: gateway-service- short_name: NGPSport: 8719external:- target: https://api.superdealz.me:443transport_protocol: tcpvia: proxy-servicewhy: Need to sync data with it.- target: mqtt://192.xxx.xxx.xxx:5028transport_protocol: tcpwhy: Get the latest Dealz.

От общей архитектуры Pivio, система LeanIX переиспользовала только PivioClient и формат файла (LeanIX Metadata как раз и есть файл в формате Pivio). В качестве каталога микросервисов и визуализации (поиск, отчеты, диаграммы) используются возможности самого LeanIX EAM.

Практика

Вот эту схему интеграции мы и стали проверять на своем проекте. Проект достаточно крупный: 15+ команд разработки, 150+ микросервисов уже в эксплуатации. Нам повезло, метаинформацию о своих микросервисах мы уже хранили вместе с кодом (у нас multirepo схема git-репозиториев, и в каждом репозитории есть метаинформация о компоненте).

Формат нашей метаинформации (https://github.com/AOEpeople/vistecture) отличается от Pivio, но это все еще yaml файл и преобразовать его "на лету" в pivio формат не составило труда.
Информация об интерфейсах и зависимостях между компонентами у нас также была уже задокументирована в машиночитаемом формате (мы используем её для настройки API Gateway).
Для начала мы решили не копировать всю информацию из swagger в систему EAM (структуру данных, методы и т.п.), это осталось пока за рамками, но будет задачей на будущее.

В планах было все просто: встраиваем в наш CI/CD pipeline дополнительный шаг по загрузке метаинформации в LeanIX (конвертация, вызов Pivio Client, который доступен как в качестве jar файла, так и в виде docker контейнера). Выглядело в планах все отлично: декларативное описание компонента, полная автоматизация обновления информации в EAM.

Документация LeanIX по использованию Pivo Client тут: https://dev.leanix.net/docs/microservices-based-on-yaml-files

Но к середине первого дня работы к нам пришло осознание, что все будет не так просто:

• Оказалось, что LeanIX поддерживает только часть возможностей Pivio-формата (не все атрибуты).
• Что еще страшнее, оказалось, что реализация Pivio в LeanIX не поддерживает описание интерфейсов между микросервисами (мы не можем документировать зависимости между компонентами).
• Естественно, наш способ документирования не включал в себя случай, когда мы выводим сервис из эксплуатации и его надо удалить (нет у нас пока pipeline на удаление сервиса). Да и Pivio Client не умеет удалять описание микросервисов из LeanIX.

Пункт 1. решился дополнительным вызовом REST интерфейса самого LeanIX. (см. https://eu.leanix.net/services/pathfinder/v1/docs/#/)

Пункт 2. решился использованием GraphQL API LeanIX.

• позволяет создать сущность "Интерфейса" и связать его c провайдером и потребителем.

mutation {   createFactSheet(validateOnly: false,     input: {name: service["name"], type:Interface},     patches: [{op: replace, path:"/description",value: service_url },         {op: replace, path:"/externalId",value:"externalId:service["name"]"}] ) {                 factSheet {                     id                     name                     displayName}        }}

mutation{  upsertRelation(from:      {externalId: {type: externalId, id: service["name"] }},           to: {externalId: {type: externalId, id: service["provider"]}},            type: relInterfaceToProviderApplication) {                relation {                id            }      }}

• Но graphQL API LeanIX не декларатильвен, значит, надо выяснять разницу между тем что есть в LeanIX и тем, что мы хотим создать/обновить.

{allFactSheets(     filter: {externalIds: ["externalId/" + externalId]}        ) {        edges {            node {                id                name                }            }      }}

• Также мы столкнулись с тем, что нельзя привязать интерфейс к микросервису, если сам микросервис еще не документирован, следовательно, это требует последовательного создания документации на провайдера, потребителя и интерфейсов между ними. Решили мы пока эту задачу "топорно": создаем документацию на все компоненты и только потом документируем интерфейсы и зависимости.

Пункт 3. пока решили оставить как ручной шаг.

В итоге получилась такая рабочая схема:

Тут крупнее

После этого можно считать, что процесс автоматизации у нас заработал, a значит, мы можем позволить себе поддерживать документацию о наших микросервисах в системе LeanIX без дополнительных трудозатрат со стороны команд разработки.

Что это нам дало:

• полнотекстовый поиск по описаниям микросервисов и интерфейсов (в том числе по endpoints name).
• информацию о версии компонента на продакшене, а также название команды, которая за компонент отвечает сейчас.
• список потребителей каждого конкретного интерфейса.
• автоматическая визуализация распределения микросвервисов по их областям (доменам) и командам разработчикам.
  

Тут крупнее

На схеме уже видно, что баланс разделения ответственности между командами в области домена order куда лучше, чем, например, в presales. В order большая часть работы выполняется всего двумя командами и затраты на коммуникации и интеграции значительно ниже, чем между 4-мя командами в presales.

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

  
  

• Возможность визуализировать зависимости между сервисами.
  
  Тут крупнее
  Тут отражен "крайний" случай, когда на диаграмме видны все-все сервисы из нашей системы. Естественно, для анализа мы используем всегда "подмножество" сервисов или кросс-доменные взаимодействия.

  
  

Итоги и открытые вопросы:

• Вопрос о том, нужно ли вообще документировать микросервисы в общем IT-ландшафте все еще остается открытым, так как пользы от такой детальной документации для главного пользователя EAM (Enterprise Architect / Business Architect) пока немного. Но мы показали, что такая подробная документация нам почти "ничего не стоит".
• Автоматизация документирования отлично вписывается в pipeline CI/CD
• Сама система LeanIX гибка и предоставляет широкие возможности для интеграции. Но это и ее минус, так как не все способы одинаково функциональны и требуется разобраться во всех них.
  
  • Интеграция с Pivio Client декларативная, выглядит как то, что надо, но не поддерживает описание интерфейсов и у нее нет логики по "удалению" документации из LeanIX.
  • В REST API легко делать простые операции, но любой поиск по критериями превращается в "танцы с бубном" на стороне клиента.
  • GraphQL API не всегда логичный (к этому, наверное, можно привыкнуть).
  • Integration API до него пока не добрались, потому что требуется разбираться с проприетарном форматом обмена данными (LDIF)
• LeanIX молодая система, и в процессе проверки нашего подхода было найдено несколько дефектов. Надо отдать должное команде LeanIX: они исправляли проблемы быстро.
• Нам имеет смысл пересмотреть какие API мы действительно хотим видеть в общем каталоге. Вероятно, что у нас будет три типа API:
  
  • internal в рамках подсистемы/домена;
  • system для поддержки процессов через несколько доменов;
  • enterprise уровень для интеграции внешних систем.

Cледующие шаги:

• Хочется задокументировать swagger описания интерфейсов в той же системе (пока они у нас отдельно все собраны) или хотя бы просто проставить ссылки на наш API Developer Portal / Swagger UI.
• Вероятно, придется настроить интеграцию через "Integration API", так как по описанию он наиболее полный с точки зрения автоматизации документирования.
• После демонстрации нашего решения и результата компании LeanIX нам было предложено попробовать новый продукт "LeanIX Cloud Native Suite: Microservices Intelligence", который имеет метамодель более ориентированную на описание микросервисной архитектуры. Кроме вышеописанных интеграционных подходов также обещают прямую интеграцию с kubernets, что позволит снимать часть актуальной информации прямо с боевого окружения. Возможно, это станет темой следующей статьи.

Немного и полезных ссылок на прощание:

• https://en.wikipedia.org/wiki/LeanIX
• http://leanix.net
• http://pivio.io
• https://youtu.be/V56GEtx36HE?t=2693 (краткое содержимое этой статьи в трех слайдах)