Развертывание пользовательского (self-hosted) воркера SourceCraft на виртуальной машине Yandex Compute Cloud

Пользовательские (self-hosted) воркеры — личные серверы пользователей, как виртуальные, так и физические, на которых выполняются CI/CD-процессы SourceCraft. В этом случае для процессов будет доступно окружение пользовательского сервера.

На пользовательские воркеры не действуют ограничения на объем вычислительных ресурсов, а также не расходуется квота на суммарное время работы CI/CD-процессов.

При наличии компьютера с подходящей конфигурацией, можно самостоятельно на нем настроить пользовательский воркер для SourceCraft. В ином случае можно создать виртуальную машину в Compute Cloud и установить пользовательский воркер на ней. Более того, можно автоматизировать не только процессы создания ВМ, установки, настройки и запуска пользовательского воркера, но и процесс удаления ВМ после выполнения рабочего процесса CI/CD. Таким образом, можно оптимально использовать ресурсы Compute Cloud.

В руководстве рассматривается пример, как реализовать такую автоматизацию с помощью CI/CD-процессов SourceCraft с использованием сервисного подключения.

Варианты использования пользовательского воркера:

  • В том же репозитории, из которого воркер был создан. Для такого случая предусмотрено автоматическое удаление ВМ после выполнения рабочего процесса.

    Пример рабочего процесса test-task-and-delete-vm-async
    test-task-and-delete-vm-async:
  runs_on: self-hosted
  tasks:
    - test-task
    - name: delete
      uses: delete-vm-async
      needs: [test-task]

    Задание test-task выполняет полезную работу, например компиляцию проекта.

    Задание delete запускается только после выполнения test-task (параметр needs: [test-task]) и удаляет в асинхронном режиме ВМ, на которой запускался пользовательский воркер.

    Перед запуском рабочего процесса test-task-and-delete-vm-async нужно запустить рабочий процесс create-vm, в котором будет создан пользовательский воркер.

    Примечание

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

  • В любом другом репозитории организации. Удалять ВМ с пользовательским воркером в таком случае нужно вручную.

Чтобы развернуть пользовательский воркер SourceCraft на ВМ Compute Cloud:

  1. Подготовьтесь к работе.
  2. Разверните инфраструктуру.
  3. Создайте репозиторий с конфигурацией CI/CD.
  4. Создайте секреты.
  5. Настройте сервисное подключение.
  6. Настройте CI/CD-процесс.
  7. Проверьте работу воркера.

Если созданные ресурсы вам больше не нужны, удалите их.

Подготовьтесь к работе

  1. Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

    1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
    2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

    Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

    Подробнее об облаках и каталогах

  2. Аутентифицируйтесь в SourceCraft на главной странице сервиса или зарегистрируйтесь.

В стоимость поддержки инфраструктуры пользовательского воркера входят:

Разверните инфраструктуру

  1. Если у вас еще нет сетевой инфраструктуры в каталоге Yandex Cloud, в котором вы хотите разместить ВМ с пользовательским воркером, создайте облачную сеть, например default, и подсеть, например default-ru-central1-d.

    Примечание

    В предложенном в руководстве примере конфигурации CI/CD используются сеть с названиями default и подсеть default-ru-central1-d.

  2. В предложенном примере для ВМ используется группа безопасности по умолчанию. Добавьте в нее следующие правила:


    Направление
    трафика

    Описание

    Диапазон портов

    Протокол

    Источник /
    Назначение

    CIDR блоки

    Входящий

    Доступ к ВМ из
    интернета

    0-65535

    Любой

    CIDR

    0.0.0.0/0

    Исходящий

    Доступ ВМ в
    интернет

    0-65535

    Любой

    CIDR

    0.0.0.0/0

  3. В каталоге Yandex Cloud, в котором вы хотите разместить ВМ с пользовательским воркером, создайте сервисный аккаунт с ролью compute.editor на каталог.

    От имени этого сервисного аккаунта будут создаваться ВМ в Compute Cloud, и осуществляться сервисное подключение SourceCraft.

Создайте репозиторий с конфигурацией CI/CD

Совет

