[ARVADOS] updated: 1.3.0-2690-g65e39827a

Thu Jun 18 16:05:07 UTC 2020

Summary of changes:
 doc/admin/upgrading.html.textile.liquid      |  8 +++---
 doc/api/permission-model.html.textile.liquid | 37 ++++++++++++++++------------
 2 files changed, 26 insertions(+), 19 deletions(-)

       via  65e39827a56cab30d7c9fe526c5cfc23e5e930e8 (commit)
      from  5502559ac286dcf807261cec86b983f061788908 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.


commit 65e39827a56cab30d7c9fe526c5cfc23e5e930e8
Author: Peter Amstutz <peter.amstutz at curii.com>
Date:   Thu Jun 18 12:04:46 2020 -0400

    16007: Doc updates/clarifications from feedback
    
    Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <peter.amstutz at curii.com>

diff --git a/doc/admin/upgrading.html.textile.liquid b/doc/admin/upgrading.html.textile.liquid
index bf584d8b6..10877ec75 100644
--- a/doc/admin/upgrading.html.textile.liquid
+++ b/doc/admin/upgrading.html.textile.liquid
@@ -58,9 +58,11 @@ Some constraints on the permission system have been added, in particular @role@
 # A @role@ is always owned by the system_user. When a group is created, it creates a @can_manage@ link for the object that would have been assigned to @owner_uuid at .  Migration adds @can_manage@ links and reassigns roles to the system user.  This also has the effect of requiring that all @role@ groups have unique names on the system.
 # A permission link can have the permission level (@name@) updated but not @head_uuid@, @tail_uuid@ or @link_class at .
 
-The @arvados-sync-groups@ tool has been updated to reflect these constraints.
+The @arvados-sync-groups@ tool has been updated to reflect these constraints, so it is important to use the version of @arvados-sync-groups@ that matches the API server version.
 
-To determine which groups have invalid @group_class@ with this command (these will be migrated to @role@ groups):
+Before upgrading, use the following commands to find out which groups and permissions in your database will be automatically modified or deleted during the upgrade.
+
+To determine which groups have invalid @group_class@ (these will be migrated to @role@ groups):
 
 <pre>
 arv group list --filters '[["group_class", "not in", ["project", "role"]]]'
