Пример организации процесса CI/CD#

Рассмотрим организацию простейшего процесса непрерывной разработки и развертывания программных продуктов. При необходимости вы можете воспроизвести данный сценарий в собственном окружении.

Описание сценария#

Приведен пример планирования и настройки непрерывного процесса разработки программного проекта (CI, continuous integration) и его развертывания (CD, continuous deployment).

Особенности сценария:

  • Проект хранится в публично доступном репозитории под управлением Git, используя GitHub.

  • Обработку процессов CI/CD выполняет контроллер Astra Automation.

  • При создании запроса (PR, pull request) на внесение изменений в какую-либо ветку репозитория GitHub вызывает процесс CI, целью которого является проверка корректности разработанного программного продукта. При исполнении контролируемая программа оповещает о корректности путем возврата соответствующего кода:

    • 0 – программа работает корректно;

    • 1 – в программе обнаружена ошибка.

    При обнаружении ошибки в программе разработчик имеет возможность исправить код и повторить процесс CI.

  • После слияния рабочей ветки с веткой master GitHub вызывает процесс CD, в котором контроллер проверяет, что объектом изменений является ветка master. В этом случае он запрашивает разрешение на обновление продукта и после одобрения выполняет обновление продукта.

Структура проекта#

Проект реализации сценария включает разработку структуры и инфраструктурного кода.

Взаимодействие компонентов#

Структурная схема сценария представляется в следующем виде:

../../_images/cdcd-process-light.svg ../../_images/cdcd-process-dark.svg

Взаимодействие компонентов в процессе CI происходит следующим образом:

  1. В репозитории GitHub разработчик вносит изменения в демонстрационную программу и создает запрос на внесение изменений в ветку master (PR).

  2. GitHub перехватывает PR с помощью соответствующего объекта webhook и направляет запрос на выполнение процесса CI в контроллере. Запрос PR переходит в состояние ожидания ответа от контроллера.

  3. Контроллер получает запрос на запуск задания из шаблона, реализующего процесс CI. В данном сценарии задание выводит содержимое программы в выходной поток и запускает программу для проверки корректности ее выполнения.

  4. Контроллер возвращает результат обработки запроса в GitHub.

  5. GitHub получает результат запроса и сообщает о готовности внести изменения в master.

CD является продолжением предыдущего процесса. Его можно выполнить в случае успешного завершения последнего:

  1. Разработчик принимает решение о внесении изменений, представленных PR, в ветку master и начинает процесс слияния веток (Git merge).

  2. После завершения обновления ветки master GitHub перехватывает запрос с помощью соответствующего объекта webhook и направляет запрос на выполнение процесса CD в контроллере.

  3. Контроллер получает запрос на запуск заданий из шаблона потока, реализующего процесс CD. Он запускает выполнение цепочки заданий, включая получение одобрения от ответственного лица.

    Примечание

    В отличие от процесса CI, контроллер не возвращает результат обработки запроса в GitHub. Поэтому результаты процесса CD необходимо анализировать средствами контроллера.

Репозиторий проекта#

Для простоты исполняемый код обслуживаемой демонстрационной программы разработчика (project.sh) и инфраструктурный код для реализации сценария находятся в одном репозитории в виде следующей структуры каталогов и файлов:

./
├── aac
│   ├── cd_check.yml
│   ├── cd_deploy.yml
│   └── ci.yml
└── project.sh

Назначение и состав файлов представлены в следующих секциях. Для воспроизведения сценария загрузите эти файлы в свой репозиторий GitHub в соответствии с представленной структурой.

Демонстрационная программа#

Демонстрационная программа, к которой применены процессы CI/CD, состоит из одного скрипта shell project.sh (download):

Demo program
#!/bin/bash

# Use "exit 0" to simulate correct code
# Use "exit 1" to "exit 255" to simulate incorrect code
exit 1

CI/CD playbooks#

Каждая часть процесса использует отдельные файлы playbook.

Процесс CI состоит из одного задания, которое выполняется с помощью playbook aac/ci.yml (download) на локальном узле, то есть на самом контроллере:

CI playbook
---
- hosts: localhost
  become: false
  gather_facts: false
  tasks:
    - name: Get code revision "{{ awx_webhook_event_ref }}"
      ansible.builtin.git:
        repo: "{{ awx_webhook_payload.repository.clone_url }}"
        dest: /tmp/project
        version: "{{ awx_webhook_event_ref }}"

    - name: Show main project
      ansible.builtin.shell:
        chdir: /tmp/project
        cmd: cat ./project.sh

    - name: Check main project
      ansible.builtin.shell:
        chdir: /tmp/project
        cmd: ./project.sh

Playbook выполняет следующие действия:

  1. Создает клон репозитория, адрес которого содержит переменная awx_webhook_payload.repository.clone_url, в каталоге /tmp/project/.

  2. Выводит содержимое файла проекта в выходной поток командой cat.

  3. Запускает на выполнение скрипт программы для тестирования ее работоспособности. По результатам выполнения контроллер определяет корректность внесенных изменений.

