Кэширование конвейера

Azure DevOps Services

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

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

Использование артефактов и кэширования

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

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

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

Задача кэша: как она работает

Кэширование добавляется в конвейер с помощью задачи "Кэш". Эта задача работает как любая другая задача и добавляется в steps раздел задания.

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

После выполнения всех шагов задания и при условии успешного состояния задания специальный шаг "Post-job: Cache" автоматически добавляется и активируется для каждого шага восстановления кэша, который не был пропущен. Этот шаг отвечает за сохранение кэша.

Настройка задачи кэша

Задача кэша имеет два обязательных аргумента: ключ и путь:

• путь: путь к папке для кэширования. Может быть абсолютным или относительным путем. Относительные пути разрешаются против $(System.DefaultWorkingDirectory).

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

• Строки:
  Фиксированное значение (например, имя кэша или имени средства) или взятое из переменной среды (например, текущее имя ОС или текущего задания).

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

  Совет

  Чтобы избежать обращения к сегменту строки типа пути, как путь к файлу, обтекайте его двойными кавычками, например: "my.key" | $(Agent.OS) | key.file

• Шаблоны файлов:
  Разделенный запятыми список шаблонов подстановочных знаков в стиле с запятыми, который должен соответствовать по крайней мере одному файлу. Например:

  • **/yarn.lock: все файлы yarn.lock в каталоге источников
  • */asset.json, !bin/**: все asset.json файлы, расположенные в каталоге источников, за исключением каталога bin

Содержимое любого файла, определяемого путем к файлу или шаблоном файла, хэшируется для создания ключа динамического кэша. Это полезно, если в проекте есть файлы, которые однозначно определяют, что кэшируется. Например, такие файлы, как package-lock.json, Gemfile.lockyarn.lockили Pipfile.lock обычно ссылаются на ключ кэша, так как все они представляют уникальный набор зависимостей.

Относительные пути к файлам или шаблоны файлов разрешаются для $(System.DefaultWorkingDirectory).

Пример:

Ниже приведен пример кэширования зависимостей, установленных Yarn:

variables:
  YARN_CACHE_FOLDER: $(Pipeline.Workspace)/s/.yarn

steps:
- task: Cache@2
  inputs:
    key: '"yarn" | "$(Agent.OS)" | yarn.lock'
    restoreKeys: |
       "yarn" | "$(Agent.OS)"
       "yarn"
    path: $(YARN_CACHE_FOLDER)
  displayName: Cache Yarn packages

- script: yarn --frozen-lockfile

В этом примере ключ кэша содержит три части: статическую строку (yarn), на которую выполняется задание, так как этот кэш является уникальным для каждой операционной системы, а хэш yarn.lock файла, который однозначно определяет набор зависимостей в кэше.

При первом запуске после добавления задачи шаг кэша сообщит о "промахе кэша", так как кэш, определенный этим ключом, не существует. После последнего шага кэш будет создан из файлов $(Pipeline.Workspace)/s/.yarn и отправлен. На следующем этапе кэша будет сообщаться о "попадании в кэш", а содержимое кэша будет загружено и восстановлено.

При использовании checkout: selfрепозиторий извлекается $(Pipeline.Workspace)/sи папка .yarn обычно находится в самом репозитории.

Восстановление ключей

restoreKeys можно использовать, если требуется запросить несколько точных ключей или префиксов ключей. Это используется для возврата к другому ключу в случае, если не key дает удара. Ключ восстановления выполняет поиск ключа по префиксу и дает последнюю созданную запись кэша в результате. Это полезно, если конвейер не может найти точное совпадение, но хочет использовать частичное попадание кэша. Чтобы вставить несколько ключей восстановления, разделите их с помощью новой строки, чтобы указать ключ восстановления (см. пример для получения дополнительных сведений). Порядок, в котором будут пытаться выполнить восстановление ключей, будут выполняться сверху вниз.

Обязательное программное обеспечение для локального агента

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

Пример:

Ниже приведен пример использования ключей восстановления Yarn:

variables:
  YARN_CACHE_FOLDER: $(Pipeline.Workspace)/.yarn

steps:
- task: Cache@2
  inputs:
    key: '"yarn" | "$(Agent.OS)" | yarn.lock'
    restoreKeys: |
       yarn | "$(Agent.OS)"
       yarn
    path: $(YARN_CACHE_FOLDER)
  displayName: Cache Yarn packages

- script: yarn --frozen-lockfile

В этом примере задача кэша пытается найти, существует ли ключ в кэше. Если ключ не существует в кэше, он пытается использовать первый ключ yarn | $(Agent.OS)восстановления. При этом выполняется поиск всех ключей, которые точно соответствуют этому ключу или имеют этот ключ в качестве префикса. При наличии другого yarn.lock хэш-сегмента может произойти попадание префикса. Например, если следующий ключ был в кэше, где old-yarn.lock получен хэш, отличный от хэшаyarn.lock, ключ yarn | $(Agent.OS) | old-yarn.lock восстановления даст частичный удар. Если на первом ключе восстановления отсутствует, он будет использовать следующий ключ восстановления, который попытается найти любой ключ yarn , который начинается с yarn. В случае попаданий префикса результат возвращает последний созданный ключ кэша в результате.

Изоляция кэша и безопасность

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

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

CI, вручную и запланированные запуски

Запуски запроса на вытягивание

Запуски запросов на вытягивание

Кондиционирование при восстановлении кэша

В некоторых сценариях успешное восстановление кэша должно привести к выполнению другого набора шагов. Например, шаг установки зависимостей можно пропустить, если кэш был восстановлен. Это возможно с помощью входных cacheHitVar данных задачи. Установка этого входного значения в имя переменной среды приводит к тому, что true переменная будет задана при попадании в кэш кэша восстановления, inexact в противном случае оно имеет значение false. Затем эту переменную можно ссылаться в условии шага или из скрипта.

В следующем примере install-deps.sh шаг пропускается при восстановлении кэша:

steps:
- task: Cache@2
  inputs:
    key: mykey | mylockfile
    restoreKeys: mykey
    path: $(Pipeline.Workspace)/mycache
    cacheHitVar: CACHE_RESTORED

- script: install-deps.sh
  condition: ne(variables.CACHE_RESTORED, 'true')

- script: build.sh

Средство увязки программ в пакеты

Для проектов Ruby с помощью Bundler переопределите BUNDLE_PATH переменную среды, используемую Пакетировщиком, чтобы задать путь Для поиска драгоценных камней.

Пример:

variables:
  BUNDLE_PATH: $(Pipeline.Workspace)/.bundle

steps:
- task: Cache@2
  displayName: Bundler caching
  inputs:
    key: 'gems | "$(Agent.OS)" | Gemfile.lock'
    path: $(BUNDLE_PATH)
    restoreKeys: | 
      gems | "$(Agent.OS)"
      gems   

Ccache (C/C++)

Ccache — это кэш компилятора для C/C++. Чтобы использовать Ccache в конвейере, убедитесь, что Ccache установлен и дополнительно добавлен в ваш PATH (см . режимы выполнения Ccache). Задайте для переменной CCACHE_DIR среды путь и $(Pipeline.Workspace) кэшируйте этот каталог.

Пример:

variables:
  CCACHE_DIR: $(Pipeline.Workspace)/ccache

steps:
- bash: |
    sudo apt-get install ccache -y    
    echo "##vso[task.prependpath]/usr/lib/ccache"
  displayName: Install ccache and update PATH to use linked versions of gcc, cc, etc

- task: Cache@2
  displayName: Ccache caching
  inputs:
    key: 'ccache | "$(Agent.OS)" | $(Build.SourceVersion)'
    path: $(CCACHE_DIR)
    restoreKeys: | 
      ccache | "$(Agent.OS)"

Дополнительные сведения см . в параметрах конфигурации Ccache.

Образы Docker

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

variables:
  repository: 'myDockerImage'
  dockerfilePath: '$(Build.SourcesDirectory)/app/Dockerfile'
  tag: '$(Build.BuildId)'

pool:
  vmImage: 'ubuntu-latest'
steps:
  - task: Cache@2
    displayName: Cache task
    inputs:
      key: 'docker | "$(Agent.OS)" | cache'
      path: $(Pipeline.Workspace)/docker
      cacheHitVar: CACHE_RESTORED                #Variable to set to 'true' when the cache is restored
    
  - script: |
      docker load -i $(Pipeline.Workspace)/docker/cache.tar
    displayName: Docker restore
    condition: and(not(canceled()), eq(variables.CACHE_RESTORED, 'true'))

  - task: Docker@2
    displayName: 'Build Docker'
    inputs:
      command: 'build'
      repository: '$(repository)'
      dockerfile: '$(dockerfilePath)'
      tags: |
        '$(tag)'

  - script: |
      mkdir -p $(Pipeline.Workspace)/docker
      docker save -o $(Pipeline.Workspace)/docker/cache.tar $(repository):$(tag)
    displayName: Docker save
    condition: and(not(canceled()), not(failed()), ne(variables.CACHE_RESTORED, 'true'))

• key: (обязательно) — уникальный идентификатор кэша.
• path: (обязательно) — путь к папке или файлу, который требуется кэшировать.

Golang

Для проектов Golang можно указать пакеты, которые нужно скачать в файле go.mod . GOCACHE Если переменная еще не задана, задайте для нее место загрузки кэша.

Пример:

variables:
  GO_CACHE_DIR: $(Pipeline.Workspace)/.cache/go-build/

steps:
- task: Cache@2
  inputs:
    key: 'go | "$(Agent.OS)" | go.mod'
    restoreKeys: | 
      go | "$(Agent.OS)"
    path: $(GO_CACHE_DIR)
  displayName: Cache GO packages

Gradle

Использование встроенной поддержки кэширования Gradle может оказать значительное влияние на время сборки. Чтобы включить кэш сборки, установите GRADLE_USER_HOME переменную среды в путь $(Pipeline.Workspace) и запустите сборку или --build-cache добавьте org.gradle.caching=true в gradle.properties файл.

Пример:

variables:
  GRADLE_USER_HOME: $(Pipeline.Workspace)/.gradle

steps:
- task: Cache@2
  inputs:
    key: 'gradle | "$(Agent.OS)" | **/build.gradle.kts' # Swap build.gradle.kts for build.gradle when using Groovy
    restoreKeys: |
      gradle | "$(Agent.OS)"
      gradle
    path: $(GRADLE_USER_HOME)
  displayName: Configure gradle caching

