RFC for the export report: report.toml #70

matthewmcnew · 2020-04-01T17:05:34Z

Signed-off-by: Matthew McNew <mmcnew@pivotal.io>

jabrown85 · 2020-04-01T19:30:00Z

text/0000-export-report.md

+Here is an overview of the suggested schema for report.toml:
+
+```
+[image]


As discussed in the CNB group meeting, we may want to consider making this a bit more future proof to support multiple image output from a single build.

hone · 2020-04-01T19:32:22Z

text/0000-export-report.md

+# How it Works
+[how-it-works]: #how-it-works
+
+The export stage will write report.toml after exporting and caching is complete. There is no default path for report.toml as its location will be platform-specific. If the export steps fails to complete no report.toml is expected to be written.


I'm inclined to think this is generally useful for most platforms. I'm a big fan of setting a default path that could be overrideable instead.

I would suggest ./report.toml (or ./.toml) (similar to ./group.toml and ./analyzed.toml default paths) which generally resolves to /layers/report.toml given that the working dir is usually the layers dir.

We should call out that the default can be changes with an env var or overrode with an exporter flag.

Updated to default to the working directory.

hone · 2020-04-01T19:33:26Z

text/0000-export-report.md

+
+- How/if `pack` should expose this information to users in a programmatic way? 
+- Is there any additional metadata that should be provided in report.toml?
+- Is report the best name for this file and should it be marshaled into toml?


export.toml?

If this is an export report, could it include the layer usage/size/reuse(?) without needing to dig into the docker image itself.

Given we have an analyzed.toml, maybe exported.toml is the most consistent

I like exported.toml. Updated the rfc.

hone · 2020-04-01T19:47:27Z

Based on the Spec Changes RFC, do we need to add a [spec-changes] section?

- This is more consistent with the existing analyzed.toml - Default `exported.toml` to default into the working dir to be consistent with analyzed.toml Signed-off-by: Matthew McNew <mmcnew@pivotal.io>

jromero · 2020-04-08T19:18:34Z

text/0000-export-report.md

+```
+[image]
+tags = ["index.docker.io/image/name:latest", "index.docker.io/image/name:other-tag"]
+identifier = "sha256:c8be1b8f4d60d99c281fc2db75e0f56df42a83ad2f0b091621ce19357e19d853"


identifier appears to be generic. It would be nice to know if it's an Image ID (in the daemon case) or Digest (in the case of a registry).

hone · 2020-04-09T19:16:54Z

Adding this as a separate comment. This might be scope creep, but does it make sense to include other image/layer information like the layer usage/size/reuse(?) without needing to dig into the docker image itself.

matthewmcnew · 2020-04-16T19:08:55Z

Working group discussion on April 16th:

report.toml might be a more appropriate and extensible name than the export specific name: exported.toml. There is likely a need for another RFC to make the files produced by the lifecycle consistent and easy to aggregate into report.toml.
Layer usage/size/reuse would be a good candidate for report.toml as it is useful information that is not currently accessible elsewhere.
A general philosophy for report.toml is that it should contain information that is not accessible elsewhere. For example, the bill of materials should not be included as it is available as an image label and would be unnecessarily duplicated in report.toml.

cc @hone @ekcasey

Please let me know if I missed anything or misrepresented any part of our discussion.

- Add a bit of info about what should go in report.toml and what it should be used for. - Add docker daemon and registry schema examples - Docker Daemon builds will use the key image_id - Registry builds will use the key digest Signed-off-by: Matthew McNew <mmcnew@pivotal.io>

matthewmcnew · 2020-04-22T02:33:38Z

@hone @sclevine

Do you have thoughts on what layer info might look like in report.toml?

Perhaps, something like this?

[[layers]]
buildpack = "some_buildpack/ruby"
name = "mri"
on_export = "reused"
cached = true
launch = true
build = true
size = 17813

[[layers]]
buildpack = "some_buildpack/ruby"
name = "cache"
on_export = "cached"
cached = true
launch = false
build = false
size = 64811

Update: This additional layer metadata is out of scope for this RFC.

hone · 2020-04-29T19:12:36Z

text/0000-export-report.md

+# Unresolved Questions
+[unresolved-questions]: #unresolved-questions
+
+- How/if `pack` should expose this information to users in a programmatic way?


Do we want to resolve this before accepting the RFC or is that just a separate RFC?

As this is primarily requested to enable workflows in kubernetes like platforms that invoke the lifecycle directly, I would like to push that to a separate rfc if possible.

@jromero thoughts on inclusion in pack?

The only case in which we'd be likely to use this would be for something like the quiet option proposed where we'd silence the output of the lifecycle and only use the information provided by this file to output only the desired information. (This could have also been achieved via structured logging. 😄)

I would agree with @matthewmcnew that pack is not the primary target for this feature and hence fleshing that out isn't necessary.

@matthewmcnew can you put in here that this question is out of scope.

Updated to indicate that this is out of scope for this RFC

hone · 2020-04-29T19:13:17Z

text/0000-export-report.md

+[unresolved-questions]: #unresolved-questions
+
+- How/if `pack` should expose this information to users in a programmatic way?
+- Is there any additional metadata that should be provided in report.toml?


I'd still like to see the layer size info and like the toml structure you laid out. I can also see the argument of making that a separate RFC.

If you don't feel strongly about adding the layer sizing stuff in here, feel free to mark this as out of scope too.

Updated to indicate that this is out of scope for this RFC

