Memorizzazione nella cache della pipeline

Azure DevOps Services

La memorizzazione nella cache della pipeline consente di ridurre il tempo di compilazione consentendo di riutilizzare gli output o le dipendenze scaricate da un'esecuzione successiva, riducendo o evitando così il costo di ricreare o scaricare nuovamente gli stessi file. La memorizzazione nella cache è particolarmente utile negli scenari in cui le stesse dipendenze vengono scaricate ripetutamente all'inizio di ogni esecuzione. Si tratta spesso di un processo dispendioso in termini di tempo che coinvolge centinaia o migliaia di chiamate di rete.

La memorizzazione nella cache può essere efficace per migliorare il tempo di compilazione fornito il tempo necessario per ripristinare e salvare la cache è inferiore al tempo necessario per produrre nuovamente l'output da zero. Per questo motivo, la memorizzazione nella cache potrebbe non essere efficace in tutti gli scenari e potrebbe effettivamente avere un impatto negativo sul tempo di compilazione.

Quando usare artefatti contro memorizzazione nella cache

La memorizzazione nella cache della pipeline e gli artefatti della pipeline eseguire funzioni simili, ma sono progettate per scenari diversi e non devono essere usate in modo intercambiabile.

• Usare gli artefatti della pipeline quando è necessario acquisire file specifici prodotti in un processo e condividerli con altri processi (e questi altri processi avranno probabilmente esito negativo senza di essi).

• Usare la memorizzazione nella cache della pipeline quando si vuole migliorare il tempo di costruzione riutilizzando i file delle esecuzioni precedenti (e la mancanza di questi file non influisce sulla capacità di esecuzione del processo).

Attività cache: come funziona

La memorizzazione nella cache viene aggiunta a una pipeline utilizzando l'attività cache. Questa attività funziona come qualsiasi altra attività e viene inserita nella sezione steps di un incarico.

Quando viene rilevato un passaggio della cache durante un'esecuzione, l'attività ripristina la cache in base agli input forniti. Se non viene trovata alcuna cache, il passaggio viene completato e viene eseguito il passaggio successivo del processo.

Dopo che tutti i passaggi del processo sono stati eseguiti e presupponendo che un stato del processo abbia esito positivo, viene aggiunto e attivato automaticamente un passaggio speciale "Post-job: Cache" viene aggiunto e attivato per ogni passaggio "restore cache" che non è stato ignorato. Questo passaggio è responsabile del salvataggio della cache .

Configurare l'attività di Cache

L'attività della cache ha due argomenti obbligatori: chiave e percorso :

• percorso: percorso della cartella da memorizzare nella cache. Può essere un percorso assoluto o relativo. I percorsi relativi vengono determinati in $(System.DefaultWorkingDirectory).

• chiave: deve essere impostata sull'identificatore per la cache da ripristinare o salvare. Le chiavi sono costituite da una combinazione di valori stringa, percorsi di file o modelli di file, in cui ogni segmento è separato da un carattere |.

• stringhe:
  Valore fisso (ad esempio il nome della cache o un nome dello strumento) o tratto da una variabile di ambiente (ad esempio il sistema operativo corrente o il nome del processo corrente)

• percorsi di file:
  Percorso di un file specifico il cui contenuto verrà sottoposto a hashing. Questo file deve esistere al momento dell'esecuzione dell'attività. Tenere presente che qualsiasi segmento di chiave che "assomiglia a un percorso di file" verrà considerato come un percorso di file. In particolare, questo include segmenti contenenti un .. Ciò potrebbe causare un errore dell'attività qualora questo "file" non esistesse.

  Suggerimento

  Per evitare che un segmento di stringa simile al percorso venga trattato come un percorso di file, racchiuderlo tra virgolette doppie, ad esempio: "my.key" | $(Agent.OS) | key.file