- task: Gradle@2
  inputs:
    gradleWrapperFile: 'gradlew'
    tasks: 'build'
    options: '--build-cache'
  displayName: Build

- script: |   
    # stop the Gradle daemon to ensure no files are left open (impacting the save cache operation later)
    ./gradlew --stop    
  displayName: Gradlew stop

• restoreKeys: резервные ключи, если первичный ключ завершается сбоем (необязательно)

Maven

Maven имеет локальный репозиторий, в котором хранятся скачивающие и созданные артефакты. Чтобы включить, задайте maven.repo.local для параметра путь в $(Pipeline.Workspace) папку и кэшируйте эту папку.

Пример:

variables:
  MAVEN_CACHE_FOLDER: $(Pipeline.Workspace)/.m2/repository
  MAVEN_OPTS: '-Dmaven.repo.local=$(MAVEN_CACHE_FOLDER)'

steps:
- task: Cache@2
  inputs:
    key: 'maven | "$(Agent.OS)" | **/pom.xml'
    restoreKeys: |
      maven | "$(Agent.OS)"
      maven
    path: $(MAVEN_CACHE_FOLDER)
  displayName: Cache Maven local repo

- script: mvn install -B -e

Если вы используете задачу Maven, обязательно передайте MAVEN_OPTS переменную, так как она перезаписывается в противном случае:

