doc/_includes/_mount_types.liquid

   1 Mount types
   2
   3 The "mounts" hash is the primary mechanism for adding data to the container at runtime (beyond what is already in the container image).
   4
   5 Each value of the "mounts" hash is itself a hash, whose "kind" key determines the handler used to attach data to the container.
   6
   7 table(table table-bordered table-condensed).
   8 |_. Mount type|_. Kind|_. Description|_. Examples|
   9 |Arvados data collection|@collection@|@"portable_data_hash"@ _or_ @"uuid"@ _may_ be provided. If not provided, a new collection will be created. This is useful when @"writable":true@ and the container's @output_path@ is (or is a subdirectory of) this mount target.
  10 @"writable"@ may be provided with a @true@ or @false@ to indicate the path must (or must not) be writable. If not specified, the system can choose.
  11 @"path"@ may be provided, and defaults to @"/"@.
  12 At container startup, the target path will have the same directory structure as the given path within the collection. Even if the files/directories are writable in the container, modifications will _not_ be saved back to the original collections when the container ends.|<pre><code>{
  13  "kind":"collection",
  14  "uuid":"...",
  15  "path":"/foo.txt"
  16 }
  17 {
  18  "kind":"collection",
  19  "uuid":"..."
  20 }</code></pre>|
  21 |Git tree|@git_tree@|One of { @"git-url"@, @"repository_name"@, @"uuid"@ } must be provided.
  22 One of { @"commit"@, @"revisions"@ } must be provided.
  23 "path" may be provided. The default path is "/".
  24 At container startup, the target path will have the source tree indicated by the given revision. The @.git@ metadata directory _will not_ be available: typically the system will use @git-archive@ rather than @git-checkout@ to prepare the target directory.
  25 - If a value is given for @"revisions"@, it will be resolved to a set of commits (as desribed in the "ranges" section of git-revisions(1)) and the container request will be satisfiable by any commit in that set.
  26 - If a value is given for @"commit"@, it will be resolved to a single commit, and the tree resulting from that commit will be used.
  27 - @"path"@ can be used to select a subdirectory or a single file from the tree indicated by the selected commit.
  28 - Multiple commits can resolve to the same tree: for example, the file/directory given in @"path"@ might not have changed between commits A and B.
  29 - The resolved mount (found in the Container record) will have only the "kind" key and a "blob" or "tree" key indicating the 40-character hash of the git tree/blob used.|<pre><code>{
  30  "kind":"git_tree",
  31  "uuid":"zzzzz-s0uqq-xxxxxxxxxxxxxxx",
  32  "commit":"master"
  33 }
  34 {
  35  "kind":"git_tree",
  36  "uuid":"zzzzz-s0uqq-xxxxxxxxxxxxxxx",
  37  "commit_range":"bugfix^..master",
  38  "path":"/crunch_scripts/grep"
  39 }</code></pre>|
  40 |Temporary directory|@tmp@|@"capacity"@: capacity (in bytes) of the storage device.
  41 @"device_type"@ (optional, default "network"): one of @{"ram", "ssd", "disk", "network"}@ indicating the acceptable level of performance.
  42 At container startup, the target path will be empty. When the container finishes, the content will be discarded. This will be backed by a storage mechanism no slower than the specified type.|<pre><code>{
  43  "kind":"tmp",
  44  "capacity":100000000000
  45 }
  46 {
  47  "kind":"tmp",
  48  "capacity":1000000000,
  49  "device_type":"ram"
  50 }</code></pre>|
  51 |Keep|@keep@|Expose all readable collections via arv-mount.
  52 Requires suitable runtime constraints.|<pre><code>{
  53  "kind":"keep"
  54 }</code></pre>|
  55 |Mounted file or directory|@file@|@"path"@: absolute path (inside the container) of a file or directory that is (or is inside) another mount target.
  56 Can be used for "stdin" and "stdout" targets.|<pre><code>{
  57  "kind":"file",
  58  "path":"/mounted_tmp/a.out"
  59 }</code></pre>|
  60 |JSON document|@json@|A JSON-encoded string, array, or object.|<pre>{
  61  "kind":"json",
  62  "content":{"foo":"bar"}
  63 }</pre>|
  64
  65 h2(#pre-populate-output). Pre-populate output using Mount points
  66
  67 When a container's output_path is a tmp mount backed by local disk, this output directory can be pre-populated with content from existing collections. This content can be specified by mounting collections at mount points that are subdirectories of output_path. Certain restrictions apply:
  68
  69 1. Only mount points of kind @collection@ are supported.
  70
  71 2. Mount points underneath output_path must not use @"writable":true@. If any of them are set as @writable@, the API will refuse to create/update the container request, and crunch-run will fail the container.
  72
  73 3. If any such mount points are configured as @exclude_from_output":true@, they will be excluded from the output.
  74
  75 If any process in the container tries to modify, remove, or rename these mount points or anything underneath them, the operation will fail and the container output and the underlying collections used to pre-populate are unaffected.
  76
  77 h3. Example mount point configurations
  78
  79 All the below examples are based on this collection:
  80 <pre><code>
  81 portable_data_hash cdfbe2e823222d26483d52e5089d553c+175
  82
  83 manifest_text: ./alice 03032680d3fa0561ef4f85071140861e+13+A04e9d06459cda00aa997565bd78001061cf5bffb@58ab593d 0:13:hello.txt\n./bob d820b9df970e1b498e7723c50b107e1b+11+A42d162a60210479d1cfaf9fbb98d494ac6322ae6@58ab593d 0:11:hello.txt\n./carol cf72b172ff969250ae14a893a6745440+13+A476a2fd39e14e9c03af3076bd17e3612c075ff66@58ab593d 0:13:hello.txt\n
  84 </code></pre>
  85
  86 table(table table-bordered table-condensed).
  87 |{width:40%}. *Mount point*|{width:30%}. *Description*|{width:30%}. *Resulting collection manifest text*|
  88 |<pre><code>"mounts": {
  89   "/tmp/foo": {
  90     "kind": "collection",
  91     "portable_data_hash": "cdfbe2...+175"
  92   },
  93 },
  94 "output_path": "/tmp"
  95 </code></pre>|No path specified and hence the entire collection will be mounted.|./*foo/*alice 030326... 0:13:hello.txt\n
  96 ./*foo/*bob d820b9... 0:11:hello.txt\n
  97 ./*foo/*carol cf72b1... 0:13:hello.txt\n
  98 *Note:* Here the "." in streams is replaced with *foo*.|
  99 |<pre><code>"mounts": {
 100   "/tmp/foo/bar": {
 101     "kind": "collection",
 102     "portable_data_hash": "cdfbe2...+175"
 103     "path": "alice"
 104   },
 105 },
 106 "output_path": "/tmp"
 107 </code></pre>|Specified path refers to the subdirectory *alice* in the collection.|./*foo/bar* 030326... 0:13:hello.txt\n
 108 *Note:* only the manifest text segment for the subdirectory *alice* is included after replacing the subdirectory *alice* with *foo/bar*.|
 109 |<pre><code>"mounts": {
 110   "/tmp/foo/bar": {
 111     "kind": "collection",
 112     "portable_data_hash": "cdfbe2...+175"
 113     "path": "alice/hello.txt"
 114   },
 115 },
 116 "output_path": "/tmp"
 117 </code></pre>|Specified path refers to the file *hello.txt* in the *alice* subdirectory|./*foo* 030326... 0:13:*bar*\n
 118 *Note:* Here the subdirectory *alice* is replaced with *foo* and the filename *hello.txt* from this subdirectory is replaced with *bar*.|