You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/docs/buildpack-author-guide/caching-strategies.md
+12-12Lines changed: 12 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ In this section we look at caching each layer type.
22
22
23
23
## Layer Metadata
24
24
25
-
Buildpacks ensure byte-for-byte reproducibility of layers. File creation time is normalized to January 1, 1980 to ensure reproducibility. Byte-for-byte reproducibility means previous layers can be reused. However, we want to invalidate previously cached layers if
25
+
buildpacks ensure byte-for-byte reproducibility of layers. File creation time is [normalized to January 1, 1980](https://medium.com/buildpacks/time-travel-with-pack-e0efd8bf05db) to ensure reproducibility. Byte-for-byte reproducibility means previous layers can be reused. However, we want to invalidate previously cached layers if
26
26
27
27
* the buildpacks API changes,
28
28
* the type of the layer changes.
@@ -42,24 +42,24 @@ Caching during the production of an application image is necessarily very flexib
42
42
43
43
1. Check that the metadata of the cached layer is current,
44
44
2. Create an empty layer, and
45
-
3. Set `Launch = true`.
45
+
3. Set `launch = true`.
46
46
47
-
This will guarantee that the previously published application image layer in the registry is re-used if the layer metadata matches the requested metadata. In this most straightforward use-case `Launch` is `true` and both `Build` and `Cache` are set to `false`. That is to say, the most common case is where `Cache = false`, `Build = false` and `Launch = true`. It is important to note that the layer is re-used on the OCI registry. This avoids expensive rebuilds of the layer and expensive pulls of the layer to the host running the build.
47
+
This will guarantee that the previously published application image layer in the registry is re-used if the layer metadata matches the requested metadata. In this most straightforward use-case `launch` is `true` and both `build` and `cache` are set to `false`. That is to say, the most common case is where `cache = false`, `build = false` and `launch = true`. It is important to note that the layer is re-used on the OCI registry. This avoids expensive rebuilds of the layer and expensive pulls of the layer to the host running the build.
48
48
49
-
Setting `Build = true` makes a layer available to subsequent buildpacks. Therefore binaries installed to the `bin` directory on a `Build = true` layer are available to subsequent buildpacks during the build phase. It is also the case that `lib` directories on a `Build = true` later are added to the `LD_LIBRARY_PATH` during the build phase of subsequent buildpacks. Environment variables defined in a `Build = true` layer are similarly available. For any layer where `Launch = true` and `Build = true`, a launch layer from the OCI registry can no longer be reused. Instead, the layer must be made available locally so that subsequent buildpacks can use it.
49
+
Setting `build = true` makes a layer available to subsequent buildpacks. Therefore binaries installed to the `bin` directory on a `build = true` layer are available to subsequent buildpacks during the build phase. It is also the case that `lib` directories on a `build = true` later are added to the `LD_LIBRARY_PATH` during the build phase of subsequent buildpacks. Environment variables defined in a `build = true` layer are similarly available. For any layer where `launch = true` and `build = true`, a launch layer from the OCI registry can no longer be reused. Instead, the layer must be made available locally so that subsequent buildpacks can use it.
50
50
51
-
Setting `Cache = true` allows additional fine-grained control over caching. The `Cache = true` flag caches a layer and allows a buildpack to make _content_ level decisions about the validity of the cache (as opposed to using the less granular metadata). As an example, suppose a layer where `Launch = true` installs a `jq` binary with version `1.5` and sets `version=1.5` in the layer metadata. By default, this layer will not be re-used from the registry when a buildpack requests `jq` with `version=1.6` to be installed. However, setting `Cache = true` makes a previously built layer available during the build. A buildpack could then prefer to implement logic to restore `jq` with `version=1.5` instead of performing a potentially expensive download of `jq` with `version=1.6`. The `Cache = true` setting allows for cache validation decisions to be made at a level of granularity that is much finer grained than layer metadata.
51
+
Setting `cache = true` allows additional fine-grained control over caching. The `cache = true` flag caches a layer and allows a buildpack to make _content_ level decisions about the validity of the cache (as opposed to using the less granular metadata). As an example, suppose a layer where `launch = true` installs a `jq` binary with version `1.5` and sets `version=1.5` in the layer metadata. By default, this layer will not be re-used from the registry when a buildpack requests `jq` with `version=1.6` to be installed. However, setting `cache = true` makes a previously built layer available during the build. A buildpack could then prefer to implement logic to restore `jq` with `version=1.5` instead of performing a potentially expensive download of `jq` with `version=1.6`. The `cache = true` setting allows for cache validation decisions to be made at a level of granularity that is much finer grained than layer metadata.
52
52
53
-
Setting `Cache = false`, `Build = false`, and `Launch = true` is the most common configuration. If `Cache = false`, `Build = false`, and `Launch = true` is not appropriate for your layer, then `Cache = true`, `Build = true`, and `Launch = true` should be the next combination to evaluate:
53
+
Setting `cache = false`, `build = false`, and `launch = true` is the most common configuration. If `cache = false`, `build = false`, and `launch = true` is not appropriate for your layer, then `cache = true`, `build = true`, and `launch = true` should be the next combination to evaluate:
54
54
55
-
* When `Cache = true, Build = true, Launch = true`, explicitly setting `Build = true` makes the layer available, to subsequent buildpacks, during the build phase. As `Cache = true` the layer is restored from local cache before proceeding to the build phase. For example, a Python distribution could be provided in a cached, build and launch layer. The build phase could verify that the restored cached version of the Python distribution contains Python 3.10 but disregard the patch number of the Python interpreter.
56
-
*`Cache = true, Build = true, Launch = true` is an appropriate setting for a layer providing a distribution or runtime such as a Python interpreter or NodeJS runtime.
55
+
* When `cache = true, build = true, launch = true`, explicitly setting `build = true` makes the layer available, to subsequent buildpacks, during the build phase. As `cache = true` the layer is restored from local cache before proceeding to the build phase. For example, a Python distribution could be provided in a cached, build and launch layer. The build phase could verify that the restored cached version of the Python distribution contains Python 3.10 but disregard the patch number of the Python interpreter.
56
+
*`cache = true, build = true, launch = true` is an appropriate setting for a layer providing a distribution or runtime such as a Python interpreter or NodeJS runtime.
57
57
58
58
Other common configurations include
59
59
60
-
*`Cache = true, Build = false, Launch = true` Allows the same caching behavior as `Cache = true, Build = true, Launch = true`, but the layer is not available to subsequent buildpacks. For example, the build phase can restore a Python distribution disregarding the patch number of the `major.minor.patch` number stored in the metadata. As `Build = false` the python interpreter is unavailable to subsequent Buildpacks.
61
-
*`Cache = true, Build = true, Launch = false` This configuration is useful where a build time dependency is provided. For example, a JDK could be provided as a cached build layer that is not added as a launch layer. Instead, a JRE could be provided as a launch layer in the application image.
62
-
*`Cache = true, Build = false, Launch = false` This configuration is particularly useful in layers that download resources. Using a cache-only layer supports allows a buildpack to re-use cached downloads during installation. For example, pip wheels could be downloaded as a cache-only layer and the same buildpack could install the wheels in to a launch layer.
60
+
*`cache = true, build = false, launch = true` Allows the same caching behavior as `cache = true, build = true, launch = true`, but the layer is not available to subsequent buildpacks. For example, the build phase can restore a Python distribution disregarding the patch number of the `major.minor.patch` number stored in the metadata. As `build = false` the python interpreter is unavailable to subsequent buildpacks.
61
+
*`cache = true, build = true, launch = false` This configuration is useful where a build time dependency is provided. For example, a JDK could be provided as a cached build layer that is not added as a launch layer. Instead, a JRE could be provided as a launch layer in the application image.
62
+
*`cache = true, build = false, launch = false` This configuration is particularly useful in layers that download resources. Using a cache-only layer supports allows a buildpack to re-use cached downloads during installation. For example, pip wheels could be downloaded as a cache-only layer and the same buildpack could install the wheels in to a launch layer.
63
63
64
-
There are other boolean combinations of Cache, Build and Launch. These provide significant flexibility in the caching system. Users of less common caching strategies need a good understanding of the [buildpacks specification on Layer Types](https://github.com/buildpacks/spec/blob/main/buildpack.md#layer-types
64
+
There are other boolean combinations of cache, build and launch. These provide significant flexibility in the caching system. Users of less common caching strategies need a good understanding of the [buildpacks specification on Layer Types](https://github.com/buildpacks/spec/blob/main/buildpack.md#layer-types
0 commit comments