doc/user/topics/collection-versioning.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: Using collection versioning
   5 ...
   6
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 Collection versioning (if enabled system-wide) adds the possibility to store different collection states as it is modified. Depending on the cluster configuration it can work automatically, but there's also a way to manually control it by the user.
  14
  15 Versioning only triggers when selected collection attributes are updated: @name@, @description@, @properties@ and @manifest_text@.
  16 When one of these attributes change and the cluster-wide's configured collection idle time is up, or the individual collection's @preserve_version@ attribute is @true@, a new copy is made before saving the changes.
  17
  18 Every collection has a @version@ attribute that indicates its version number, starting from 1 on new collections and incrementing by 1 with every versionable update. Also, all collections point to their most current version via the @current_version_uuid@ attribute.
  19
  20 h3. Accessing past versions of a collection
  21
  22 To request a particular collection with all its versions you should request a list with filters including the collection's UUID and passing the @include_old_versions@ query parameter. For example, using the @arv@ command line client:
  23
  24 <pre>
  25 $ arv collection index --filters '[["uuid", "=", "o967z-4zz18-ynmlhyjbg1arnr2"]]' --include-old-versions
  26 {
  27  "kind":"arvados#collectionList",
  28  "etag":"",
  29  "self_link":"",
  30  "offset":0,
  31  "limit":100,
  32  "items":[
  33   {
  34    "href":"/collections/o967z-4zz18-i3ucessyo6xxadt",
  35    "kind":"arvados#collection",
  36    "etag":"7bhgspoi4rg9d33o925y8k277",
  37    "uuid":"o967z-4zz18-i3ucessyo6xxadt",
  38    "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
  39    "created_at":"2018-10-05T14:43:38.916885000Z",
  40    "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
  41    "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
  42    "modified_at":"2018-10-05T14:44:31.098019000Z",
  43    "name":"Test collection",
  44    "description":"This is the first version",
  45    "properties":{},
  46    "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
  47    "replication_desired":null,
  48    "replication_confirmed":null,
  49    "replication_confirmed_at":null,
  50    "storage_classes_desired":[
  51     "default"
  52    ],
  53    "storage_classes_confirmed":[],
  54    "storage_classes_confirmed_at":null,
  55    "delete_at":null,
  56    "trash_at":null,
  57    "is_trashed":false,
  58    "version":1,
  59    "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
  60    "preserve_version":true
  61   },
  62   {
  63    "href":"/collections/o967z-4zz18-ynmlhyjbg1arnr2",
  64    "kind":"arvados#collection",
  65    "etag":"1b995we7yilwyh7sc0w746urv",
  66    "uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
  67    "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
  68    "created_at":"2018-10-05T14:43:38.916885000Z",
  69    "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
  70    "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
  71    "modified_at":"2018-10-05T14:44:31.078643000Z",
  72    "name":"Test collection",
  73    "description":"This is the second (and current) version",
  74    "properties":{},
  75    "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
  76    "replication_desired":null,
  77    "replication_confirmed":null,
  78    "replication_confirmed_at":null,
  79    "storage_classes_desired":[
  80     "default"
  81    ],
  82    "storage_classes_confirmed":[],
  83    "storage_classes_confirmed_at":null,
  84    "delete_at":null,
  85    "trash_at":null,
  86    "is_trashed":false,
  87    "version":2,
  88    "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
  89    "preserve_version":false
  90   }
  91  ],
  92  "items_available":2
  93 }
  94 </pre>
  95
  96 You can also access a past version directly by its UUID:
  97
  98 <pre>
  99 $ arv collection get --uuid o967z-4zz18-i3ucessyo6xxadt
 100 {
 101  "href":"/collections/o967z-4zz18-i3ucessyo6xxadt",
 102  "kind":"arvados#collection",
 103  "etag":"1ej4d9klu70bez72cy7yjrz7o",
 104  "uuid":"o967z-4zz18-i3ucessyo6xxadt",
 105  "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
 106  "created_at":"2018-10-05T14:43:38.916885000Z",
 107  "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
 108  "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
 109  "modified_at":"2018-10-05T14:44:31.098019000Z",
 110  "name":"Test collection",
 111  "description":"This is the first version",
 112  "properties":{},
 113  "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
 114  "manifest_text":"",
 115  "replication_desired":null,
 116  "replication_confirmed":null,
 117  "replication_confirmed_at":null,
 118  "storage_classes_desired":[
 119   "default"
 120  ],
 121  "storage_classes_confirmed":[],
 122  "storage_classes_confirmed_at":null,
 123  "delete_at":null,
 124  "trash_at":null,
 125  "is_trashed":false,
 126  "version":1,
 127  "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
 128  "preserve_version":true
 129 }
 130 </pre>
 131
 132 h3. Manually preserving a version
 133
 134 Regardless of the collection's auto-save idle time cluster configuration, the user has the option to request that a particular collection state should be preserved.
 135
 136 When working on a collection, if there's a need to preserve the current state as a new version, the @preserve_version@ attribute should be set to @true@. This will trigger a new version creation on the next update, keeping this "version 2" state as a snapshot.
 137
 138 <pre>
 139 $ arv collection update --uuid o967z-4zz18-ynmlhyjbg1arnr2 -c '{"preserve_version":true}'
 140 {
 141  "href":"/collections/o967z-4zz18-ynmlhyjbg1arnr2",
 142  "kind":"arvados#collection",
 143  "etag":"8vhdwnahk8jcr84mqitmd5stu",
 144  "uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
 145  "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
 146  "created_at":"2018-10-05T14:43:38.916885000Z",
 147  "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
 148  "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
 149  "modified_at":"2018-10-05T15:12:57.986454000Z",
 150  "name":"Test collection",
 151  "description":"This is the second (and current) version",
 152  "properties":{},
 153  "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
 154  "manifest_text":"",
 155  "replication_desired":null,
 156  "replication_confirmed":null,
 157  "replication_confirmed_at":null,
 158  "storage_classes_desired":[
 159   "default"
 160  ],
 161  "storage_classes_confirmed":[],
 162  "storage_classes_confirmed_at":null,
 163  "delete_at":null,
 164  "trash_at":null,
 165  "is_trashed":false,
 166  "version":2,
 167  "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
 168  "preserve_version":true
 169 }
 170 </pre>
 171
 172 Once the @preserve_version@ attribute is set to @true@, it cannot be manually changed to @false@ and it will only be reset when a versionable update on the collection triggers a new version snapshot.
 173
 174 h3. Collection versions behavior & limitations
 175
 176 Past version collections are read-only, if you need to make changes to one of them, the suggested approach is to copy it into a new collection before updating.
 177
 178 Some attributes get automatically synced when they change on the current version:
 179
 180 * @owner_uuid@
 181 * @delete_at@
 182 * @trash_at@
 183 * @is_trashed@
 184 * @replication_desired@
 185 * @storage_classes_desired@
 186
 187 This way, old versions follow the current one on several configurations. In the special case that a current version's UUID gets updated, their past versions get also updated to point to the newer UUID.
 188
 189 Permissions on past versions are the same as their current version, the system does not allow attaching permission links to old versions. If you need to give special access to someone to a particular old version, the correct procedure is by copying it as a new collection.