- task: Maven@4
  inputs:
    mavenPomFile: 'pom.xml'
    mavenOptions: '-Xmx3072m $(MAVEN_OPTS)'

.NET/NuGet

Если вы используете PackageReferences для управления зависимостями NuGet непосредственно в файле проекта и имеете packages.lock.json файл, можно включить кэширование, задав NUGET_PACKAGES переменную среды в путь $(UserProfile) и кэширование этого каталога. Дополнительные сведения о блокировке зависимостей см . в справочнике по пакетам в файлах проекта. Если вы хотите использовать несколько packages.lock.json, вы по-прежнему можете использовать следующий пример без внесения изменений. Содержимое всех файлов packages.lock.json будет хэшировано и при изменении одного из файлов создается новый ключ кэша.

Пример:

variables:
  NUGET_PACKAGES: $(Pipeline.Workspace)/.nuget/packages

steps:
- task: Cache@2
  inputs:
    key: 'nuget | "$(Agent.OS)" | $(Build.SourcesDirectory)/**/packages.lock.json'
    restoreKeys: |
       nuget | "$(Agent.OS)"
       nuget
    path: $(NUGET_PACKAGES)
  displayName: Cache NuGet packages

Node.js/npm

Существуют различные способы включения кэширования в проекте Node.js, но рекомендуется кэшировать общий каталог кэша npm. Этот каталог управляется npm и содержит кэшированную версию всех загруженных модулей. Во время установки npm сначала проверяет этот каталог (по умолчанию) для модулей, которые могут уменьшить или устранить сетевые вызовы к общедоступному реестру npm или к частному реестру.

