Documentation

Расскажу о нашем опыте автоматического документирования 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 (краткое содержимое этой статьи в трех слайдах)

Ведение документации для тестирования в Google-доках и Google-таблицах не лучший способ работы с тестовой документацией. Такой подход имеет свои недостатки.
В этой статье я расскажу, как мы перешли от хранения тестовой документации с Google docs к специализированным SaaS-решениям, сделаю сравнение трех разных инструментов (HipTest, Leantesting, Test Management for Jira) и поделюсь результатами такого перехода.

Меня зовут Татьяна и уже 2,5 года я работаю в компании Englishdom на позиции qa engineer. Мы онлайн-школа английского языка, и наш IT-отдел разрабатывает уникальную цифровую платформу учебник для изучения английского, а также несколько приложений для тренировок и домашних заданий. QA-команда тестирует эти продукты и для этого мы ведем документацию.
Использование Google-доков и Google-таблиц имеет свои преимущества:

• бесплатные ресурсы без ограничений;
  
• легкая адаптация так как таблицы простой и понятный инструмент.
  

Но у такого подхода есть и свои недостатки:

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

Когда я пришла на работу в проект Englishdom, в качестве тестовой документации мы как раз использовали чек-листы в Google-таблицах и в Confluence. Из-за недостатков, описанных выше, одной из главных задач для улучшения процессов был переход с чек-листов на тест-кейсы. А для этого требовался хороший инструмент для их хранения и управления.

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

• избегание переезда или нежелание переноса множества тестов на другой инструмент;
  
• дискомфорт при выходе из зоны комфорта и получении непривычного нового опыта;
  
• отсутствие необходимого бюджета, т.к. почти все Test Case Management Tools платные;
  
• выбор self-hosted, а не saas-cloud решений для Test Case Management System, что также является платным, и может быть проблемой ввиду отсутствия или ограниченности бюджета;
  
• имеются сложности договориться с менеджментом о необходимости или стоимости для такого инструмента.
  

В нашем случае первоначально стояла задача: найти бесплатный Test Case Management Tool на минимальное количество пользователей, так как на проекте было всего несколько тестировщиков и большое количество юзеров для нас не имело значения, также количество тестовых проверок на тот момент было не слишком большое. Ввиду этого не было необходимости в платном и супер-крутом инструменте.

HipTest

Дальше настало время экспериментов. Первый инструмент, который мы решили попробовать это HipTest https://hiptest.net/ Представлю краткий его обзор:


Преимущества:

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

Недостатки:

• создание и редактирование сценариев и action words (при создании новых шагов-действий можно квалифицировать их как шаг, ожидаемый результат или многоразовое действие, это называется action words в HipTest) возможно только в HipTest, а редактор там специфичный. Чтобы понять, нужно попробовать и сравнить с блокнотом или, скажем, с google docs/sheets;
  
• массовый быстрый рефакторинг сценариев не получится так же, как это легко можно делать в текстовых редакторах;
  
• необходимо быть аккуратным с переименованием (случайным или нет) action words, т.к. в случае, если сценарий уже автоматизирован, то переименование только в HipTest приводит к упавшему тесту, потому что в части реализации наш action word остался с прежним именем;
  
• нет возможности прикреплять скриншот к step, а только ко всему тест-кейсу.
  

Пример тестового сценария в hiptest

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

P.S. В моем рассказе HipTest представлен в том виде, который был на момент нашего использования. На данный момент HipTest объединен с Cucumber под одним брендом, запустив CucumberStudio и новый улучшенный веб-сайт Cucumber.io. Однако теперь инструмент платный.

LEANTESTING

Итак, поиски инструмента продолжились. Следующим был вариант https://leantesting.com/ (по сути это бесплатный аналог Test Rail, однако есть возможность приобрести расширенные возможности за дополнительную плату. Сейчас мы рассмотрим особенности бесплатной версии.

Пример тестового сценария в LeanTesting

Преимущества:

• неограниченное количество пользователей;
  
• неограниченное количество проектов;
  
• неограниченное количество тестов и тест сайклов;
  
• удобные отчеты;
  
• в новом обновлении Lean Testing может запускать автоматизированные тесты с Selenium.
  

