Implement the capability to the phases to handle input/output images in OCI layout format

[jjbustamante]

Description

According to the export to OCI layout RFC

Add a new capability to the lifecycle (enabled by configuration) to resolve any image reference (input or output) to a disk location in OCI Image Layout format. It means, instead of interacting with a daemon or registry lifecycle will interact against the filesystem to read or write any image reference.

Proposed solution

The lifecycle phases affected by this new behavior are:

• Analyze
• Export
• Create

At a high level view the proposed solution can be summarized with the following system landscape diagram from the C4 model

Notice that we are relying on the OCI format Specification to expose the data for Platforms

The following new inputs are proposed to be added to these phases

Input	Environment Variable	Default Value	Description
<layout>	CNB_USE_OCI_LAYOUT	false	Enables the capability of resolving image from/to in OCI layout format on disk
<layout-dir>	CNB_OCI_LAYOUT_PATH	/layout-repo	Path to a directory where the images are saved in OCI layout format

Describe alternatives you've considered

• This is actually a new feature for the lifecycle, other alternatives were to export to a tarball, but this scenario will be considered in the near future. a new issue was created for that

Additional context

A folder on disk (accessible by the lifecycle) is required to execute the feature, this new folder works as a local registry and the content must be in OCI Image Layout format.

Let's suppose a directory exists and it has the following structure:

layout-repo
└── index.docker.io
    └── cnb
        └── my-full-stack-run:bionic
            └── bionic
                └── blobs
                    ├── sha256
                    │   ├── 1f59...944a // manifest
                    │   ├── 6388...af5a // config
                    │   ├── 824b...f984e
                    │   ├── f5f7...5b38
                    │   └── 870e...f1b09
                    ├── index.json
                    └── oci-layout

Let's see a couple of examples

Analyzing run-image

> export CNB_USE_LAYOUT=true
> /cnb/lifecycle/analyzer -run-image cnb/my-full-stack-run:bionic my-app-image

# OR

> /cnb/lifecycle/analyzer -layout -run-image cnb/my-full-stack-run:bionic my-app-image

expected analyzed.toml output

[run-image]
  reference = "<image reference>"
  name = "/layout-repo/index.docker.io/cnb/my-full-stack-run/bionic"

Export to OCI using run-image full saved on disk

> export CNB_USE_OCI_LAYOUT=true
> /cnb/lifecycle/exporter my-app-image

# OR

>  /cnb/lifecycle/exporter -layout my-app-image

The output will be written into the repository folder described above and it should looks like this:

layout-repo
└── index.docker.io
    ├── cnb
    │   └── my-full-stack-run:bionic
    │       └── bionic
    │           └── blobs
    │               ├── sha256
    │               │   ├── 1f59...944a // manifest
    │               │   ├── 6388...af5a // config
    │               │   ├── 824b...f984e
    │               │   ├── f5f7...5b38
    │               │   └── 870e...f1b09
    │               ├── index.json
    │               └── oci-layout
    └── library
        └── my-app-image
            └── latest
                ├── blobs
                │   └── sha256
                │       ├── 1bcd5..x               // app image manifest
                │       ├── 2f789..d               // app image config
                │       ├── 824b...f984e           // run layer
                │       ├── f5f7...5b38            // run layer
                │       ├── 870e...f1b09           // run layer
                │       └── 3g234..f               // buildpack layer
                ├── index.json
                └── oci-layout

As we can see, the application image my-app-image contains a full copy of the layers in its blobs folder.