OCI layout documentation #574
Conversation
Signed-off-by: Juan Bustamante <jbustamante@vmware.com>
Signed-off-by: Juan Bustamante <jbustamante@vmware.com>
- Ruby 3+ no longer includes webrick so it has to be explicitly required in the Gemfile for the app to start - See: https://bugs.ruby-lang.org/issues/17303 Signed-off-by: Tim Downey <tdowney@vmware.com>
Signed-off-by: Philipp Stehle <philipp.stehle@sap.com>
Signed-off-by: Juan Bustamante <jbustamante@vmware.com>
| </div> | ||
|
|
||
| Exporting to OCI layout format is an **experimental** feature available on pack since version X.Y.Z | ||
|
|
There was a problem hiding this comment.
I think we need a table somewhere comparing the cnb layout with the oci layout. The first question I'd ask as a user is "Which layout should I choose?", and such a table would contain enough "Why?" to answer which layout to choose.
| ```bash | ||
| cat ~/.pack/config.toml | ||
| experimental = true | ||
| layout-repo-dir = "<$HOME>/.pack/layout-repo" |
There was a problem hiding this comment.
Does pack config experimental true add the "layout-repo-dir" to config.toml?
| pack build oci:sample-app --path samples/apps/java-maven --builder cnbs/sample-builder:bionic | ||
| ``` | ||
|
|
||
| It will save the image in a folder `./sample-app` created in your current directory. |
There was a problem hiding this comment.
Why do we need layout-repo-dir if the OCI layout is saved to the PWD?
There was a problem hiding this comment.
We are using the layout-repo-dir to save the run-image on disk because actually invoking the lifecycle. When lifecycle is configured to use OCI layout it is expecting to have all the require inputs (like the run-image) on disk, because that should be transparent for users, we are saving those images in that particular folder.
| Before using this option we suggest to remove your local layout directory (the one configured in your pack config.toml with the key `layout-repo-dir`) and | ||
| your application image folder (if you are planning to use the same folder), the reason for this is pack doesn't remove the blobs saved in the `layout-repo-dir` if you use the `--sparse` flag |
There was a problem hiding this comment.
Here it becomes more unclear why layout-repo-dir was necessary above.
| If you are interested on keep playing with the image in OCI layout format, one tool you can take a look is [umoci](https://umo.ci/) it can help you to create a | ||
| [runtime bundler](https://github.com/opencontainers/runtime-spec) that can be executed with another tool like [runc](https://github.com/opencontainers/runc) |
There was a problem hiding this comment.
There a number of tools here that we might need to explain to end-users. I think we're using umoci because it is a strict-OCI compliant tool? That assembles an image. I presume that docker can also execute a strict-OCI image? If so, should we prefer to not introduce a new runtime there?
There was a problem hiding this comment.
Yeah, I had some doubts about including those tool, maybe we can suppose users know what they can do with the OCI layout format
| It will give you `application/vnd.oci.image.index.v1+json` media type, which is currently working | ||
|
|
||
| But [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane) | ||
|
|
||
| ```bash | ||
| crane pull <your-image> <dest> --format=oci | ||
| ``` | ||
| It will give you `application/vnd.docker.distribution.manifest.list.v2+json`, which will fail |
There was a problem hiding this comment.
Do these things pass/fail due to the state of our current implementation? Or because of a limitation in crane, or because the operation violates part of the OCI spec? Or for some other reason?
There was a problem hiding this comment.
agree, helpful to add a little more detail here
There was a problem hiding this comment.
It fails because of the state or our current implementation, it should be improve on new versions of the feature. I will add it
There was a problem hiding this comment.
Let me explain this part a little better so you can guide me on how to document it.
According to the RFC if you want to export your application image on disk, you need to mount to the lifecycle a local storage with the images require by the build process, for example, the run-image. This storage must contain images in OCI layout format and name resolution will follow some rules defined also in the RFC.
The documented part was based on a feedback provided by @natalieparellano here, which is basically the following scenario: Suppose you want to execute the lifecycle directly without using pack, for example, a platform implementor. They need to create this local storage and save everything there before executing the build, right?, well the problem is: If they save in the local storage a manifest list and then they execute the lifecycle, right now, we are not smart enough to detect which manifest we need to pick to execute the build.
That is the actual comment we want to document so users can take it into consideration, now I am not sure this is the right place to do it, or maybe I didn't write it correctly, so any advice will be appreciate!
| It will give you `application/vnd.oci.image.index.v1+json` media type, which is currently working | ||
|
|
||
| But [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane) | ||
|
|
||
| ```bash | ||
| crane pull <your-image> <dest> --format=oci | ||
| ``` | ||
| It will give you `application/vnd.docker.distribution.manifest.list.v2+json`, which will fail |
There was a problem hiding this comment.
agree, helpful to add a little more detail here
Co-authored-by: Joe Kimmel <86852107+joe-kimmel-vmw@users.noreply.github.com> Co-authored-by: Aidan Delaney <aidan.delaney@gmail.com> Signed-off-by: Juan Bustamante <jbustamante@vmware.com>
Maybe I can move the documentation under Feature section, put something like Experimental there?
|
|
What's the status on this one? Does it still need changes? |
Co-authored-by: Aidan Delaney <aidan.delaney@gmail.com> Signed-off-by: Juan Bustamante <jbustamante@vmware.com>
Signed-off-by: Juan Bustamante <jbustamante@vmware.com>
Signed-off-by: Juan Bustamante <jbustamante@vmware.com>
…ent-export-to-oci-layout OCI layout documentation
The following pull requests adds documentation on how to use the new experimental feature to export the application image to disk in OCI layout format
I added a new section Experimental under the Feature section a it looks like this:
fixes #529