github.com/mika/distribution@v2.2.2-0.20160108133430-a75790e3d8e0+incompatible/docs/architecture.md (about)

     1  <!--[metadata]>
     2  +++
     3  draft = true
     4  +++
     5  <![end-metadata]-->
     6  
     7  # Architecture
     8  
     9  ## Design
    10  **TODO(stevvooe):** Discuss the architecture of the registry, internally and externally, in a few different deployment scenarios.
    11  
    12  ### Eventual Consistency
    13  
    14  > **NOTE:** This section belongs somewhere, perhaps in a design document. We
    15  > are leaving this here so the information is not lost.
    16  
    17  Running the registry on eventually consistent backends has been part of the
    18  design from the beginning. This section covers some of the approaches to
    19  dealing with this reality.
    20  
    21  There are a few classes of issues that we need to worry about when
    22  implementing something on top of the storage drivers:
    23  
    24  1. Read-After-Write consistency (see this [article on
    25     s3](http://shlomoswidler.com/2009/12/read-after-write-consistency-in-amazon.html)).
    26  2. [Write-Write Conflicts](http://en.wikipedia.org/wiki/Write%E2%80%93write_conflict).
    27  
    28  In reality, the registry must worry about these kinds of errors when doing the
    29  following:
    30  
    31  1. Accepting data into a temporary upload file may not have latest data block
    32     yet (read-after-write).
    33  2. Moving uploaded data into its blob location (write-write race).
    34  3. Modifying the "current" manifest for given tag (write-write race).
    35  4. A whole slew of operations around deletes (read-after-write, delete-write
    36     races, garbage collection, etc.).
    37  
    38  The backend path layout employs a few techniques to avoid these problems:
    39  
    40  1. Large writes are done to private upload directories. This alleviates most
    41     of the corruption potential under multiple writers by avoiding multiple
    42     writers.
    43  2. Constraints in storage driver implementations, such as support for writing
    44     after the end of a file to extend it.
    45  3. Digest verification to avoid data corruption.
    46  4. Manifest files are stored by digest and cannot change.
    47  5. All other non-content files (links, hashes, etc.) are written as an atomic
    48     unit. Anything that requires additions and deletions is broken out into
    49     separate "files". Last writer still wins.
    50  
    51  Unfortunately, one must play this game when trying to build something like
    52  this on top of eventually consistent storage systems. If we run into serious
    53  problems, we can wrap the storagedrivers in a shared consistency layer but
    54  that would increase complexity and hinder registry cluster performance.