ekcasey · 2020-05-06T19:29:40Z

@matthewmcnew Some of the proposed metadata additions here may over with #63, which solves part of the problem by adding all layer metadata to the exported image even if launch=false. It seems like we should move forward with the original proposal and follow up with another RFC to address other desirable build data.

Signed-off-by: Matthew McNew <mmcnew@pivotal.io>

nebhale · 2020-05-16T14:15:58Z

Entering Final Comment Period for merge disposition, closing 23 May, 2020.

mattmoor · 2020-05-16T17:21:43Z

text/0000-export-report.md

+image_id = "9c0e1895b90f"
+```
+
+By representing this in toml, we can extend this information with additional metadata when needed. A general philosophy for report.toml is that it should contain information that is not accessible elsewhere. For example, the bill of materials should not be included as it is available as an image label and would be unnecessarily duplicated in report.toml. 


Is there any decent tooling for extracting toml keys? Something like jq for toml?

Suppose what I wanted in a particular result file (e.g. in Tekton) was the image digest, what is the guidance for extracting particular keys?

You could use yj with jq. yj -t | jq -r .image.digest

This is what we've been doing in the heroku buildpacks.

[#70] Signed-off-by: Ben Hale <bhale@vmware.com>

matthewmcnew requested a review from a team as a code owner April 1, 2020 17:05

RFC for the export report

0e8b010

Signed-off-by: Matthew McNew <mmcnew@pivotal.io>

matthewmcnew force-pushed the export-report branch from ceaaa62 to 0e8b010 Compare April 1, 2020 19:09

jabrown85 reviewed Apr 1, 2020

View reviewed changes

hone reviewed Apr 1, 2020

View reviewed changes

Rename report.toml to exported.toml

291305e

- This is more consistent with the existing analyzed.toml - Default `exported.toml` to default into the working dir to be consistent with analyzed.toml Signed-off-by: Matthew McNew <mmcnew@pivotal.io>

matthewmcnew force-pushed the export-report branch from 7720be8 to 291305e Compare April 8, 2020 02:30

matthewmcnew changed the title ~~RFC for the export report.toml~~ RFC for the export report: exported.toml Apr 8, 2020

jromero reviewed Apr 8, 2020

View reviewed changes

nebhale requested review from a team April 22, 2020 18:03

matthewmcnew changed the title ~~RFC for the export report: exported.toml~~ RFC for the export report: report.toml Apr 22, 2020

hone reviewed Apr 29, 2020

View reviewed changes

Explicitly call out what is out of scope for this RFC

1fb77d6

Signed-off-by: Matthew McNew <mmcnew@pivotal.io>

hone approved these changes May 13, 2020

View reviewed changes

jkutner approved these changes May 13, 2020

View reviewed changes

ekcasey approved these changes May 13, 2020

View reviewed changes

hone mentioned this pull request May 14, 2020

Image exposes metadata for all layers that participated in an image's build #63

Closed

nebhale approved these changes May 15, 2020

View reviewed changes

nebhale added the Final Comment Period label May 16, 2020

mattmoor reviewed May 16, 2020

View reviewed changes

nebhale added a commit that referenced this pull request May 27, 2020

RFC #40

bb90fca

[#70] Signed-off-by: Ben Hale <bhale@vmware.com>

nebhale merged commit ae59745 into buildpacks:master May 27, 2020

ekcasey mentioned this pull request Jun 24, 2020

Specify report.toml buildpacks/spec#95

Closed

ekcasey mentioned this pull request Jul 8, 2020

Export report (report.toml) buildpacks/lifecycle#333

Closed

ekcasey removed the Final Comment Period label Oct 14, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC for the export report: report.toml #70

RFC for the export report: report.toml #70

matthewmcnew commented Apr 1, 2020

jabrown85 Apr 1, 2020

hone Apr 1, 2020

ekcasey Apr 3, 2020

matthewmcnew Apr 8, 2020

hone Apr 1, 2020

ekcasey Apr 3, 2020

matthewmcnew Apr 8, 2020

hone commented Apr 1, 2020

jromero Apr 8, 2020

hone commented Apr 9, 2020

matthewmcnew commented Apr 16, 2020

matthewmcnew commented Apr 22, 2020 •

edited

Loading

hone Apr 29, 2020

matthewmcnew Apr 29, 2020

hone Apr 30, 2020

jromero Apr 30, 2020

hone May 6, 2020

matthewmcnew May 7, 2020

hone Apr 29, 2020 •

edited

Loading

hone May 6, 2020

matthewmcnew May 7, 2020

ekcasey commented May 6, 2020

nebhale commented May 16, 2020

mattmoor May 16, 2020

matthewmcnew May 18, 2020 •

edited

Loading

hone May 18, 2020

mattmoor May 18, 2020

RFC for the export report: report.toml #70

RFC for the export report: report.toml #70

Conversation

matthewmcnew commented Apr 1, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hone commented Apr 1, 2020

Choose a reason for hiding this comment

hone commented Apr 9, 2020

matthewmcnew commented Apr 16, 2020

matthewmcnew commented Apr 22, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hone Apr 29, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ekcasey commented May 6, 2020

nebhale commented May 16, 2020

Choose a reason for hiding this comment

matthewmcnew May 18, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matthewmcnew commented Apr 22, 2020 •

edited

Loading

hone Apr 29, 2020 •

edited

Loading

matthewmcnew May 18, 2020 •

edited

Loading