Кэш задач

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

Например, для сборки Java приложения с помощью maven или gradle скачиваются из репозитория артефактов необходимые библиотеки (mavencentral). Такие библиотеки можно сохранить на машине, где запущен агент и переиспользовать их в тех задачах, в которых они необходимы.

Как работает кэширование

Основой кэширования для текущей версии агента, который использует Docker для выполнения задач конвейера, является общий для проекта том (Docker Volume). Для каждого экземпляра агента (виртуальной машины, на которой запущен агент) создается свой том для конкретного проекта. Данный том монтируется к каждому контейнеру, который запускается для выполнения конкретной задачи проекта. В каждом томе может храниться множество архивов, которые получаются из конкретной конфигурации кэша задачи.

Архивы с кэшем различаются названием, которое является хешем от строки, состоящей из ключей кэша. Последовательность ключей в конфигурации не важна, потому что перед тем, как получить хеш строки с ключами, список ключей сортируется. Если при конфигурировании кэша не указаны ключи для имени, то используется стандартное значение default.

Пример конфигурации кэша:

без ключей кэширования. В данном случае для ключа кэширования применится значение default.

cache:
  paths:
    - .m2/repository/

с ключами кэширования maven и build

cache:
  key:
    - maven
    - build
  paths:
    - .m2/repository/

Процесс работы задачи с кэшем

При запуске каждой задачи агентом, агент проверяет наличие доступного для работы кэша нужного для проекта. Если необходимый архив с кэшем найден, тогда этот архив распаковывается в рабочую директорию задачи. После завершения выполнения всех скриптов задачи агент ищет подходящие для кэширования файлы и папки, после этого эти файлы и папки упаковываются в архив, который отправляется на хранение в нужный для кэша том. Старый архив заменяется новым.

Отключение кэша для определенных задач

Если вы определяете кэш глобально для всего pipeline, каждое задание использует одно и то же определение. Вы можете переопределить это поведение для каждого job.

Чтобы полностью отключить его для job, используйте пустой список:

job:
  cache: []

Есть возможность отдельно конфигрурировать кэш для задачи: если для задачи указан кэш + пути (paths: ключевое слово, непустой массив путей), то эта конфигурация перезапишет глобальную для job, если нет (не указан кэш или пути), то будет использоваться глобальная для job, если таковая есть.

Ручной сброс кэша задач

Для ручного сброса кэша задач существует соответствующая кнопка. Эта кнопка доступна только пользователям с ролью Администратор и выше.

После использования данной функции будет сброшен кэш для всех новых задач, созданных после нажатия. Задачи, которые были созданы до применения данной функции будут использовать старый кэш.

Каждый раз, когда вы очищаете кэш вручную, обновляется внутреннее имя кэша. Старый кэш не удаляется. Вы можете самостоятельно удалить эти файлы из хранилища агента.

Конфигурирование распределенного кэша

По-умолчанию, кэш хранится на агентах только локально. Однако также существует распределенный кэш - механизм, позволяющий использовать один и тот же кэш на нескольких агентах.

Настройка распределенного кэша позволяет подключить к агенту объектное хранилище (на данный момент поддерживаются s3-объектные хранилища), которое и будет использоваться как хранилище для кэша.

Для настройки распределенного кэша необходимо указать следующие параметры в application.properties.

Параметр	Тип	Наличие	Описание
`runner.cache.type`	string	Обязательно	Тип хранилища. На данный момент поддерживается `s3`. Если параметр не указан или указано другое значение, кэш будет храниться только локально
`runner.cache.s3.server-address`	string	Обязательно	Адрес сервера, например `https://storage.yandexcloud.net`
`runner.cache.s3.access-key`	string	Обязательно	Идентификатор ключа доступа
`runner.cache.s3.secret-key`	string	Обязательно	Секретный ключ
`runner.cache.s3.bucket-name`	string	Обязательно	Название бакета. Он должен быть предварительно создан в объектном хранилище
`runner.cache.s3.region`	string	Обязательно	Регион сервера, например `ru-central1`
`runner.cache.s3.path`	string	Опционально	Префикс для объектов
`runner.cache.s3.shared`	boolean	Опционально	Определяет будет ли кэш, хранящийся для проекта по некоторому ключу, общим для разных агентов. Если `false`, то у агентов с разными UUID будет разный кэш. По умолчанию имеет значение `false`
`runner.cache.s3.max-uploaded-archive-size`	integer	Опционально	Максимальный размер загружаемого в S3 архива. Принимает значение в байтах. По умолчанию имеет значение 5 ГБ. Указанное значение не должно быть больше 5 ГБ и меньше 10 МБ. Если значение параметра превысило данную границу, то кэш будет хранится локально

Пример конфигурации application.properties

# обязательные параметры
runner.cache.type=s3
runner.cache.s3.server-address=https://storage.yandexcloud.net
runner.cache.s3.access-key=ACCESS_KEY
runner.cache.s3.secret-key=SECRET_KEY
runner.cache.s3.bucket-name=BUCKET_NAME
runner.cache.s3.region=ru-central1
# опциональные параметры
runner.cache.s3.shared=true
runner.cache.s3.path=distributed-runner-cache/shared
# устанавливает максимальный размер кеша, прогружаемый в s3, на значение 2 GB
runner.cache.s3.max-uploaded-archive-size=26843545608

Путь до кэша имеет следующий вид: {serverAddress}/{bucketName}/{path}/runner/{runnerUUID}/project/{projectUUID}/{cacheKey}

Если не указан параметр runner.cache.s3.path, тогда в пути будет отстутствовать /{path}.

Если параметр runner.cache.s3.shared = true, тогда в пути будет отстутствовать /runner/{runnerUUID}.