From 79bed0960265e0bd01c58170fb53358249867d6a Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Tue, 14 Jul 2020 12:09:30 -0400 Subject: [PATCH] Specify build reproducibily Signed-off-by: Emily Casey --- platform.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/platform.md b/platform.md index a81fabc4..a8940d67 100644 --- a/platform.md +++ b/platform.md @@ -53,6 +53,7 @@ Examples of a platform might include: - [User-Provided Variables](#user-provided-variables) - [Launch Environment](#launch-environment) - [Caching](#caching) + - [Build Reproducibility](#build-reproducibility) - [Data Format](#data-format) - [Files](#files) - [`analyzed.toml` (TOML)](#analyzedtoml-toml) @@ -459,6 +460,9 @@ Usage: - `io.buildpacks.lifecycle.metadata`: see [lifecycle metadata label (JSON)](#lifecycle-metadata-label-(json)) - `io.buildpacks.project.metadata`: the value of which SHALL be the json representation `` - `io.buildpacks.build.metadata`: see [build metadata (JSON)](#build-metadata-label-(json)) +- To ensure [build reproducibility](#build-reproducibility), the lifecycle: + - SHOULD set the modification time of all files in newly created layers to a constant value + - SHOULD set the `created` time in image config to a constant value If a cache is provided the lifecycle: - SHALL write the contents of all cached layers to the cache @@ -545,6 +549,8 @@ Usage: - The value of `io.buildpacks.lifecycle.metadata` SHALL be modified as follows - `run-image.reference` SHALL uniquely identify `` - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` +- To ensure [build reproducibility](#build-reproducibility), the lifecycle: + - Set the `created` time in image config to a constant #### `launcher` Usage: @@ -660,6 +666,25 @@ If caching is enabled the platform is responsible for providing the lifecycle wi Whenever possible, the platform SHOULD provide the same cache to each rebuild of a given app image. Cache locality and availability MAY vary between platforms. +### Build Reproducibility +When given identical inputs all build and rebase operations: + - SHOULD produce app images with identical imageIDs + - **If** exporting directly to a registry + - SHOULD produce app images with identical manifest digests + - MAY output other non-reproducible artifacts + +To achieve reproducibility the lifecycle SHOULD set the following to a constant, rather than an accurate value: +- file modification times in generated layers +- image creation time + +Because compressions algorithms and manifest whitespace affect the image digest, an app image exported to the docker daemon and subsequently pushed to a registry MAY have a different digest than an app image exported directly to a registry by the lifecycle, even when all other inputs are held constant. + +If buildpacks do not generate layer contents or layer metadata reproducibly, builds MAY NOT be reproducibile even when identical source code and buildpacks are provided to the lifecycle. + +All app image labels SHOULD contain only reproducible values. + +For more information on build reproducibility see [https://reproducible-builds.org/](https://reproducible-builds.org/) + ## Data Format ### Files