[ARVADOS] created: 1.2.0-149-g9d8a391d4
Git user
git at public.curoverse.com
Fri Oct 5 14:56:27 EDT 2018
at 9d8a391d4545063a66212f77034a581e7e6875f5 (commit)
commit 9d8a391d4545063a66212f77034a581e7e6875f5
Author: Lucas Di Pentima <ldipentima at veritasgenetics.com>
Date: Fri Oct 5 15:55:41 2018 -0300
13561: Update documentation on collection versioning.
Arvados-DCO-1.1-Signed-off-by: Lucas Di Pentima <ldipentima at veritasgenetics.com>
diff --git a/doc/_config.yml b/doc/_config.yml
index 4ab858550..81a034fec 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -39,6 +39,7 @@ navbar:
- user/topics/keep.html.textile.liquid
- user/topics/arv-copy.html.textile.liquid
- user/topics/storage-classes.html.textile.liquid
+ - user/topics/collection-versioning.html.textile.liquid
- Running workflows at the command line:
- user/cwl/cwl-runner.html.textile.liquid
- user/cwl/cwl-run-options.html.textile.liquid
diff --git a/doc/api/methods/collections.html.textile.liquid b/doc/api/methods/collections.html.textile.liquid
index bcd57415d..c68773d90 100644
--- a/doc/api/methods/collections.html.textile.liquid
+++ b/doc/api/methods/collections.html.textile.liquid
@@ -35,7 +35,10 @@ table(table table-bordered table-condensed).
|replication_confirmed_at|datetime|When replication_confirmed was confirmed. If replication_confirmed is null, this field is also null.||
|trash_at|datetime|If @trash_at@ is non-null and in the past, this collection will be hidden from API calls. May be untrashed.||
|delete_at|datetime|If @delete_at@ is non-null and in the past, the collection may be permanently deleted.||
-|is_trashed|datetime|True if @trash_at@ is in the past, false if not.||
+|is_trashed|boolean|True if @trash_at@ is in the past, false if not.||
+|current_version_uuid|string|UUID of the collection's current version. On new collections, it'll be equal to the @uuid@ attribute.||
+|version|number|Version number, starting at 1 on new collections. This attribute is read-only.||
+|preserve_version|boolean|When set to true on a current version, it will be saved on the next versionable update.||
h3. Conditions of creating a Collection
@@ -67,7 +70,7 @@ table(table table-bordered table-condensed).
h3. delete
-Put a Collection in the trash. This sets the @trash_at@ field to @now@ and @delete_at@ field to @now@ + token TTL. A trashed group is invisible to most API calls unless the @include_trash@ parameter is true.
+Put a Collection in the trash. This sets the @trash_at@ field to @now@ and @delete_at@ field to @now@ + token TTL. A trashed collection is invisible to most API calls unless the @include_trash@ parameter is true.
Arguments:
@@ -91,6 +94,11 @@ List collections.
See "common resource list method.":{{site.baseurl}}/api/methods.html#index
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+|include_trash|boolean (default false)|Include trashed collections.|query||
+|include_old_versions|boolean (default false)|Include past versions of the collection(s) being listed, if any.|query||
+
Note: Because adding access tokens to manifests can be computationally expensive, the @manifest_text@ field is not included in results by default. If you need it, pass a @select@ parameter that includes @manifest_text at .
h3. update
diff --git a/doc/user/topics/collection-versioning.html.textile.liquid b/doc/user/topics/collection-versioning.html.textile.liquid
new file mode 100644
index 000000000..739c7fd24
--- /dev/null
+++ b/doc/user/topics/collection-versioning.html.textile.liquid
@@ -0,0 +1,189 @@
+---
+layout: default
+navsection: userguide
+title: Using collection versioning
+...
+
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+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.
+
+Versioning only triggers when selected collection attributes are updated: @name@, @description@, @properties@ and @manifest_text at .
+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.
+
+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.
+
+h3. Accessing past versions of a collection
+
+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:
+
+<pre>
+$ arv collection index --filters '[["uuid", "=", "o967z-4zz18-ynmlhyjbg1arnr2"]]' --include-old-versions
+{
+ "kind":"arvados#collectionList",
+ "etag":"",
+ "self_link":"",
+ "offset":0,
+ "limit":100,
+ "items":[
+ {
+ "href":"/collections/o967z-4zz18-i3ucessyo6xxadt",
+ "kind":"arvados#collection",
+ "etag":"7bhgspoi4rg9d33o925y8k277",
+ "uuid":"o967z-4zz18-i3ucessyo6xxadt",
+ "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
+ "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "modified_at":"2018-10-05T14:44:31.098019000Z",
+ "name":"Test collection",
+ "description":"This is the first version",
+ "properties":{},
+ "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
+ "replication_desired":null,
+ "replication_confirmed":null,
+ "replication_confirmed_at":null,
+ "storage_classes_desired":[
+ "default"
+ ],
+ "storage_classes_confirmed":[],
+ "storage_classes_confirmed_at":null,
+ "delete_at":null,
+ "trash_at":null,
+ "is_trashed":false,
+ "version":1,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "preserve_version":true
+ },
+ {
+ "href":"/collections/o967z-4zz18-ynmlhyjbg1arnr2",
+ "kind":"arvados#collection",
+ "etag":"1b995we7yilwyh7sc0w746urv",
+ "uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
+ "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "modified_at":"2018-10-05T14:44:31.078643000Z",
+ "name":"Test collection",
+ "description":"This is the second (and current) version",
+ "properties":{},
+ "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
+ "replication_desired":null,
+ "replication_confirmed":null,
+ "replication_confirmed_at":null,
+ "storage_classes_desired":[
+ "default"
+ ],
+ "storage_classes_confirmed":[],
+ "storage_classes_confirmed_at":null,
+ "delete_at":null,
+ "trash_at":null,
+ "is_trashed":false,
+ "version":2,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "preserve_version":false
+ }
+ ],
+ "items_available":2
+}
+</pre>
+
+You can also access a past version directly by its UUID:
+
+<pre>
+$ arv collection get --uuid o967z-4zz18-i3ucessyo6xxadt
+{
+ "href":"/collections/o967z-4zz18-i3ucessyo6xxadt",
+ "kind":"arvados#collection",
+ "etag":"1ej4d9klu70bez72cy7yjrz7o",
+ "uuid":"o967z-4zz18-i3ucessyo6xxadt",
+ "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
+ "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "modified_at":"2018-10-05T14:44:31.098019000Z",
+ "name":"Test collection",
+ "description":"This is the first version",
+ "properties":{},
+ "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
+ "manifest_text":"",
+ "replication_desired":null,
+ "replication_confirmed":null,
+ "replication_confirmed_at":null,
+ "storage_classes_desired":[
+ "default"
+ ],
+ "storage_classes_confirmed":[],
+ "storage_classes_confirmed_at":null,
+ "delete_at":null,
+ "trash_at":null,
+ "is_trashed":false,
+ "version":1,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "preserve_version":true
+}
+</pre>
+
+h3. Manually preserving a version
+
+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.
+
+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 at . This will trigger a new version creation on the next update, keeping this "version 2" state as a snapshot.
+
+<pre>
+$ arv collection update --uuid o967z-4zz18-ynmlhyjbg1arnr2 -c '{"preserve_version":true}'
+{
+ "href":"/collections/o967z-4zz18-ynmlhyjbg1arnr2",
+ "kind":"arvados#collection",
+ "etag":"8vhdwnahk8jcr84mqitmd5stu",
+ "uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
+ "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "modified_at":"2018-10-05T15:12:57.986454000Z",
+ "name":"Test collection",
+ "description":"This is the second (and current) version",
+ "properties":{},
+ "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
+ "manifest_text":"",
+ "replication_desired":null,
+ "replication_confirmed":null,
+ "replication_confirmed_at":null,
+ "storage_classes_desired":[
+ "default"
+ ],
+ "storage_classes_confirmed":[],
+ "storage_classes_confirmed_at":null,
+ "delete_at":null,
+ "trash_at":null,
+ "is_trashed":false,
+ "version":2,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "preserve_version":true
+}
+</pre>
+
+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.
+
+h3. Collection versions behavior & limitations
+
+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.
+
+Some attributes get automatically synced when they change on the current version:
+
+* @owner_uuid@
+* @delete_at@
+* @trash_at@
+* @is_trashed@
+* @replication_desired@
+* @storage_classes_desired@
+
+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.
+
+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.
\ No newline at end of file
-----------------------------------------------------------------------
hooks/post-receive
--
More information about the arvados-commits
mailing list