Almacenamiento en caché de las canalizaciones

Azure DevOps Services

El almacenamiento en caché de canalización puede ayudar a reducir el tiempo de compilación al permitir que las salidas o las dependencias descargadas de una ejecución se vuelvan a usar en ejecuciones posteriores, lo que reduce o evita el costo de volver a crear o volver a descargar los mismos archivos. El almacenamiento en caché es especialmente útil en escenarios en los que se descargan las mismas dependencias en el inicio de cada ejecución. Este suele ser un proceso lento que implica cientos o miles de llamadas de red.

El almacenamiento en caché puede ser eficaz al mejorar el tiempo de compilación siempre que el tiempo de restauración y guardar la caché sea menor que el tiempo para generar la salida de nuevo desde cero. Por este motivo, es posible que el almacenamiento en caché no sea eficaz en todos los escenarios y puede tener un impacto negativo en el tiempo de compilación.

Cuándo usar artefactos frente al almacenamiento en caché

El almacenamiento en caché de canalización y los artefactos de canalización realizan funciones similares, pero están diseñadas para diferentes escenarios y no deben usarse indistintamente.

• Use artefactos de canalización cuando necesite tomar archivos específicos generados en un trabajo y compartirlos con otros trabajos (y es probable que estos otros trabajos produzcan un error sin ellos).

• Use el almacenamiento en caché de canalización cuando desee mejorar el tiempo de compilación mediante la reutilización de archivos de ejecuciones anteriores (y no tener estos archivos no afectará a la capacidad del trabajo de ejecución).

Tarea de caché: cómo funciona

El almacenamiento en caché se agrega a una canalización mediante la tarea Caché. Esta tarea funciona como cualquier otra tarea y se agrega a la sección steps de un trabajo.

Cuando se encuentra un paso de caché durante una ejecución, la tarea restaura la memoria caché en función de las entradas proporcionadas. Si no se encuentra ninguna memoria caché, se completa el paso y se ejecuta el paso siguiente del trabajo.

Después de ejecutar todos los pasos del trabajo y asumir un estado de trabajo correcto, se agrega automáticamente un paso especial «Post-job: Cache» y se desencadena para cada paso de «caché de restauración» que no se omitió. Este paso es responsable de guardar la memoria caché.

Configurar la memoria caché

La tarea de caché tiene dos argumentos necesarios: clave y ruta de acceso:

• Ruta de acceso: la ruta de acceso de la carpeta que se va a almacenar en caché. Puede ser una ruta de acceso absoluta o relativa. Las rutas de acceso relativas se resuelven en $(System.DefaultWorkingDirectory).

• Clave: debe establecerse en el identificador de la memoria caché que desea restaurar o guardar. Las claves se componen de una combinación de valores de cadena, rutas de acceso de archivo o patrones de archivo, donde cada segmento está separado por un carácter |.

• Cadenas:
  Valor fijo (como el nombre de la memoria caché o un nombre de herramienta) o tomado de una variable de entorno (como el sistema operativo actual o el nombre del trabajo actual)

• Rutas de acceso a archivos:
  Ruta de acceso a un archivo específico cuyo contenido se aplicará un hash. Este archivo debe existir en el momento en que se ejecuta la tarea. Tenga en cuenta que cualquier segmento de clave que «tenga un aspecto similar a una ruta de acceso de archivo» se tratará como una ruta de acceso de archivo. En concreto, esto incluye segmentos que contienen un .. Esto podría producir un error en la tarea cuando este «archivo» no existe.

  Sugerencia

  Para evitar que un segmento de cadena similar a una ruta de acceso se trate como una ruta de acceso de archivo, encapsularlo con comillas dobles, por ejemplo: "my.key" | $(Agent.OS) | key.file

