github.com/coreos/rocket@v1.30.1-0.20200224141603-171c416fac02/Documentation/proposals/oci.md (about)

     1  ## OCI Image Format roadmap
     2  
     3  ### Background
     4  
     5  rkt currently implements the [appc specification][app-container] and therefore relies on the [ACI][aci] (Application Container Image) image format internally.
     6  
     7  [OCI][opencontainers] on the other hand defines a new [image format][oci] following a separate specification.
     8  This new specification differs considerably from rkt's internal ACI-based image format handling.
     9  
    10  The internal rkt image handling is currently divided in three subsystems:
    11  - **fetching**: This subsystem is responsible for downloading images of various types.
    12  Non-ACI image types (Docker and OCI) are converted to ACI images by delegating to [docker2aci][docker2aci]. The logic resides in the `github.com/rkt/rkt/rkt/image` package.
    13  
    14  - **image store**: The image store is responsible for persisting and managing downloaded images.
    15  It consists of two parts, a directory tree storing the actual image file blobs (usually residing under `/var/lib/rkt/cas/blob`) and a separate embedded SQL database storing image metadata usually residing in `/var/lib/rkt/cas/db/ql.db`. The implementation resides in the `github.com/rkt/rkt/store/imagestore` package.
    16  
    17  - **tree store**: Since dependencies between ACI images form a directed acyclic graph according to the [appc spec][ace-fs] they are pre-rendered in a directory called the tree store cache.
    18  If the [overlay filesystem](https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt) is enabled, the pre-rendered image is used as the `lowerdir` for the pod's rendered rootfs. The implementation resides in the `github.com/rkt/rkt/store/treestore` package.
    19  
    20  The actual internal lifecycle of an image is documented in the [architecture documentation][image-lifecycle].
    21  
    22  The following table gives an overview of the relevant differences between OCI and appc regarding image handling aspects:
    23  
    24   Aspect | OCI | ACI
    25  --------|-----|------------------
    26  Dependencies | Layers array in the [image manifest][oci-manifest] | [Dependency graph][ace-fs]
    27  Hash algorithms | Potentially multiple [algorithms][oci-algorithms], but SHA-256 preferred | [SHA-512][appc-image-id-type]
    28  
    29  Current ongoing work to support OCI in rkt is tracked in the following Github project: [https://github.com/rkt/rkt/projects/4](https://github.com/rkt/rkt/projects/4).
    30  
    31  ### Goals, non-Goals
    32  
    33  With the deprecation of the appc Spec (https://github.com/appc/spec#-disclaimer-) the current internal rkt architecture is not favorable any more.
    34  Currently rkt does support ACI, Docker, and OCI images, but the conversion step from OCI to ACI using `docker2aci` seems unnecessary.
    35  It introduces CPU and I/O bound overhead and is bound by semantical differences between the formats. For these reasons native support of OCI images inside rkt is envisioned.
    36  
    37  The goal therefore is to support OCI images natively next to ACI.
    38  rkt will continue to support the ACI image format and distribution mechanism.
    39  There is currently no plans to remove that support.
    40  
    41  This document outlines the following necessary steps and references existing work to transition to native OCI image support in rkt:
    42  
    43  1. Distribution points
    44  2. Reference based image handling
    45  3. Transport handlers
    46  4. Tree store support for OCI
    47  
    48  A non-goal is the implementation of the [OCI runtime specification][oci-runtime]. There is ongoing work in [https://github.com/rkt/rkt/issues/3408](https://github.com/rkt/rkt/issues/3408) covering this topic.
    49  
    50  ### Overview
    51  
    52  #### Distribution points
    53  
    54  rkt historically used the image name and heuristics around it to determine the actual image format type (appc, Docker, OCI).
    55  The concept of "distribution points" introduced a URI syntax that uniquely points to the different image formats including the necessary metadata (file location, origin URL, version, etc.).
    56  
    57  The URI scheme "cimd" (Container Image Distribution) was chosen to uniquely identify different image formats. The following CIMDs are currently supported:
    58  
    59  Name | Example
    60  -----|--------
    61  appc | `cimd:appc:v=0:coreos.com/etcd?version=v3.0.3&os=linux&arch=amd64`
    62  ACIArchive | `cimd:aci-archive:v=0:file%3A%2F%2Fabsolute%2Fpath%2Fto%2Ffile`
    63  Docker | `cimd:docker:v=0:busybox`
    64  
    65  The design document can be found in [Documentation/devel/distribution-point.md][distribution-point].
    66  
    67  ###### Status
    68  
    69  - The design document (https://github.com/rkt/rkt/pull/2953) is merged.
    70  - The implementation (https://github.com/rkt/rkt/pull/3369) is merged.
    71  
    72  ###### TODOs
    73  
    74  - Introduce a dedicated remote `cimd:oci` and potentially also a local `cimd:oci-layout` (see [github.com/opencontainers/image-spec/image-layout.md][oci-image-layout]) CIMD scheme.
    75  
    76  #### Reference based image handling
    77  
    78  The current image store implementation does not support different image formats. The blob image store only supports SHA-512.
    79  The ql backed SQL image store has a simple SQL scheme referencing only ACI images.
    80  
    81  In order to prepare native support for OCI the following changes need to be implemented:
    82  
    83  - Store the CIMD URI as a primary key in the current image store.
    84  - Support for multiple hash algorithms: Currently only SHA-512 is supported. OCI in addition needs SHA-256 and potentially other hash algorithms.
    85  - The database schema needs to be reworked to reflect multi-image support.
    86  
    87  ###### Status
    88  
    89  - The design and initial implementation is proposed in https://github.com/rkt/rkt/pull/3071.
    90  - The actual design document of the above PR can be found in [Documentation/proposals/reference_based_image_access_and_cas_store.md](https://github.com/rkt/rkt/blob/23313af1c3dac2fb24fe41f9a7c5eaca573e45dd/Documentation/proposals/reference_based_image_access_and_cas_store.md).
    91  
    92  Note that the above design document also suggests the introduction of a new key/value [Bolt](https://github.com/boltdb/bolt) based store. The current consensus is that the replacement of `ql` as the backing store can be done independently and therefore should be a non-goal for the OCI roadmap.
    93  
    94  ###### TODOs
    95  
    96  - Finalize the initial design proposal and implementation.
    97  
    98  #### Transport handlers
    99  
   100  Currently rkt directly fetches remote ACI based images or uses `docker2aci` to delegate non-ACI fetching.
   101  The current implementation makes it hard to integrate separate fetching subsystems due to the lack of any abstraction.
   102  
   103  ###### Status
   104  
   105  The current proposal is to abstract fetching logic behind "transport handlers" allowing for independent (potentially swappable) fetching implementations for the various image formats.
   106  
   107  - A first initial design is proposed in https://github.com/rkt/rkt/pull/2964.
   108  - The actual design document of the above PR can be found in [Documentation/proposal/fetchers_refactor.md](https://github.com/sgotti/rkt/blob/239fdff081f9fd47dd08834a5660a1375ea4771d/Documentation/proposal/fetchers_refactor.md).
   109  - A first initial implementation is proposed in https://github.com/rkt/rkt/pull/3232.
   110  
   111  Note that the initial design and implementation are in very early stage and should only be considered inspirational. 
   112  
   113  ###### TODOs
   114  
   115  - Fetching images remotely and locally from disk for all formats must be supported.
   116  - The current initial design proposal needs to be finalized.
   117  - The current fetcher logic needs to be abstracted allowing to introduce alternative libraries like https://github.com/containers/image to delegate fetching logic for OCI or Docker images.
   118  
   119  #### Tree store support for OCI
   120  
   121  The current tree store implementation is used for rendering ACI images only. A design document and initial implementation has to be created to prototype deflating OCI images and their dependencies.
   122  
   123  ###### Status
   124  
   125  Not started yet
   126  
   127  ### Risks
   128  
   129  Backwards compatibility: Currently the biggest concern identified is backwards compatibility/rollback capabilities. The proposed changes do not only imply simple schema changes in the `ql` backed database, but also intrusive schema and directory layout changes.
   130  
   131  [opencontainers]: https://www.opencontainers.org/
   132  [docker2aci]: https://github.com/appc/docker2aci
   133  [oci-runtime]: https://github.com/opencontainers/runtime-spec
   134  
   135  [aci]: https://github.com/appc/spec/blob/v0.8.11/spec/aci.md#app-container-image
   136  [ace-fs]: https://github.com/appc/spec/blob/v0.8.11/spec/ace.md#filesystem-setup
   137  [appc-image-id-type]: https://github.com/appc/spec/blob/v0.8.11/spec/types.md#image-id-type
   138  
   139  [oci]: https://github.com/opencontainers/image-spec
   140  [oci-manifest]: https://github.com/opencontainers/image-spec/blob/v1.0.0-rc2/manifest.md#image-manifest
   141  [oci-algorithms]: https://github.com/opencontainers/image-spec/blob/v1.0.0-rc2/descriptor.md#algorithms
   142  [oci-image-layout]: https://github.com/opencontainers/image-spec/blob/v1.0.0-rc2/image-layout.md
   143  
   144  [app-container]: https://github.com/rkt/rkt/blob/v1.30.0/Documentation/app-container.md
   145  [image-lifecycle]: https://github.com/rkt/rkt/blob/v1.30.0/Documentation/devel/architecture.md#image-lifecycle
   146  [distribution-point]: https://github.com/rkt/rkt/blob/v1.30.0/Documentation/devel/distribution-point.md