В этой статье я дам краткую вводную, что такое 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.0

• Quay quay.io/woozymasta/archimate-ci:4.9.1-1.0

• DockerHub 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 и архитектурных решений.