• Patrones de archivo:
  Lista separada por comas del patrón de caracteres comodín de estilo global que debe coincidir con al menos un archivo. Por ejemplo:

  • **/yarn.lock: todos los archivos yarn.lock en el directorio de origen
  • */asset.json, !bin/**: todos los archivos asset.json ubicados en un directorio en el directorio de origen, excepto en el directorio de bin

El contenido de cualquier archivo identificado por una ruta de acceso de archivo o un patrón de archivo se aplica un hash para generar una clave de caché dinámica. Esto es útil cuando el proyecto tiene archivos que identifican de forma única lo que se almacena en caché. Por ejemplo, normalmente se hace referencia a archivos como package-lock.json, yarn.lock, Gemfile.lock, o Pipfile.lock en una clave de caché, ya que todos representan un conjunto único de dependencias.

Las rutas de acceso de archivo relativas o los patrones de archivo se resuelven en $(System.DefaultWorkingDirectory).

Ejemplo:

Este es un ejemplo que muestra cómo almacenar en caché las dependencias instaladas por 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

En este ejemplo, la clave de caché contiene tres partes: una cadena estática ("yarn"), el sistema operativo en el que se ejecuta el trabajo, ya que esta caché es única por sistema operativo y el hash del archivo yarn.lock que identifica de forma única el conjunto de dependencias en la memoria caché.

En la primera ejecución después de agregar la tarea, el paso de caché notificará un error de caché, ya que la memoria caché identificada por esta clave no existe. Después del último paso, se creará una memoria caché a partir de los archivos de $(Pipeline.Workspace)/s/.yarn y se cargará. En la siguiente ejecución, el paso de caché notificará un «acierto de caché» y el contenido de la memoria caché se descargará y restaurará.

Al usar checkout: self, el repositorio se desprotege en $(Pipeline.Workspace)/s y la carpeta .yarn normalmente reside en el propio repositorio.

Restaurar claves

restoreKeys se puede usar si quiere consultar varias claves exactas o prefijos de clave. Esto se usa para revertir a otra clave en caso de que key no produzca un golpe. Una clave de restauración busca una clave por prefijo y genera la entrada de caché creada más reciente como resultado. Esto es útil si la canalización no puede encontrar una coincidencia exacta, pero quiere usar un acierto de caché parcial en su lugar. Para insertar varias claves de restauración, se delimitan mediante una nueva línea para indicar la clave de restauración (consulte el ejemplo para obtener más detalles). El orden en el que se probarán las claves de restauración será de arriba abajo.

Software necesario en el agente autohospedado

Los archivos ejecutables anteriores deben estar en una carpeta enumerada en la variable de entorno PATH. Tenga en cuenta que los agentes hospedados vienen con el software incluido, esto solo es aplicable a los agentes autohospedados.

Ejemplo:

Este es un ejemplo de cómo usar las claves de restauración de 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

En este ejemplo, la tarea de caché intenta buscar si la clave existe en la memoria caché. Si la clave no existe en la memoria caché, intenta usar la primera clave yarn | $(Agent.OS)de restauración. Con esto se intenta buscar todas las claves que coincidan exactamente con esa clave o que tengan esa clave como prefijo. Puede producirse un acierto de prefijo si había un segmento hash diferente yarn.lock. Por ejemplo, si la clave yarn | $(Agent.OS) | old-yarn.lock siguiente estaba en la memoria caché donde el old-yarn.lock produjo un hash diferente de yarn.lock, la clave de restauración producirá un acierto parcial. Si se produce un error en la primera clave de restauración, usará la siguiente clave yarn de restauración que intentará encontrar cualquier clave que comience por yarn. Para los aciertos de prefijos, el resultado generará la clave de caché creada más recientemente como resultado.

Aislamiento y seguridad de caché

Para garantizar el aislamiento entre las cachés de diferentes canalizaciones y diferentes ramas, cada caché pertenece a un contenedor lógico denominado ámbito. Los ámbitos proporcionan un límite de seguridad que garantiza que un trabajo de una canalización no puede acceder a las cachés de una canalización diferente y un trabajo que crea una solicitud de incorporación de cambios tiene acceso de lectura a las memorias caché de la rama de destino de la solicitud de incorporación de cambios (para la misma canalización), pero no puede escribir (crear) cachés en el ámbito de la rama de destino.

Cuando se encuentra un paso de caché durante una ejecución, se solicita la memoria caché identificada por la clave desde el servidor. A continuación, el servidor busca una memoria caché con esta clave de los ámbitos visibles para el trabajo y devuelve la memoria caché (si está disponible). Al guardar en caché (al final del trabajo), se escribe una caché en el ámbito que representa la canalización y la rama. Consulte a continuación para más información.

CI, manual y ejecuciones programadas

Ejecuciones de solicitudes de incorporación de cambios

Ejecuciones de bifurcación de solicitud de incorporación de cambios

Acondicionamiento en la restauración de caché

En algunos escenarios, la restauración correcta de la memoria caché debe provocar que se ejecute un conjunto diferente de pasos. Por ejemplo, se puede omitir un paso que instale las dependencias si se restauró la memoria caché. Esto es posible mediante la entrada de la tarea cacheHitVar. Si se crea esta entrada en el nombre de una variable de entorno, la variable pasará a ser true cuando se alcance una caché, inexact en un acierto de caché de claves de restauración; de lo contrario, pasará a ser false. A continuación, se puede hacer referencia a esta variable en una condición de paso o desde un script.

En el ejemplo siguiente, se omite el paso install-deps.sh cuando se restaura la memoria caché:

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

En el caso de los proyectos de Ruby que usan Bundler, invalide la variable de entorno BUNDLE_PATH usada por Bundler para establecer la ruta de Bundler en la que se buscará las gemas.

Ejemplo:

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 es una caché del compilador para C/C++. Para usar Ccache en la canalización, asegúrese de que Ccache esté instalado y, opcionalmente, se agregue a la PATH (consulte modos de ejecución de Ccache). Establezca la variable de entorno CCACHE_DIR en una ruta de acceso en $(Pipeline.Workspace) y almacene en caché este directorio.

Ejemplo:

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

Consulte Opciones de configuración de Ccache para obtener más detalles.

Imágenes de Docker

El almacenamiento en caché de imágenes de Docker reduce considerablemente el tiempo necesario para ejecutar la canalización.

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

• clave: (obligatorio): un identificador único para la memoria caché.
• ruta de acceso: (obligatorio): ruta de acceso de la carpeta o archivo que desea almacenar en caché.

Golang

En el caso de los proyectos de Golang, puede especificar los paquetes que se van a descargar en el archivo go.mod. Si la variable GOCACHE aún no está establecida, establézcala en la ubicación en la que desea que se descargue la memoria caché.

Ejemplo:

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

El uso de la compatibilidad integrada con el almacenamiento en caché de Gradle puede tener un impacto significativo en el tiempo de compilación. Para habilitar la memoria caché de compilación, establezca la variable de entorno GRADLE_USER_HOME en una ruta de acceso en $(Pipeline.Workspace) y ejecute la compilación con --build-cache o agregue org.gradle.caching=true al archivo gradle.properties.

Ejemplo:

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: las claves de reserva si se produce un error en la clave principal (opcional)

Maven

Maven tiene un repositorio local donde almacena descargas y artefactos creados. Para habilitarlo, establezca la opción maven.repo.local en una ruta de acceso en $(Pipeline.Workspace) y almacene en caché esta carpeta.

Ejemplo:

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

Si usa una tarea de Maven, asegúrese de pasar también la variable MAVEN_OPTS porque se sobrescribe de lo contrario:

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

.NET/NuGet

Si usa PackageReferences para administrar las dependencias de NuGet directamente en el archivo del proyecto y tiene un archivo packages.lock.json, puede habilitar el almacenamiento en caché estableciendo la variable de entorno NUGET_PACKAGES en una ruta de acceso en $(UserProfile) y almacenando en caché este directorio. Consulte Referencia de paquetes en archivos de proyecto para obtener más información sobre cómo bloquear las dependencias. Si desea usar varios archivos packages.lock.json, puede seguir usando el ejemplo siguiente sin realizar ningún cambio. En el contenido de todos los archivos packages.lock.json se aplicará un hash y, si se cambia uno de los archivos, se generará una nueva clave de caché.

Ejemplo:

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

Hay diferentes maneras de habilitar el almacenamiento en caché en un proyecto de Node.js, pero la manera recomendada es almacenar en caché el directorio de caché compartida de npm. Este directorio se administra mediante npm y contiene una versión almacenada en caché de todos los módulos descargados. Durante la instalación, npm comprueba primero este directorio (de forma predeterminada) para los módulos que pueden reducir o eliminar las llamadas de red al registro público npm o a un registro privado.

Dado que la ruta de acceso predeterminada al directorio de caché compartida de npm no es la misma en todas las plataformas, se recomienda invalidar la variable de entorno npm_config_cache en una ruta de acceso en $(Pipeline.Workspace). Esto también garantiza que la memoria caché sea accesible en trabajos de contenedor y que no sean de contenedor.

Ejemplo:

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

Si el proyecto no tiene un archivo package-lock.json, haga referencia al archivo package.json en la entrada de la clave de caché en su lugar.

Node.js/Yarn

Al igual que con npm, hay diferentes maneras de almacenar en caché los paquetes instalados con Yarn. La manera recomendada es almacenar en caché la carpeta de caché compartida de Yarn. Este directorio se administra mediante Yarn y contiene una versión almacenada en caché de todos los paquetes descargados. Durante la instalación, Yarn comprueba primero este directorio (de forma predeterminada) para los módulos, lo que puede reducir o eliminar las llamadas de red a registros públicos o privados.

Ejemplo:

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

Configure el almacenamiento en caché de la canalización con entornos de Anaconda:

Ejemplo

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

En el caso de los proyectos PHP que usen Composer, invalide la COMPOSER_CACHE_DIR variable de entorno usada por Composer.

Ejemplo:

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

Problemas conocidos y comentarios

Si tiene problemas al configurar el almacenamiento en caché para la canalización, compruebe la lista de problemas abiertos en el repositorio de microsoft/azure-pipelines-tasks. Si no ve el problema en la lista, cree uno nuevo y proporcione la información necesaria sobre su escenario.

Preguntas y respuestas

P: ¿Puedo borrar una memoria caché?

R: Actualmente no se admite borrar una memoria caché. Sin embargo, puede agregar un literal de cadena (como version2) a la clave de caché existente para cambiar la clave de una manera que evite los aciertos en las memorias caché existentes. Por ejemplo, cambie la siguiente clave de caché de esta:

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

Por esta otra:

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

P: ¿Cuándo expira una memoria caché?

R: Las memorias caché expiran después de siete días sin actividad.

P: ¿Cuándo se carga la memoria caché?

R: Después del último paso para la canalización, se creará una caché a partir de la memoria caché path y se cargará. Consulte el ejemplo para obtener más detalles.

P: ¿Existe un límite en el tamaño de una memoria caché?

R: No hay ningún límite aplicado en el tamaño de las cachés individuales o el tamaño total de todas las cachés de una organización.