• modelli di file:
  Elenco di pattern jolly di tipo glob separati da virgole che devono corrispondere ad almeno un file. Per esempio:

  • **/yarn.lock: tutti i file yarn.lock nella directory 'sources'
  • */asset.json, !bin/**: tutti i file asset.json che si trovano in una directory sotto alla directory sources, ad eccezione della directory bin

Il contenuto di qualsiasi file identificato da un percorso di file o da un modello di file viene sottoposto a hashing per produrre una chiave della cache dinamica. Ciò è utile quando il progetto include file che identificano in modo univoco ciò che viene memorizzato nella cache. Ad esempio, ai file come package-lock.json, yarn.lock, Gemfile.locko Pipfile.lock si fa comunemente riferimento in una chiave della cache, poiché rappresentano tutti un set univoco di dipendenze.

I percorsi di file o i modelli di file relativi vengono risolti in $(System.DefaultWorkingDirectory).

esempio:

Ecco un esempio che illustra come memorizzare nella cache le dipendenze installate da 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

In questo esempio la chiave della cache contiene tre parti: una stringa statica ("yarn"), il sistema operativo su cui è in esecuzione il processo poiché questa cache è univoca per ogni sistema operativo e l'hash del file yarn.lock che identifica in modo univoco il set di dipendenze nella cache.

Al primo esecuzione dopo l'aggiunta dell'attività, il passaggio della cache segnala un "mancato riscontro nella cache" perché la cache identificata da questa chiave non esiste. Dopo l'ultimo passaggio, verrà creata una cache dai file in $(Pipeline.Workspace)/s/.yarn e verrà caricata. All'esecuzione successiva, il passaggio della cache riporterà un "cache hit" e il contenuto della cache verrà scaricato e ripristinato.

Quando si usa checkout: self, il repository viene scaricato su $(Pipeline.Workspace)/se la cartella .yarn si trova in genere nel repository stesso.

Ripristinare chiavi

restoreKeys può essere usato se si desidera eseguire una query su più chiavi esatte o prefissi di chiave. Viene usato per fare il fallback a un'altra chiave nel caso in cui un key non dia risultati. Una chiave di ripristino effettua una ricerca per prefisso e restituisce l'ultimo elemento di cache creato come risultato. Ciò è utile se la pipeline non riesce a trovare una corrispondenza esatta, ma vuole usare invece un hit parziale della cache. Per inserire più chiavi di ripristino, delimitarle usando una nuova riga per indicare la chiave di ripristino (vedere l'esempio per altri dettagli). L'ordine in cui verranno tentate le chiavi di ripristino sarà dall'alto verso il basso.

Software necessario nell'agente autogestito

I file eseguibili precedenti devono trovarsi in una cartella elencata nella variabile di ambiente PATH. Tenere presente che gli agenti ospitati sono dotati del software incluso, questo è applicabile solo per gli agenti self-hosted.

Esempio:

Ecco un esempio di come usare le chiavi di ripristino da 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

In questo esempio l'attività della cache tenta di trovare se la chiave esiste nella cache. Se la chiave non esiste nella cache, tenta di usare la prima chiave di ripristino yarn | $(Agent.OS). In questo modo si tenta di cercare tutte le chiavi che corrispondono esattamente a tale chiave o a quella chiave come prefisso. Un colpo di prefisso può verificarsi se è presente un segmento hash yarn.lock diverso. Ad esempio, se la chiave seguente yarn | $(Agent.OS) | old-yarn.lock si trovava nella cache in cui il old-yarn.lock ha restituito un hash diverso rispetto a yarn.lock, la chiave di ripristino genererà un riscontro parziale. Se si verifica un errore nella prima chiave di ripristino, userà quindi la chiave di ripristino successiva yarn che tenterà di trovare qualsiasi chiave che inizia con yarn. Per i riscontri del prefisso, il risultato restituisce la chiave della cache creata più di recente.

Isolamento e sicurezza della cache

Per garantire l'isolamento tra cache da pipeline diverse e rami diversi, ogni cache appartiene a un contenitore logico denominato ambito. Gli ambiti forniscono un limite di sicurezza che garantisce:

1. Un lavoro da una pipeline non può accedere alle cache di un'altra pipeline e
2. Un processo che crea una richiesta pull ha accesso in lettura alle cache per il ramo di destinazione della richiesta pull (per la stessa pipeline), ma non può scrivere (creare) cache nell'ambito del ramo di destinazione.

Quando viene rilevato un passaggio della cache durante un'esecuzione, la cache identificata dalla chiave viene richiesta dal server. Il server cerca quindi una cache con questa chiave dagli ambiti visibili al processo e restituisce la cache (se disponibile). Al salvataggio della cache (alla fine del processo), una cache viene scritta nello spazio che rappresenta la pipeline e il ramo. Per altri dettagli, vedere di seguito.

Esecuzioni CI, manuali e pianificate

Esecuzioni delle richieste di pull

Esecuzioni della richiesta pull del fork

Configurazione per il ripristino della cache

In alcuni scenari, il ripristino corretto della cache deve causare l'esecuzione di un set diverso di passaggi. Ad esempio, un passaggio che installa le dipendenze può essere ignorato se la cache è stata ripristinata. Ciò è possibile usando l'input dell'attività cacheHitVar. Se si configura questo input con il nome di una variabile di ambiente, la variabile viene impostata su true in caso di riscontro nella cache, su inexact in caso di successo della cache della chiave di ripristino; altrimenti viene impostata su false. È quindi possibile fare riferimento a questa variabile in una condizione del passaggio o dall'interno di uno script.

Nell'esempio seguente il passaggio install-deps.sh viene ignorato quando viene ripristinata la cache:

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

Bundler

Per i progetti Ruby che utilizzano Bundler, eseguire l'override della variabile di ambiente BUNDLE_PATH usata da Bundler per impostare il percorso in cui Bundler cerca le Gems.

esempio:

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 è una cache del compilatore per C/C++. Per usare Ccache nella pipeline, assicurati che Ccache sia installato e, facoltativamente, aggiunto a PATH (vedi le modalità d'esecuzione di Ccache in ). Impostare la variabile di ambiente CCACHE_DIR su un percorso sotto $(Pipeline.Workspace) e memorizzare nella cache questa directory.

Esempio:

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)"

Per maggiori dettagli, vedere impostazioni di configurazione di Ccache.

Immagini Docker

La memorizzazione nella cache delle immagini Docker riduce notevolmente il tempo necessario per eseguire la pipeline.

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'))

• chiave: (obbligatorio) - identificatore univoco per la cache.
• percorso: (obbligatorio) - percorso della cartella o del file da memorizzare nella cache.

Golang

Per i progetti Golang, è possibile specificare i pacchetti da scaricare nel file go.mod. Se la variabile GOCACHE non è già impostata, impostarla su dove si vuole scaricare la cache.

esempio:

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

L'uso di Gradle supporto predefinito per la memorizzazione nella cache può avere un impatto significativo sul tempo di compilazione. Per abilitare la cache di compilazione, impostare la variabile di ambiente GRADLE_USER_HOME su un percorso in $(Pipeline.Workspace) e quindi eseguire la compilazione con --build-cache o aggiungere org.gradle.caching=true al file gradle.properties.

Esempio:

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: Le chiavi di fallback se la chiave primaria non riesce (facoltativo)

Intenditore

Maven ha un repository locale in cui archivia i download e gli artefatti compilati. Per abilitare, impostare l'opzione maven.repo.local su un percorso in $(Pipeline.Workspace) e memorizzare nella cache questa cartella.

esempio:

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

Se stai usando un compito Maven, assicurati di passare anche la variabile MAVEN_OPTS perché altrimenti viene sovrascritta.

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

.NET/NuGet

Se utilizzi PackageReferences per gestire le dipendenze NuGet direttamente all'interno del file di progetto e possiedi un file packages.lock.json, puoi abilitare il caching impostando la variabile di ambiente NUGET_PACKAGES su un percorso sotto $(UserProfile) e cacheare questa directory. Per altre informazioni su come bloccare le dipendenze, vedere informazioni di riferimento sui pacchetti nei file di progetto. Se si desidera usare più packages.lock.json, è comunque possibile usare l'esempio seguente senza apportare alcuna modifica. Il contenuto di tutti i file packages.lock.json verrà sottoposto a hashing e, se uno dei file viene modificato, viene generata una nuova chiave della cache.

Esempio:

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

Questo approccio è valido anche per i progetti .NET Core se il progetto usa packages.lock.json per bloccare le versioni dei pacchetti. È possibile abilitare questa opzione impostando su nel file Csproj oppure usando il comando seguente: .

Node.js/npm

Esistono diversi modi per abilitare la memorizzazione nella cache in un progetto Node.js, ma è consigliabile memorizzare nella cache la directory della cache condivisa di npm . Questa directory è gestita da npm e contiene una versione memorizzata nella cache di tutti i moduli scaricati. Durante l'installazione, npm controlla prima questa directory (per impostazione predefinita) per i moduli che possono ridurre o eliminare le chiamate di rete al registro npm pubblico o a un registro privato.

Poiché il percorso predefinito della directory cache condivisa di npm è non uguale in tutte le piattaforme, è consigliabile eseguire l'override della variabile di ambiente npm_config_cache a un percorso in $(Pipeline.Workspace). Ciò garantisce anche che la cache sia accessibile dai lavori in container e non in container.

Esempio:

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

Se il progetto non ha un file package-lock.json, invece fare riferimento al file package.json nell'input della chiave della cache.

Node.js/Yarn

Analogamente a npm, esistono diversi modi per memorizzare nella cache i pacchetti installati con Yarn. Il modo consigliato consiste nel memorizzare nella cache la cartella cache condivisa di Yarn . Questa directory è gestita da Yarn e contiene una versione memorizzata nella cache di tutti i pacchetti scaricati. Durante l'installazione, Yarn verifica prima questa directory (per impostazione predefinita) alla ricerca dei moduli, il che può ridurre o eliminare le chiamate di rete verso i registri pubblici o privati.

Esempio:

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

Configurare la memorizzazione nella cache della pipeline con gli ambienti Anaconda:

Esempio

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

Per i progetti PHP che usano Composer, eseguire l'override della variabile di ambiente COMPOSER_CACHE_DIR usata da Composer.

Esempio:

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

Problemi noti e feedback

Se riscontri problemi nell'impostazione della cache per la pipeline, guarda l'elenco di problemi aperti nel repository microsoft/azure-pipelines-tasks. Se non vedi il tuo problema elencato, crearne uno nuovo e fornire le informazioni necessarie sul tuo scenario.

Q&A

D: È possibile cancellare una cache?

R: La cancellazione di una cache non è attualmente supportata. È tuttavia possibile aggiungere una stringa letterale (ad esempio version2) alla chiave della cache esistente per modificare la chiave in modo da evitare riscontri nelle cache esistenti. Ad esempio, modificare la chiave della cache seguente da questo:

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

A questo scopo:

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

D: Quando scade una cache?

R: Le cache scadono dopo sette giorni di assenza di attività.

D: Quando viene caricata la cache?

R: Dopo l'ultimo passaggio della tua pipeline, verrà creata una cache dalla cache path e successivamente caricata. Per altri dettagli, vedere l'esempio di .

D: Esiste un limite per le dimensioni di una cache?

R: Non esiste alcun limite applicato alle dimensioni delle singole cache o alle dimensioni totali di tutte le cache in un'organizzazione.