@@ -72,7 +74,7 @@ To list all @role@ groups, which will be reassigned to the system user (unless @
 arv group list --filters '[["group_class", "=", "role"]]'
 </pre>
 
-To list which @project@ groups have outgoing permission links.  Such links are now invalid and will be deleted by the migration:
+To list which @project@ groups have outgoing permission links (such links are now invalid and will be deleted by the migration):
 
 <pre>
 for uuid in $(arv link list --filters '[["link_class", "=", "permission"], ["tail_uuid", "like", "%-j7d0g-%"]]' |
diff --git a/doc/api/permission-model.html.textile.liquid b/doc/api/permission-model.html.textile.liquid
index 4e04699fc..f6878c0c9 100644
--- a/doc/api/permission-model.html.textile.liquid
+++ b/doc/api/permission-model.html.textile.liquid
@@ -16,9 +16,13 @@ There are four levels of permission: *none*, *can_read*, *can_write*, and *can_m
 ** the object is not included in any list query response.
 ** direct queries of the object by uuid return 404 Not Found.
 ** Link objects require valid identifiers in @head_uuid@ and @tail_uuid@, so an attempt to create a Link that references an unreadable object will return an error indicating the object is not found.
-* *can_read* grants read-only access to the record.  Attempting to update or delete the record returns an error.  *can_read* does not allow a reader to see any permission grants on the object except the object's owner_uuid and the reader's own permissions.
-* *can_write* permits changes to the record (but not permission links).  *can_write* permits the user to delete the object.  *can_write* also implies *can_read*.
-* *can_manage* permits the user to read, create, update and delete permission links whose @head_uuid@ is this object's @uuid at .  *can_manage* also implies *can_write* and *can_read*.
+* *can_read* grants read-only access to the record.  Attempting to update or delete the record returns an error.
+** *can_read* does not allow a reader to see any permission grants on the object except the object's owner_uuid and the reader's own permissions.
+* *can_write* permits changes to the record, including changing ownership and deleting the object.
+** *can_write* cannot read, create, update or delete permission links associated with the object.
+** *can_write* also implies *can_read*.
+* *can_manage* permits the user to read, create, update and delete permission links whose @head_uuid@ is this object's @uuid at .
+** *can_manage* also implies *can_write* and *can_read*.
 
 h2. Ownership
 
@@ -33,23 +37,24 @@ h2(#links). Permission links
 A permission link is a link object with:
 
 * @owner_uuid@ of the system user.
-* @link_class@ *permission*
+* @link_class@ "permission"
 * @name@ one of *can_read*, *can_write* or *can_manage*
 * @head_uuid@ of some Arvados object
-* @tail_uuid@ of a User or Group
+* @tail_uuid@ of a User or Group.  For Group, the @group_class@ must be a "role".
 
 This grants the permission in @name@ for @tail_uuid@ accessing @head_uuid at .
 
-If a User has *can_manage* permission on some object, the user has the ability to read, create, update and delete permission links with @head_uuid@ of the managed object (i.e. permission grants on the object).
+If a User has *can_manage* permission on some object, the user has the ability to read, create, update and delete permission links with @head_uuid@ of the managed object.  In other words, the user has the ability to modify the permission grants on the object.
 
 h3. Transitive permissions
 
-Permissions can be obtained indirectly by following multiple permission links or nested ownership.
+Permissions can be obtained indirectly through nested ownership (*can_manage*) or by following multiple permission links.
 
-* If a User X *can_read* Group A, and Group A *can_read* Object B, then User X *can_read* Object B.
+* If a User X owns project A, and project A owns project B, then User X *can_manage* project B.
+* If a User X *can_read* role A, and role A *can_read* Object B, then User X *can_read* Object B.
 * Permissions are narrowed to the least powerful permission on the path.
-** If User X *can_write* Group A, and Group A *can_read* Object B, then User X *can_read* Object B.
-** If User X *can_read* Group A, and Group A *can_write* Object B, then User X *can_read* Object B.
+** If User X *can_write* role A, and role A *can_read* Object B, then User X *can_read* Object B.
+** If User X *can_read* role A, and role A *can_write* Object B, then User X *can_read* Object B.
 
 h2. Projects and Roles
 
@@ -57,13 +62,13 @@ A "project" is a subtype of Group that is displayed as a "Project" in Workbench,
 * A project can own things (appear in @owner_uuid@)
 * A project can be owned by a user or another project.
 * The name of a project is unique only among projects with the same owner_uuid.
-* Projects can be the target (@head_uuid@) of a permission link, but not the origin (@tail_uuid@).  Putting a project in a @tail_uuid@ field is an error.
+* Projects can be targets (@head_uuid@) of permission links, but not origins (@tail_uuid@).  Putting a project in a @tail_uuid@ field is an error.
 
 A "role" is a subtype of Group that is treated in Workbench as a group of users who have permissions in common (typically an organizational group).
 * A role cannot own things (cannot appear in @owner_uuid@).  Putting a role in an @owner_uuid@ field is an error.
 * All roles are owned by the system user.
-* The name of a role is unique across an instance.
-* A role can be both the target (head_uuid) and origin (tail_uuid) of a permission link.
+* The name of a role is unique across a single Arvados cluster.
+* Roles can be both targets (@head_uuid@) and origins (@tail_uuid@) of permission links.
 
 h3. Access through Roles
 
@@ -79,15 +84,15 @@ h2. Special cases
 
 Log table objects are additionally readable based on whether the User has *can_read* permission on @object_uuid@ (User can access log history about objects it can read).  To retain the integrity of the log, the log table denies all update or delete operations.
 
-Permission links where @tail_uuid@ is a User allow @can_read@ on the link record by that user.  (User can discover her own permission grants.)
+Permission links where @tail_uuid@ is a User allow *can_read* on the link record by that user (User can discover her own permission grants.)
 
 At least *can_read* on a Collection grants permission to read the blocks that make up the collection (API server returns signed blocks).
 
 A user can only read a container record if the user has read permission to a container_request with that container_uuid.
 
 *can_read* and *can_write* access on a user grants access to the user record, but not anything owned by the user.
-*can_manage* access to a user grants can_manage access to the user, _and everything owned by that user_.
-If a user A *can_read* role R, and role R *can_manage* user B, then user A *can_read* user B _and everything owned by that user_.
+*can_manage* access to a user grants can_manage access to the user, _and everything owned by that user_ .
+If a user A *can_read* role R, and role R *can_manage* user B, then user A *can_read* user B _and everything owned by that user_ .
 
 h2(#system). System user and group
 

-----------------------------------------------------------------------


hooks/post-receive
-- 


