Развертывание пользовательского (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 на главной странице сервиса или зарегистрируйтесь.

Необходимые платные ресурсыНеобходимые платные ресурсы

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

• плата за диск и запущенную ВМ (см. тарифы Yandex Compute Cloud);
• плата за использование внешнего IP-адреса (см. тарифы Yandex Virtual Private Cloud).

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

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Создайте репозиторий с конфигурацией CI/CD

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 на каталог.

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

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

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

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

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

• create-vm — создает ВМ с пользовательским воркером.
• delete-vm — удаляет ВМ с пользовательским воркером.
• 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
• Создать виртуальную машину с пользовательским скриптом конфигурации
• Получить список публичных образов
• Платформы
• Уровни производительности vCPU