github.com/dctrud/umoci@v0.4.3-0.20191016193643-05a1d37de015/doc/site/reference/architecture.md (about)

     1  +++
     2  title = "Architecture"
     3  weight = 20
     4  +++
     5  
     6  umoci is a fairly simple tool, that takes advantage of a couple of tricks in
     7  order to allow for modification of OCI images. This architecture document is
     8  fairly high-level and will likely change once some more of the
     9  [roadmap][roadmap.md] is implemented. If you feel something is missing from
    10  this document, feel free to [contribute][contributing.md].
    11  
    12  When umoci was first released, I also published [a blog post][blog] outlying
    13  the original architecture (which has remained fairly similar over time).
    14  
    15  [roadmap.md]: /doc/roadmap.md
    16  [contributing.md]: /contributing
    17  [blog]: https://www.cyphar.com/blog/post/umoci-new-oci-image-tool
    18  
    19  ### Manifests ###
    20  
    21  The key feature of umoci is that it allows for generation of delta layers
    22  without the need for copies of the original root filesystem or fancy filesystem
    23  features (such as snapshots or overlays). As a result, the design is applicable
    24  to any modern Unix-like operating system.
    25  
    26  This feature is implemented through the use of manifest files. In particular,
    27  [`mtree(8)` manifests][mtree(5)]. After extraction of the root filesystem has
    28  been completed, a full manifest is generated from the root filesystem. When
    29  wanting to generate a delta layer, a new manifest is generated and the two
    30  manifests are compared. Any inconsistencies are then added to the delta layer.
    31  
    32  By using this very simple (and quite old) technique, we can create delta layers
    33  without the need for copies of the original filesystem or fancy filesystems.
    34  
    35  [mtree(8)]: https://www.freebsd.org/cgi/man.cgi?mtree(5)
    36  
    37  ### Mutation ###
    38  
    39  The main purpose of umoci is the ability to modify an image in various ways
    40  (by changing the configuration or adding delta layers).
    41  
    42  At the core of an OCI image is a content-addressable blob store, with different
    43  types of blobs signifying important data or metadata about an image contained
    44  in the store. As all blobs (both the metadata and data) are
    45  content-addressable, it does not make sense to talk about "modifying" a blob.
    46  
    47  Instead, what umoci does is that it creates a new version of a blob that is
    48  being replaced. Then, umoci walks up the referencing path that it took to
    49  reach the replaced blob and replaces all of the blobs that reference the old
    50  blob with a new blob referencing the new blob. This replacement will result in
    51  further changes to parents until the change bubbles up to the root
    52  `index.json`. Then, umoci will create or replace a top-level `index.json`
    53  entry to point to the newly created tree. Note that umoci will not replace
    54  any blobs that were not in the ancestor path of the modification, which means
    55  that all of the unchanged blobs are necessarily de-duplicated (and any other
    56  references to the old blob remain intact).