В примере показано, как создать новый репозиторий с использованием в качестве основы репозитория self-hosted-worker.

Вместо создания нового репозитория вы также можете сделать ответвление (fork) от репозитория self-hosted-worker.

  1. Создайте новый пустой репозиторий в организации, чьи облако и каталог будут использоваться для ВМ пользовательского воркера.

    На открывшейся странице скопируйте ссылку для доступа к новому репозиторию вида: https://git@git.sourcecraft.dev/<слаг_организации>/<слаг_нового_репозитория>.git.

    Примечание

    В примере далее для работы с git используется протокол HTTPS. Также вы можете работать по протоколу SSH.

  2. Клонируйте репозиторий self-hosted-worker с примером развертывания пользовательского воркера:

    git clone https://git@git.sourcecraft.dev/examples/self-hosted-worker.git
cd self-hosted-worker

    Репозиторий self-hosted-worker содержит следующие файлы:

    ├── .sourcecraft
│   └── ci.yaml                      # конфигурация CI/CD SourceCraft
├── .gitignore
├── compute-instance-create.sh       # скрипт для создания ВМ
├── compute-instance-delete-async.sh # скрипт для удаления ВМ в асинхронном режиме
├── compute-instance-delete.sh       # скрипт для удаления ВМ
├── metadata.yaml                    # метаданные для ВМ
└── README.md

  3. Используйте репозиторий self-hosted-worker в качестве основы для своего нового репозитория:

    git remote remove origin
git remote add origin https://git@git.sourcecraft.dev/<слаг_организации>/<слаг_нового_репозитория>.git
git branch -M main

  4. Отправьте изменения в новый репозиторий:

    git push -u origin main

Создайте секреты

  1. Получите персональный токен (PAT) с ролью Администратор репозитория с доступом к репозиторию, в котором вы хотите использовать пользовательский воркер для CI/CD.

    Совет

    Если вы хотите использовать воркер не только для репозитория, из которого он был создан, укажите для персонального токена соответствующие права.

    С помощью этого токена воркер аутентифицируется в SourceCraft.

  2. Сгенерируйте SSH-ключи для доступа на ВМ с воркером.

  3. Создайте следующие секреты SourceCraft:

    • с названием PAT и значением токена;
    • с названием SSH_PUB и публичным SSH-ключом.

Настройте сервисное подключение

Сервисные подключения — это безопасный способ интеграции ваших проектов SourceCraft с ресурсами Yandex Cloud.

Создайте сервисное подключение с названием default-service-connection, используйте для него созданный ранее сервисный аккаунт с ролью compute.editor на каталог.

Важно

Действие гранта от SourceCraft, который выдается при создании сервисного подключения в персональной организации SourceCraft, не распространяется на сервисы Yandex Compute Cloud и Yandex Virtual Private Cloud.

Настройте CI/CD-процесс

Настройте CI/CD-процесс для развертывания пользовательского воркера.

Сконфигурируйте базовые параметры CI/CD

CI/CD-процесс настраивается в файле .sourcecraft/ci.yaml.

Представленная конфигурация CI/CD состоит из следующих рабочих процессов:

  • create-vm — создает ВМ с пользовательским воркером.
  • delete-vm — удаляет ВМ с пользовательским воркером.
  • test-task-and-delete-vm-async — выполняет тестовую задачу на пользовательском воркере и удаляет ВМ в асинхронном режиме.

Примечание

Рабочие процессы create-vm и delete-vm выполняются на стандартных облачных воркерах SourceCraft. Процесс test-task-and-delete-vm-async выполняется на пользовательском воркере.

Откорректируйте конфигурацию CI/CD под свои задачи или воспользуйтесь существующей.

Задайте параметры ВМ