Недостатки:

• интеграция с другими вебхуками (например, Slack, GitGub, BitBucket ) платная;
  
• настройка пользовательских статусов и типов ошибок также платная;
  
• нет интеграции с какими-либо системами баг-трекеров (в нашем случае Jira);
  
• скриншот можно прикрепить только к тест-кейсу в целом, но не к шагам;
  
• нет возможности импортировать тест-кейсы из других Test Case Management Tools или Excel.
  

Изначально приняв решение о переходе на этот инструмент, мы видели одно большое преимущество более удобный пользовательский интерфейс, чем в HipTest, но спустя год активного использования все-таки решили уйти от Lean Testing. Главной причиной для нас на тот момент стало отсутствие интеграции с Jira (на проекте мы активно ее используем для ведения всех задач и, конечно же, было бы удобно хранить все в одном месте) и возможность прикреплять скриншот только ко всему тест-кейсу, а не к каждому шагу. Также на тот момент в бесплатной версии было ограничено количество создаваемых кейсов.

То есть изначально при выборе инструмента, мы не задумывались о таких вещах как интеграция с Jira, но впоследствии пришли к выводу, что это было бы очень удобно и полезно для тестирования и разработки. Мы не думали про то, что проект будет так стремительно расти, а с ним и количество наших тестов. Изначально мы просто хотели перенести документацию только для части функционала, а остальную оставить в Confluence. Но со временем, пощупав удобство пользования тест-кейсами в специальной системе их хранения, мы решили переносить туда и другие тесты.

Test Management for Jira (TM4J)

Спустя какое-то время поиска выбор пал на Test Management (https://www.adaptavist.com/doco/display/KT/Test+Management+for+Jira+Server) встраиваемый в Jira инструмент, простыми словами плагин.

Преимущества:

• красивые и понятные отчеты в виде диаграмм (но довольно простенькие);
  
• добавление и удаление статусов к тест-кейсам, тест прогонам и результатам;
  
• возможность проставлять лейблы, компоненты, приоритеты в каждом кейсе;
  
• возможность добавлять скрины в каждый шаг тест-кейса (!);
  
• связь с Jira.
  

Недостатки:

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

Для нас главным и приоритетным преимуществом выбора инструмента стала все-таки связь с Jira. Это значит, что во время прохождения тест-сайкла на регрессии перед релизом вы заводите баг и прикрепляете прямо к тест-кейсу, указываете на каком шаге фейлится тест, разработчик заходит сразу в тест-кейс и видит нужную информацию это же круто, экономия времени). Еще вариант использования: продакт-менеджер создает задачу, qa прикрепляет тест-кейсы к задаче, разработчик сразу видит тест кейс и шаги к нему, которые ему необходимо пройти перед передачей функционала на тестирование. И несмотря на то, что плагин платный, мы поняли, что эти преимущества очень важны для нас и помогут улучшить процессы в тестировании.

Визуализация тест сайклов

Визуализация создания тест-кейса (скрин1)

Визуализация создания тест-кейса (скрин2)

Сравнительный анализ трех инструментов приведен в таблице:

Итоги

Методом проб и ошибок мы сменили инструмент, выбрав тот, который оказался самым удобным для нашего проекта, изменили подход к ведению тестовой документации, ее хранению и управлению, забыв про чек-листы в Google-таблицах и полностью перейдя на тест-кейсы в специальной системе Test Management. За все время использования еще ни разу не пожалели о выборе. Ведение тестовой документации прямо в Jira оказалось неимоверно удобным. Такой подход планируем использовать и в будущем.

Совет для тех, кто еще не решился уходите из Google-доков и переходите на специальные инструменты для тестовой документации. Какой решать вам, предложений по инструментам действительно много, но точно найдется вариант под ваш проект и ваши цели. Я лишь поделилась историей опыта нашего qa-отдела. Могу сказать, что это сэкономило нам немало времени. Пара примеров: актуализация, формирование тест-сайкла и распределение ответственных qa раньше занимало приблизительно час, сейчас 40 мин. Также создание бага раньше занимало до 15 мин, сейчас около 5 мин времени. Итого, экономия времени составила до 30%.

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