Процесс CD состоит из потока заданий, в который вовлечены следующие файлы playbook:

  1. aac/cd_check.yml (download) – проверка того, что вызов задания связан с обновлением ветки master в репозитории GitHub:

    CD check playbook
    ---
    - hosts: localhost
      become: false
      gather_facts: false
      tasks:
        - name: Check if push is into master branch
          ansible.builtin.fail:
            msg: This push is not into master branch
          when: awx_webhook_payload.ref != "refs/heads/master"
    

    Playbook завершает аварийно процесс CD, если обновление было не в ветке master. В противном случае процесс продолжается.

  2. aac/cd_deploy.yml (download) – демонстрационное (фиктивное) развертывание продукта:

    CD deployment playbook
    ---
    - hosts: localhost
      become: false
      gather_facts: false
      tasks:
        - name: Deploy project
          ansible.builtin.debug:
            msg: The project is being deployed.
    

    Playbook только выводит сообщение о выполнении развертывания.

Настройка процесса#

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

Настройка прав доступа#

Для обеспечения взаимодействия компонентов проекта необходимо предоставить контроллеру полномочия на доступ к репозиторию GitHub. Это позволит контроллеру возвращать состояние процесса (callback) в GitHub. Полномочия необходимо предоставить через персональный токен доступа к репозиторию GitHub. Для его создания в GitHub существует следующая последовательность шагов в настройках:

profile > settings > developer settings > personal access tokens > tokens(classic) > generate new token

Примечание

Сгенерированный токен показывается только один раз. Для повторного использования необходимо сохранить его в надежном месте.

Контроллер#

В контроллере необходимо произвести следующие настройки:

  1. Задайте базовый URL сервиса, который для контроллера, установленном на одном узле, совпадает с URL этого контроллера. Шаги настройки:

    Настройки (Settings) > Система (System) > Общие системные настройки (Miscellaneous System settings) > Базовый URL сервиса (Base URL of the service)

    Примечание

    Базовый URL будет передан в GitHub для использования его в качестве ссылки на соответствующее задание контроллера.

  2. Создайте организацию. Шаги настройки:

    Access > Organizations > Add

    Параметры настройки:

    • Название: cicd.

  3. Создайте полномочие на доступ к репозиторию GitHub. Шаги настройки:

    Resources > Credentials > Add

    Параметры настройки:

    • Название (Name): cicd;

    • Тип полномочия (Credential Type): Личный токен доступа к GitHub (GitHub Personal Access Token);

    • Сведения о типе (Type Details) > Токен (Token): <содержимое токена, созданного для организации или учетной записи в GitHub>;

    • Организация (Organization): cicd.

  4. Создайте проект на основе репозитория, созданного в GitHub. Шаги настройки:

    Resources > Projects > Add

    Параметры настройки:

    • Название: cicd;

    • Организация (Organization): cicd;

    • Среда исполнения (Execution Environment): Default execution environment;

    • Тип системы управления исходными данными (Source Control Type): Git;

    • URL системы управления исходными данными (Source Control URL): https://github.com/<GitHub account or organization>/<repo-name>.git.

  5. Создайте шаблоны заданий. Шаги настройки:

    Resources > Templates > Add > Add job template

    Параметры настройки для шаблона CI:

    • Название (Name): ci;

    • Тип задания (Job Type): Выполнение (Run);

    • Инвентарь (Inventory): Demo Inventory;

    • Проект (Project): cicd;

    • Playbook: aac/ci.yml.

    • В секции Опции (Options) включите следующие флаги:

      • Включить webhook (Enable Webhook);

      • Параллельные задания (Enable Concurrent Jobs).

    • В секции Подробности о webhook (Webhook details) настройте следующие параметры:

      • Сервис webhook (Webhook Service): GitHub;

      • Полномочия webhook (Webhook Credential): cicd.

    Сохраните настройки.

    Параметры настройки для шаблона задания на шаге проверки процесса CD:

    • Название (Name): cd_check;

    • Тип задания (Job Type): Выполнение (Run);

    • Инвентарь (Inventory): Demo Inventory;

    • Проект (Project): cicd;

    • Playbook: aac/cd_check.yml.

    Сохраните настройки.

    Параметры настройки для шаблона задания на шаге развертывания процесса CD:

    • Название (Name): cd_deploy;

    • Тип задания (Job Type): Выполнение (Run);

    • Инвентарь (Inventory): Demo Inventory;

    • Проект (Project): cicd;

    • Playbook: aac/cd_deploy.yml.

    Сохраните настройки.

  6. Создайте шаблон потока заданий для процесса CD. Шаги настройки:

    Resources > Templates > Add > Add workflow template

    Параметры настройки:

    • Название (Name): cd;

    • Организация (Organization): cicd;

    • Инвентарь (Inventory): Demo Inventory.

    • В секции Опции (Options) выберите следующие опции:

      • Включить webhook (Enable Webhook);

      • Параллельные задания (Enable Concurrent Jobs).

    • В секции Подробности о webhook (Webhook details) настройте следующие параметры:

      • Сервис webhook (Webhook Service): GitHub;

      • Полномочия webhook (Webhook Credential): cicd.

    Сохраните настройки.

    Во всплывающем окне Пожалуйста, нажмите кнопку «Пуск», чтобы начать (Please click the Start button to begin) нажмите кнопку Пуск (Start) для настройки потока с помощью визуализатора.

    • Создайте узел на основе шаблона cd_check со следующими параметрами:

      • Тип узла (Node Type): Шаблон задания (Job Template);

      • Название (Name): cd_check.

    • Создайте узел согласования со следующими параметрами:

      • Тип узла (Node Type): Согласование (Approval);

      • Название (Name): Согласование развертывания продукта.

    • Создайте узел на основе шаблона cd_deploy со следующими параметрами:

      • Тип узла (Node Type): Job Template;

      • Название (Name): cd_deploy.