Конфигурация ВМ для пользовательского воркера задается в блоке переменных env в файле .sourcecraft/ci.yaml:

  • COMPUTE_INSTANCE_NAME — название и имя хоста ВМ, например self-hosted-worker.
  • VPC_SUBNET_NAME — название подсети, созданной ранее, в которой будет размещена ВМ, например default-ru-central1-d.
  • CREATE_BOOT_DISK — образ диска, из которого будет создана ВМ, например image-folder-id=standard-images,image-family=ubuntu-2204-lts (Ubuntu 22.04 LTS). См. также Получить список публичных образов.
  • PLATFORM — платформа ВМ, например standard-v3.
  • MEMORY — количество RAM, например 64GB.
  • CORES — количество ядер vCPU, например 8.
  • CORE_FRACTION — гарантированная доля vCPU, например 100.
  • PREEMPTIBLE — указание, использовать ли прерываемую ВМ, например false.
  • SSH_PUB — созданный ранее секрет с публичной частью SSH-ключа в формате ${{ secrets.<название_секрета> }}. Задается на случай, если понадобится подключиться к ВМ с пользовательским воркером.

Создание пользователя ВМ с логином builder происходит в файле с метаданными metadata.yaml:

users:
- name: builder
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - ${SSH_PUB}

Откорректируйте конфигурацию ВМ под свои задачи или воспользуйтесь существующей.

Составьте скрипт установки пользовательского воркера и другого ПО на ВМ

Для установки исполняемого файла пользовательского воркера и другого программного обеспечения, например Docker, используется файл с метаданными metadata.yaml:

  - path: "/usr/local/etc/startup.sh"
    permissions: "755"
    content: |
      #!/bin/bash

      # install self-hosted-processor
      apt-get update
      apt-get install -y musl
      curl \
        --silent \
        --show-error \
        --location \
        https://storage.yandexcloud.net/src-processor-downloads/self-hosted-processor-latest/linux/amd64/self-hosted-processor \
        --output self-hosted-processor
      chmod +x self-hosted-processor
      mv self-hosted-processor /home/builder/sourcecraft
      chmod 777 -R /home/builder/sourcecraft

      # install docker
      apt install ca-certificates curl software-properties-common apt-transport-https -y
      install -m 0755 -d /etc/apt/keyrings
      curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
      echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
      apt update
      apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
      usermod -aG docker builder

При развертывании ВМ, в ней создается и выполняется bash-скрипт /usr/local/etc/startup.sh, который устанавливает исполняемый файл пользовательского воркера и Docker.

Откорректируйте скрипт установки под свои задачи или воспользуйтесь существующим.

Сконфигурируйте пользовательский воркер

Конфигурационный файл воркера config.yaml также настраивается в файле с метаданными metadata.yaml:

write_files:
  - path: "/home/builder/sourcecraft/config.yaml"
    permissions: "644"
    content: |
      executor_type: shell
      self_hosted:
        root_dir: /home/builder/sourcecraft/tmp
        max_slots: 3
      logger_type: json
      logger_level: info
      endpoint:
        host: ci.sourcecraft.tech
        port: 443
        ssl_no_verify: false
      auth:
        pat: ${PAT}

Проверьте работу воркера

Создайте ВМ с пользовательским воркером

Запустите вручную рабочий процесс create-vm.

Процесс создания можно контролировать по логам кубиков. При успешном завершении рабочего процесса созданную ВМ можно увидеть в консоли управления Yandex Cloud по ссылке из лога кубика create-vm.

Запустите тестовый рабочий процесс

  1. Запустите вручную рабочий процесс test-task-and-delete-vm-async.
  2. В задании test-task проверьте логи кубиков test-worker и test-docker:
    • В логах кубика test-worker должны отобразиться результаты выполнения команд uname -a и free -h, запущенных непосредственно на воркере.
    • В логах кубика test-docker должна отобразиться версия утилиты Yandex Cloud CLI, которая будет запущена в Docker-контейнере.

После выполнения задания test-task запустится задание delete (delete-vm-async), в котором будет предпринята попытка удалить ВМ в асинхронном режиме. Результат удаления можно увидеть в консоли управления Yandex Cloud по ссылке из лога кубика delete-vm.

Как удалить созданные ресурсы

Чтобы перестать платить за созданные ресурсы, запустите вручную рабочий процесс delete-vm или удалите ВМ с пользовательским воркером в интерфейсе Yandex Cloud.

При необходимости удалите сеть и подсеть.

См. также

Предыдущая
Хостинг статического сайта с помощью SourceCraft Sites
Следующая
Взаимосвязь ресурсов