[ARVADOS] updated: 2.1.0-449-gd2f6583ef
Git user
git at public.arvados.org
Thu Mar 4 22:44:52 UTC 2021
Summary of changes:
doc/_config.yml | 1 +
doc/api/methods/groups.html.textile.liquid | 48 ++++++++++++++++++++++++++--
doc/api/permission-model.html.textile.liquid | 10 ++++--
doc/user/topics/projects.html.textile.liquid | 36 +++++++++++++++++++++
4 files changed, 91 insertions(+), 4 deletions(-)
create mode 100644 doc/user/topics/projects.html.textile.liquid
via d2f6583ef5d588fdfe7dd65a2deb75b41d9498a0 (commit)
from 7a3215a77922f308857881f108cfabc3b85d2378 (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 d2f6583ef5d588fdfe7dd65a2deb75b41d9498a0
Author: Ward Vandewege <ward at curii.com>
Date: Thu Mar 4 17:42:06 2021 -0500
17119: add documentation.
Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <ward at curii.com>
diff --git a/doc/_config.yml b/doc/_config.yml
index b0355e269..4e0e2f873 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -44,6 +44,7 @@ navbar:
- user/tutorials/tutorial-keep-mount-os-x.html.textile.liquid
- user/tutorials/tutorial-keep-mount-windows.html.textile.liquid
- user/tutorials/tutorial-keep-collection-lifecycle.html.textile.liquid
+ - user/topics/projects.html.textile.liquid
- user/topics/arv-copy.html.textile.liquid
- user/topics/collection-versioning.html.textile.liquid
- user/topics/storage-classes.html.textile.liquid
diff --git a/doc/api/methods/groups.html.textile.liquid b/doc/api/methods/groups.html.textile.liquid
index f85e621db..73df7a066 100644
--- a/doc/api/methods/groups.html.textile.liquid
+++ b/doc/api/methods/groups.html.textile.liquid
@@ -25,8 +25,9 @@ Each Group has, in addition to the "Common resource fields":{{site.baseurl}}/api
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
|name|string|||
-|group_class|string|Type of group. This does not affect behavior, but determines how the group is presented in the user interface. For example, @project@ indicates that the group should be displayed by Workbench and arv-mount as a project for organizing and naming objects.|@"project"@
-null|
+|group_class|string|Type of group. @project@ and @filter@ indicate that the group should be displayed by Workbench and arv-mount as a project for organizing and naming objects. @role@ means FIXME. |@"filter"@
+@"project"@
+@"role"@|
|description|text|||
|properties|hash|User-defined metadata, may be used in queries using "subproperty filters":{{site.baseurl}}/api/methods.html#subpropertyfilters ||
|writable_by|array|List of UUID strings identifying Users and other Groups that have write permission for this Group. Only users who are allowed to administer the Group will receive a full list. Other users will receive a partial list that includes the Group's owner_uuid and (if applicable) their own user UUID.||
@@ -34,6 +35,49 @@ null|
|delete_at|datetime|If @delete_at@ is non-null and in the past, the group and all objects directly or indirectly owned by the group may be permanently deleted.||
|is_trashed|datetime|True if @trash_at@ is in the past, false if not.||
+ at filter@ groups have a special @properties@ field named @filters@, which must be an array of arrays with 3 elements, each describing a filter. @filter@ groups are virtual groups; they can not own other objects. Filter attributes must include the object type (@collections@, @container_requests@, @groups@, @workflows@), separated with a dot from the field to be filtered on. Filters are applied with an implied *and* between them, but each filter only applies to the object type specified. The results are subject to the usual access controls - they are a subset of all objects the user can see. Here is an example:
+
+<pre>
+ "properties":{
+ "filters":[
+ [
+ "groups.name",
+ "like",
+ "Public%"
+ ]
+ ]
+ },
+</pre>
+
+This @filter@ group will return all groups (projects) that have a name starting with the word @Public@ and are visible to the user issuing the query. Because groups can contain many types of object, it will also return all objects of other types that the user can see.
+
+The 'is_a' filter operator is of particular interest to limit the @filter@ group 'content' to the desired object(s). When the 'is_a' operator is used, the attribute must be 'uuid'. The operand may be a string or an array which means objects of either type will match the filter. This example will return all groups (projects) that have a name starting with the word @Public@, as well as all collections that are in the project with uuid @zzzzz-j7d0g-0123456789abcde at .
+
+<pre>
+ "properties":{
+ "filters":[
+ [
+ "groups.name",
+ "like",
+ "Public%"
+ ],
+ [
+ "collections.owner_uuid",
+ "=",
+ "zzzzz-j7d0g-0123456789abcde"
+ ],
+ [
+ "uuid",
+ "is_a",
+ [
+ "arvados#group",
+ "arvados#collection"
+ ]
+ ]
+ ]
+ },
+ </pre>
+
h2. Methods
See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update at .
diff --git a/doc/api/permission-model.html.textile.liquid b/doc/api/permission-model.html.textile.liquid
index 54c4a3331..f54dc8bf2 100644
--- a/doc/api/permission-model.html.textile.liquid
+++ b/doc/api/permission-model.html.textile.liquid
@@ -26,7 +26,7 @@ There are four levels of permission: *none*, *can_read*, *can_write*, and *can_m
h2. Ownership
-All Arvados objects have an @owner_uuid@ field. Valid uuid types for @owner_uuid@ are "User" and "Group". For Group, the @group_class@ must be a "project".
+All Arvados objects have an @owner_uuid@ field. Valid uuid types for @owner_uuid@ are "User" and "Group". For Group, the @group_class@ must be "filter", "project" or "role".
The User or Group specified by @owner_uuid@ has *can_manage* permission on the object. This permission is one way: an object that is owned does not get any special permissions on the User or Group that owns it.
@@ -63,9 +63,15 @@ h2. Projects and Roles
A "project" is a subtype of Group that is displayed as a "Project" in Workbench, and as a directory by @arv-mount at .
* 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.
+* The name of a project is unique only among projects and filters with the same owner_uuid.
* 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 "filter" is a subtype of Group that is displayed as a "Project" in Workbench, and as a directory by @arv-mount at . See "the groups API documentation":/api/methods/groups.html for more information.
+* A filter cannot own things (cannot appear in @owner_uuid@). Putting a role in an @owner_uuid@ field is an error.
+* A filter can be owned by a user or another project.
+* The name of a filter is unique only among projects and filters with the same owner_uuid.
+* Filters can be targets (@head_uuid@) of permission links, but not origins (@tail_uuid@). Putting a filter 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.
diff --git a/doc/user/topics/projects.html.textile.liquid b/doc/user/topics/projects.html.textile.liquid
new file mode 100644
index 000000000..f4b236c4c
--- /dev/null
+++ b/doc/user/topics/projects.html.textile.liquid
@@ -0,0 +1,36 @@
+---
+layout: default
+navsection: userguide
+title: "Projects"
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+Arvados @projects@ are used to organize objects. Projects can contain @collections@, @container requests@, @workflows@, etc. Projects can also contain other projects. An object is part of a project if the @owner_uuid@ of the object is set to the uuid of the project.
+
+Projects are implemented as a subtype of the Arvados @group@ object type, with @group_class@ set to the value "project". More information is available in the "groups API reference":/api/methods/groups.html.
+
+Projects can be manipulated via Workbench, the cli tools, the SDKs, and the Arvados APIs.
+
+h2. The home project
+
+Each user has a @home project@, which is implemented differently. This is a virtual project that is comprised of all objects owned by the user, in other words, all objects with the @owner_uuid@ set to the @uuid@ of the user. The home project is accessible via Workbench, which makes it easy view its contents and to move objects from and to the home project. The home project is also accessible via FUSE, WebDAV and the S3 interface.
+
+The same thing can be done via the APIs. To put something in a user's home project via the cli or SDKs, one would set the @owner_uuid@ of the object to the user's @uuid at . This also implies that this user now has full ownership and control over that object.
+
+The contents of the home project can be accessed with the @group contents@ API, e.g. via the cli with this command:
+<pre>arv group contents --uuid zzzzz-tpzed-123456789012345</pre>
+In this command, `zzzzz-tpzed-123456789012345` is a @user@ uuid, which is unusual because we are using it as the argument to a @groups@ API. The @group contents@ API is normally used with a @group@ uuid.
+
+Because the home project is a virtual project, other operations via the @groups@ API are not supported.
+
+h2. Filter groups
+
+Filter groups are another type of virtual project. They are implemented as an Arvados @group@ object with @group_class@ set to the value "filter".
+
+Filter groups define one or more filters which are applied to all objects that the current user can see, and returned as the contents of the @group at . @filter@ groups are described in more detail in the "groups API reference":/api/methods/groups.html.
+
+Filter groups are accessible (read-only) via Workbench and the Arvados FUSE mount, WebDAV and S3 interface. Filter groups must currently be defined via the API, SDK or cli, there is no Workbench support yet.
-----------------------------------------------------------------------
hooks/post-receive
--
More information about the arvados-commits
mailing list