doc/user/intro-keep.md

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Intro: Keep"
   5 navorder: 3
   6 ---
   7
   8 # Intro: Keep
   9
  10 Keep is a content-addressable storage system. Its semantics are
  11 inherently different from the POSIX-like file systems you're used to.
  12
  13 > Explain what "content-addressable" means more specifically.
  14 > Define "locator"
  15
  16 Using Keep looks like this:
  17
  18 1. Write data.
  19 2. Receive locator.
  20 3. Use locator to retrieve data.
  21 4. Tag the locator with a symbolic name.
  22
  23 By contrast, using POSIX looks like this:
  24
  25 1. Choose locator (*i.e.*, filename).
  26 2. Write data to locator.
  27 3. Use locator to retrieve data.
  28
  29 Content addressing provides various benefits, including:
  30
  31 * Reduction of unnecessary data duplication
  32 * Prevention of race conditions (a given locator always references the same data)
  33 * Systematic client- and server-side verification of data integrity
  34 * Provenance reporting (when combined with Arvados MapReduce jobs)
  35
  36 ### Vocabulary
  37
  38 Keep arranges data into **collections** and **data blocks**.
  39
  40 A collection is analogous to a directory tree in a POSIX
  41 filesystem. It contains subdirectories and filenames, and indicates
  42 where to find the data blocks which comprise the files. It is encoded
  43 in plain text.
  44
  45 > Can a collection contain sub-collections?
  46 > The "plain text" encoding is JSON, right?  Either be specific or
  47 > remove it because the user doesn't really need to know about the encoding
  48 > at this level.
  49
  50 A data block contains between 1 byte and 64 MiB of data. Its locator
  51 is the MD5 checksum of the data, followed by a plus sign and its size
  52 in bytes (encoded as a decimal number).
  53
  54 `acbd18db4cc2f85cedef654fccc4a4d8+3`
  55
  56 > What does this locator encode?  Give an example so the astute
  57 > reader could use "md5" herself to construct the id.
  58
  59 A locator may include additional "hints" to help the Keep store find a
  60 data block more quickly. For example, in the locator
  61 `acbd18db4cc2f85cedef654fccc4a4d8+3+K@{{ site.arvados_api_host }}` the
  62 hint "+K@{{ site.arvados_api_host }}" indicates that the data block is
  63 stored in the Keep instance called *{{ site.arvados_api_host }}*. The
  64 hints are not necessary for Keep to locate a data block -- only the
  65 MD5 hash is -- but they help improve performance.
  66
  67 Keep distributes data blocks among the available disks. It also stores
  68 multiple copies of each block, so a single disk or node failure does
  69 not cause any data to become unreachable.
  70
  71 ### No "delete"
  72
  73 One of the side effects of the Keep write semantics is the lack of a
  74 "delete" operation. Instead, Keep relies on garbage collection to
  75 delete unneeded data blocks.
  76
  77 ### Tagging valuable data
  78
  79 > Now this goes from background introduction to tutorial,
  80 > so this should probably be split up
  81
  82 Valuable data must be marked explicitly by creating a Collection in
  83 Arvados. Otherwise, the data blocks will be deleted during garbage
  84 collection.
  85
  86 Use the arv(1) program to create a collection. For example:
  87
  88     arv collection create --uuid "acbd18db4cc2f85cedef654fccc4a4d8+3"
  89
  90 > What does this actually do?
  91
  92 ## Getting started
  93
  94 Write three bytes of data to Keep.
  95
  96     echo -n foo | whput -
  97
  98 > What does "wh" stand for in the program name?
  99
 100 Output:
 101
 102     acbd18db4cc2f85cedef654fccc4a4d8+3+K@arv01
 103
 104 > Explain that this is the locator that Keep has stored the data under
 105
 106 Retrieve the data.
 107
 108     whget acbd18db4cc2f85cedef654fccc4a4d8+3+K@arv01
 109
 110 Output:
 111
 112     foo
 113
 114
 115 {% include alert-stub.html %}
 116
 117 ### Writing a collection
 118
 119 ### Reading a file from a collection
 120
 121 ### Adding a collection to Arvados
 122
 123 ### Tagging a collection
 124
 125 ### Mounting Keep as a read-only POSIX filesystem
 126
 127 ### Mounting a single collection as a POSIX filesystem
 128
 129 > Needs a yellow "this web page under construction" sign with a guy shoveling dirt.