В этой статье я дам краткую вводную, что такое Archi и ArchiMate. Расскажу о коллективной работе с Archi используя расширение coArchi, после чего предоставлю контейнер позволяющий автоматизировать работу по созданию HTML и PDF документов с ArchiMate моделями. Завершим же, созданием своего GitHub Action, настроим GitHub и GitLab пайплайн с последующей публикацией модели в GitHub/GitLab Pages.
В чем основная проблематика и причина появления этой автоматизации? Логично утверждать, что любая автоматика экономит время и выполняет рутину за вас, но основной причиной появления данного инструмента и статьи, является простота публикации моделей (схем). Я столкнулся с тем, что большинству нужно просто посмотреть или продемонстрировать схему, но ни кто не хочет разбираться с установкой дополнительного ПО, подключать к нему плагины, настраивать подключение к git репозиторию. Web-страница с актуальной и интерактивной моделью — это то, что нужно среднестатистическому менеджеру, да и архитектора не побеспокоят просьбой сделать скриншот текущей модели.
Для тех кому все подробности не нужны, резюмирую: используя этот GitHub Action или этот контейнер в результате получим такой результат.
Что такое Archi и ArchiMate
Набор кроссплатформенных инструментов моделирования Archi предназначен для архитекторов и разработчиков моделей всех уровней. Archi написан на Java и распространяются под лицензией MIT, репозиторий проекта доступен на GitHub. Он обеспечивает низкий порог входа для пользователей работающих с языком моделирования ArchiMate.
ArchiMate (в оригинале Architecture-Animate) — это открытый и независимый язык моделирования архитектуры предприятия и визуализации архитектуры внутри и за пределами бизнес-процессов. Это технический стандарт от The Open Group, базирующийся на IEEE 1471.
ArchiMate дистанцируется от других языков, таких как UML и BPMN по предназначению для моделирования предприятия. Цель ArchiMate — «быть настолько лаконичным, насколько это возможно» (as small as possible), а не охватить все возможные сценарии.
Основные сущности и типы связей языка ArchiMate можно рассматривать как структуру, так называемую ArchiMate Framework.
Слои языка хорошо соотносятся с соответствующими фазами метода разработки архитектуры TOGAF (TOGAF и ArchiMate являются стандартами The Open Group).
Экспорт модели
Модель ArchiMate представляет из себя XML документ и подразумевает наличие инструмента Archi для редактирования и просмотра. Archi позволяет экспортировать модель в виде отчуждаемых файлов, и поддерживает такие форматы:
Статический HTML отчет с интерактивной структурой и навигацией;
CSV отчет по имеющимся в модели элементам, характеристикам и связям;
Jasper отчет в форматах PDF, HTML, RTF, PPT, ODT и DOCX;
Экспорт модели в нативном формате XML с расширением
.archimate;Экспорт модели в формате Open Exchange XML.
Совместная работа
coArchi — это расширение Archi, которое позволяет вести коллективную работу над моделями ArchiMate, посредством совместного использования и управления версиями моделей в git репозитории.
Для установки расширения перейдите на страницу с списком расширений, найдите в списке coArchi и следуйте инструкциям. Репозиторий проекта на GitHub также содержит дополнительную информацию по настройке и решению проблем в работе, подробности смотрите в wiki.
ℹ️ Оригинальный файл модели ArchiMate представляет из себя единый XML документ с расширением
.archimate. Для возможности совместного редактирования и слияния изменений, данная модель разбивается плагином coArchi на элементы, где каждый элемент хранится в отдельном файле. Соответственно открыть модель сохраненную в репозитории при помощи coArchi, вы сможете только используя это расширение.
Некоторые функции coArchi находятся в стадии разработки и постоянно улучшаются. На текущий момент coArchi версии 0.8.1 имеет ограниченную поддержку специализаций и образов добавленных в Archi 4.9.
ℹ️ Обратите внимание, что для работы с репозиторием по SSH средствами плагина coArchi — работают только RSA ключи в формате PEM, о чем написано в разделе вики. Также вам не удастся использовать oauth2 токен (у меня не вышло), к примеру в случае активной двухфакторной аутентификации. Судя по всему проблема связана с JGit используемым в проекте, разработчики плагина пока не дали ответа на это замечание.
Как видим, всё же имеются некоторые трудности в настройке окружения, на этапе установки coArchi и клонирования модели зачастую менеджер сдается и просто просит скриншот модели у её авторов.
Интерфейс командной строки
Помимо графического интерфейса, Archi также имеет интерфейс командной строки. Подробную справку о работе с ним вы можете найти в вики проекта.
К примеру для вывода справки с доступными аргументами выполните:
./Archi -application com.archimatetool.commandline.app \
-consoleLog -nosplash --helpОбраз контейнера Archi
Получив сведения о том, что у Archi есть CLI, функция экспорта и возможна совместная работа в git репозитории, мы имеем все основания попытаться упаковать всё это в образ контейнера, для дальнейшего использования в пайплайне.
Поскольку некоторые библиотеки зависят от наличия драйвера дисплея, для запуска CLI в Linux, нам потребуется установить определенные библиотеки, такие как gtk3 и xvfb. В связи с этим и размер образа становиться заметно больше.
Итоговый Dockerfile доступен в репозитории:
А для удобства работы со всеми аргументами командной строки и реализации возможности доступа к репозиторию модели с любыми стандартными проколами и методами аутентификации git, был реализован bash сценарий запуска entrypoint.sh:
В скрипте реализованы переменные окружения для управления ключевыми параметрами клонирования модели и создания отчета, что упростит применение образа в CI пайплайнах.
Клонирование репозитория выполняется привычной утилитой git, а уже после передается Archi как модель. Так мы обходим ограничения самого coArchi.
Выполнена обвязка для исполнения задания в GitHub Actions с созданием отдельной ветки используя git subtree и дальнейшей публикацией в GitHub Pages.
Выполнена обвязка для более простого запуска заданий в GitLab CI
ℹ️ Git subtree выбран не спроста. Как альтернативный вариант в GitHub Pages можно опубликовать файлы из отдельного каталога текущей ветки, к примеру
/docs, но в таком случае у нас в основной рабочей ветке появляются лишние автоматические "шумные" коммиты, а вместе с ними и растет размер индекса этой ветки, помимо этого, при ответвлении и слиянии правок у нас появляются конфликты в сгенерированных отчетах, которые просто так не решаются через интерфейс Archi.
Образы контейнера доступны в репозиториях:
GHCR
ghcr.io/woozymasta/archimate-ci:4.9.1-1.0Quay
quay.io/woozymasta/archimate-ci:4.9.1-1.0DockerHub
docker.io/woozymasta/archimate-ci:4.9.1-1.0
Пайплайн
Для демонстрации работы был создан отдельный проект на GitHub и GitLab с примером модели ArchiMetal взятой из официального репозитория archimate и сохраненной при помощи coArchi.
При запуске контейнера в среде GitHub Action или GitLab CI в HTML отчет также будут добавлены ссылки на другие отчеты включенные для генерации.
GitLab пайплайн
Для генерации отчета и публикации его в GitLab Pages необходимо создать файл .gitlab-ci.yml в корне проекта вашей coArchi модели, примерно с таким содержимым:
---
pages:
stage: build
image:
name: quay.io/woozymasta/archimate-ci-image:4.9.1-1.0.2
entrypoint: [""]
script:
- /opt/Archi/entrypoint.sh
variables:
ARCHI_HTML_REPORT_ENABLED: "true"
ARCHI_JASPER_REPORT_ENABLED: "true"
ARCHI_JASPER_REPORT_FORMATS: "PDF,DOCX"
ARCHI_CSV_REPORT_ENABLED: "false"
ARCHI_EXPORT_MODEL_ENABLED: "true"
rules:
- if: $CI_COMMIT_BRANCH != null || $CI_PIPELINE_SOURCE == "merge_request_event"
exists:
- model/folder.xml
artifacts:
name: "$CI_JOB_NAME from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"
expire_in: 30d
paths:
- public
После фиксации изменений в репозитории, у вас должен успешно выполнится пайплайн (пример), а модель опубликоваться в виде web-страницы (пример) в вашем GitLab Pages.
GitHub пайплайн
Для GitHub был реализован GitHub Action - Deploy Archi Report, который опубликует вашу модель на GitHub Pages из отдельной ветки gh-pages. Чтобы воспользоваться им вам достаточно создать файл в каталоге .github/workflows к примеру .github/workflows/main.yml с таким содержимым:
---
jobs:
archi_report:
permissions:
contents: write
pages: write
runs-on: ubuntu-latest
name: Deploy Archi report HTML to GitHub Pages
steps:
- name: Check out the repo
uses: actions/checkout@v2
- name: Deploy Archi report
id: archi
uses: WoozyMasta/archimate-ci-image@4.9.1-1.0.2
with:
archiHtmlReportEnabled: true
archiJasperReportEnabled: true
archiJasperReportFormats: PDF,DOCX
archiCsvReportEnabled: false
archiExportModelEnabled: true
githubToken: ${{ secrets.GITHUB_TOKEN }}Зафиксировав изменения в репозитории, у вас должен успешно выполнится пайплайн (пример). После первого запуска вам также понадобится указать из какой ветки следует публиковать отчет, по умолчанию это gh-pages. Перейдите в настройки репозитория, в разделе Pages укажите исходную ветку gh-pages и используйте корневой каталог для поиска файлов, примените эти настройки.
После этого, публикация будет выполнятся из указанной вами ветки (пример) в вашем GitHub Pages.
На этом всё
Благодарю за ваше время и внимание! Успешных вам пайплайнов и актуальных моделей.
Присоединяйтесь в телеграмм канал, где я периодически публикую заметки на тему DevOps, SRE и архитектурных решений.