Так как путь по умолчанию к каталогу общего кэша npm не совпадает на всех платформах, рекомендуется переопределить npm_config_cache переменную среды на путь.$(Pipeline.Workspace) Это также гарантирует, что кэш доступен из заданий контейнера и неконтейнеров.

Пример:

variables:
  npm_config_cache: $(Pipeline.Workspace)/.npm

steps:
- task: Cache@2
  inputs:
    key: 'npm | "$(Agent.OS)" | package-lock.json'
    restoreKeys: |
       npm | "$(Agent.OS)"
    path: $(npm_config_cache)
  displayName: Cache npm

- script: npm ci

Если в проекте нет package-lock.json файла, обратитесь package.json к файлу в входных данных ключа кэша.

Node.js/Yarn

Как и в npm, существуют различные способы кэширования пакетов, установленных с помощью Yarn. Рекомендуется кэшировать общую папку кэша Yarn. Этот каталог управляется Yarn и содержит кэшированную версию всех загруженных пакетов. Во время установки Yarn сначала проверяет этот каталог (по умолчанию) для модулей, что может уменьшить или исключить сетевые вызовы к общедоступным или частным реестрам.

Пример:

variables:
  YARN_CACHE_FOLDER: $(Pipeline.Workspace)/.yarn

steps:
- task: Cache@2
  inputs:
    key: 'yarn | "$(Agent.OS)" | yarn.lock'
    restoreKeys: |
       yarn | "$(Agent.OS)"
       yarn
    path: $(YARN_CACHE_FOLDER)
  displayName: Cache Yarn packages

- script: yarn --frozen-lockfile

Python/Anaconda

Настройте кэширование конвейера с помощью сред Anaconda:

Пример

variables:
  CONDA_CACHE_DIR: /usr/share/miniconda/envs

# Add conda to system path
steps:
- script: echo "##vso[task.prependpath]$CONDA/bin"
  displayName: Add conda to PATH

- bash: |
    sudo chown -R $(whoami):$(id -ng) $(CONDA_CACHE_DIR)
  displayName: Fix CONDA_CACHE_DIR directory permissions

- task: Cache@2
  displayName: Use cached Anaconda environment
  inputs:
    key: 'conda | "$(Agent.OS)" | environment.yml'
    restoreKeys: | 
      python | "$(Agent.OS)"
      python
    path: $(CONDA_CACHE_DIR)
    cacheHitVar: CONDA_CACHE_RESTORED

- script: conda env create --quiet --file environment.yml
  displayName: Create Anaconda environment
  condition: eq(variables.CONDA_CACHE_RESTORED, 'false')

• Windows

  - task: Cache@2
    displayName: Cache Anaconda
    inputs:
      key: 'conda | "$(Agent.OS)" | environment.yml'
      restoreKeys: | 
        python | "$(Agent.OS)"
        python
      path: $(CONDA)/envs
      cacheHitVar: CONDA_CACHE_RESTORED
  
  - script: conda env create --quiet --file environment.yml
    displayName: Create environment
    condition: eq(variables.CONDA_CACHE_RESTORED, 'false')
  

PHP/Composer

Для проектов PHP с помощью Composer переопределите переменную среды, используемую COMPOSER_CACHE_DIR composer.

Пример:

variables:
  COMPOSER_CACHE_DIR: $(Pipeline.Workspace)/.composer

steps:
- task: Cache@2
  inputs:
    key: 'composer | "$(Agent.OS)" | composer.lock'
    restoreKeys: |
      composer | "$(Agent.OS)"
      composer
    path: $(COMPOSER_CACHE_DIR)
  displayName: Cache composer

- script: composer install

Известные проблемы и отзывы

Если у вас возникли проблемы с настройкой кэширования для конвейера, проверьте список открытых проблем в репозитории microsoft/azure-pipelines-tasks . Если вашей проблемы нет в списке, создайте новую проблему и предоставьте необходимые сведения о сценарии.

Q&A

Вопрос. Можно ли очистить кэш?

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

key: 'yarn | "$(Agent.OS)" | yarn.lock'

На эту:

key: 'version2 | yarn | "$(Agent.OS)" | yarn.lock'

Вопрос. Когда истекает срок действия кэша?

Ответ. Срок действия кэша истекает через семь дней без действия.

Вопрос. Когда кэш отправляется?

Ответ. После последнего шага конвейера кэш будет создан из кэша path и отправлен. Дополнительные сведения см. в примере .

Вопрос. Существует ли ограничение на размер кэша?

Ответ. Нет принудительного ограничения на размер отдельных кэшей или общий размер всех кэшей в организации.