Skip to content

Latest commit

 

History

History
84 lines (62 loc) · 4.47 KB

0103-source-date-epoch.md

File metadata and controls

84 lines (62 loc) · 4.47 KB

Meta

  • Name: Use SOURCE_DATE_EPOCH to configure image create time
  • Start Date: 2022-02-24
  • Author(s): natalieparellano
  • Status: Implemented
  • RFC Pull Request: rfcs#204
  • CNB Pull Request: (leave blank)
  • CNB Issue: buildpacks/lifecycle#809
  • Supersedes: (put "N/A" unless this replaces an existing RFC, then link to that RFC)

Summary

To allow for build reproducibility, images created by Cloud Native Buildpacks have a hard-coded create time of January 1, 1980. We have received requests from the community (see here and here) to allow for this value to be configurable. This RFC proposes making the value configurable by setting SOURCE_DATE_EPOCH in the lifecycle's execution environment during export.

Definitions

  • build reproducibility: identical inputs should produce identical outputs (blog post)
  • SOURCE_DATE_EPOCH: a "standardised environment variable that distributions can set centrally and have build tools consume this in order to produce reproducible output" (see here)

Motivation

  • Why should we do this? Users have asked for it
  • What use cases does it support? A meaningful image create time, e.g., the ability to determine which images are most recent
  • What is the expected outcome? Images built with SOURCE_DATE_EPOCH set will not be reproducible, as the config blob will change

What it is

  • Define the target persona: buildpack user, platform operator

    • A buildpack user could pass a flag to pack to set SOURCE_DATE_EPOCH to the current time in the lifecycle's execution environment during export.
    • A platform operator could choose to set SOURCE_DATE_EPOCH whenever export is run.

  • If applicable, describe the differences between teaching this to existing users and new users. We should mention this feature in the lifecycle release notes and docs.

How it Works

This PR to imgutil would read the environment variable at the point of saving the image. An alternative implementation could be to have the exporter read the variable and provide it via a new SetCreatedAt() method on the imgutil.Image interface. The latter might be safer as it would avoid unintended side effects for other consumers of imgutil (e.g., pack).

Drawbacks

Why should we not do this?

Platforms that choose to set SOURCE_DATE_EPOCH to real creation time will not have 100% reproducible builds.

Alternatives

  • What other designs have been considered?
    • Doing nothing
    • Allowing layer timestamps to also be configurable, but this would effectively prohibit launch layer re-use and make builds slower
  • Why is this proposal the best?
    • It is easy to implement, easy to use, and solves for the desired use case
  • What is the impact of not doing this?
    • The lack of meaningful image create times makes it difficult to automate cleanup of images and could be a deal breaker for some users

Prior Art

  • See under "Reading the variable" here
  • ko
  • jib

Unresolved Questions

  • What parts of the design do you expect to be resolved before this gets merged?
    • Should we require users to be on platform api 0.9 in order to use this feature? (Opinion: no, because this feature is invisible if the environment variable is not set. The motivation for spec'ing this in the platform api is to make it clear for platform operators how to use it.)
  • What parts of the design do you expect to be resolved through implementation of the feature?
    • Should we do this in imgutil or the lifecycle? (see above)

Spec. Changes (OPTIONAL)

See spec PR.