После сохранения каждого из двух шаблонов контроллер сгенерирует параметры доступа для шаблона в следующем виде:

  • Webhook URL: <webhook URL>;

  • Ключ webhook (Webhook key): <hash code>.

Параметры доступа необходимы для настройки объектов webhook в GitHub.

GitHub#

В репозитории проекта необходимо настроить перехват событий с помощью объектов webhook.

Шаги настройки:

Settings > Webhooks > Add webhook

Создайте объекты перехвата событий со следующими параметрами:

  • Webhook для CI:

    • Payload URL: <URL, использованный в настройках шаблона задания CI в контроллере>;

    • Content type: application/json;

    • Secret: <значение Webhook key из настроек шаблона задания CI в контроллере>;

    • SSL verification: Disable.

      Примечание

      Здесь и далее необходимо отключить проверку сертификата, если не установлен корректный сертификат TLS/SSL на сервере, которому вы доверяете.

    • В секции Which events would you like to trigger this webhook выберите опцию Let me select individual events.

    • В открывшемся списке выберите Pull requests.

    • Выберите опцию Active.

  • Webhook для CD:

    • Payload URL: <URL, использованный в настройках шаблона потока заданий CD в контроллере>;

    • Content type: application/json;

    • Secret: <значение Webhook key из настроек шаблона задания CI в контроллере>;

    • SSL verification: Disable.

    • В секции Which events would you like to trigger this webhook выберите опцию Let me select individual events.

    • В открывшемся списке выберите Pushes.

    • Выберите опцию Active.

Проверка работоспособности#

Проверке подлежат отдельно два процесса.

Проверка CI#

Инициируйте процесс CI следующими действиями:

  1. В репозитории GitHub внесите изменение в файл project.sh, так чтобы в нем оставалась команда exit 1, имитирующая некорректный код.

  2. Нажмите кнопку Commit changes….

  3. Выберите опцию Create a new branch… и введите комментарий в поле сообщения.

  4. Нажмите кнопку Propose changes.

  5. Нажмите кнопку Create pull request.

Сервис GitHub выведет сообщения о начале обработке события. Эта обработка завершается сообщением об ошибке «All checks have failed, 1 failing check».

Проверьте запуск процесса CI в контроллере:

  1. В панели навигации откройте Views > Jobs. В верху списка вы видите появление новой записи о запуске задания из шаблона CI.

  2. Откройте задание и изучите результат его работы. Поскольку скрипт project.sh возвращает код 1, то последняя задача в playbook ci.yml возвращает ошибку.

Повторите весь процесс, обеспечив в скрипте project.sh выполнение команды exit 0, сообщающей об успешном выполнении программы. Отличия от предыдущей попытки:

  • Процесс следует начать с редактирования последней ветки, созданной в предыдущей попытке.

  • Не надо создавать еще одну ветку, а выберите ту, в которой вы внесли изменения.

В этот раз процесс CI завершается успешно. Для того, чтобы убедиться в этом, откройте в вкладку Pull requests и затем откройте новейший PR.

Проверка CD#

Процесс CD является продолжением процесса CI. После успешного завершения CI сервис GitHub предоставит возможность начать процесс обновления ветки master с последующим обновлением продукта.

После появления зеленой кнопки Merge pull request выполните обновление ветки master. Для этого нажмите кнопку Merge pull request и затем Confirm merge.

На этом работа в GitHub завершена.

Проверьте запуск процесса CD в контроллере:

  1. В панели навигации откройте Views > Jobs. В верху списка вы видите появление новой записи о запуске потока заданий из шаблона CD.

  2. Откройте задание и изучите результат ее работы.

  3. Используйте один из следующих способов для определения узла графа, требующего разрешения на выполнение дальнейших действий:

    • визуализатор открытого потока заданий;

    • иконка уведомлений (в виде колокольчика);

    • список согласований, который можно открыть с помощью панели навигации: Режимы просмотра ‣ Согласование потоков заданий (Views ‣ Workflow Approvals).

  4. Выберите соответствующий узел и нажмите кнопку Согласовать (Approve). Убедитесь, что выполнение потока заданий (процесс CD) завершено успешно.