From 040db1debca6c5dccda5513fb6d42f14687ae910 Mon Sep 17 00:00:00 2001 From: Peter Amstutz Date: Thu, 30 Jan 2020 18:17:43 -0500 Subject: [PATCH] Update more documentation for new config file, add 'group favorites' refs #16015 Arvados-DCO-1.1-Signed-off-by: Peter Amstutz --- doc/_config.yml | 11 +-- .../collection-versioning.html.textile.liquid | 29 +++++--- ...olling-container-reuse.html.textile.liquid | 10 +-- doc/admin/favorites.html.textile.liquid | 57 +++++++++++++++ .../logs-table-management.html.textile.liquid | 69 +++++++++---------- doc/admin/storage-classes.html.textile.liquid | 22 +++--- .../workbench2-vocabulary.html.textile.liquid | 4 +- 7 files changed, 128 insertions(+), 74 deletions(-) create mode 100644 doc/admin/favorites.html.textile.liquid diff --git a/doc/_config.yml b/doc/_config.yml index 0f7684f837..814852fcc3 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -165,20 +165,21 @@ navbar: - admin/metrics.html.textile.liquid - admin/health-checks.html.textile.liquid - admin/management-token.html.textile.liquid - - Cloud: - - admin/storage-classes.html.textile.liquid - - admin/spot-instances.html.textile.liquid - - admin/cloudtest.html.textile.liquid - Data Management: + - admin/favorites.html.textile.liquid - admin/collection-versioning.html.textile.liquid - admin/collection-managed-properties.html.textile.liquid - admin/keep-balance.html.textile.liquid - admin/controlling-container-reuse.html.textile.liquid - admin/logs-table-management.html.textile.liquid + - admin/workbench2-vocabulary.html.textile.liquid + - admin/storage-classes.html.textile.liquid + - Cloud: + - admin/spot-instances.html.textile.liquid + - admin/cloudtest.html.textile.liquid - Other: - install/migrate-docker19.html.textile.liquid - admin/upgrade-crunch2.html.textile.liquid - - admin/workbench2-vocabulary.html.textile.liquid installguide: - Overview: - install/index.html.textile.liquid diff --git a/doc/admin/collection-versioning.html.textile.liquid b/doc/admin/collection-versioning.html.textile.liquid index 0a4d1fa769..f67f4ad983 100644 --- a/doc/admin/collection-versioning.html.textile.liquid +++ b/doc/admin/collection-versioning.html.textile.liquid @@ -12,21 +12,28 @@ SPDX-License-Identifier: CC-BY-SA-3.0 This page describes how to enable and configure the collection versioning feature on the API server. -h3. API Server configuration +h3. Configuration -There are 2 configuration settings that control this feature, both go on the @application.yml@ file. +There are 2 configuration settings in the @Collections@ section of @config.yml@ that control this feature. -h4. Setting: @collection_versioning@ (Boolean. Default: false) +
+    Collections:
+      # If true, enable collection versioning.
+      # When a collection's preserve_version field is true or the current version
+      # is older than the amount of seconds defined on PreserveVersionIfIdle,
+      # a snapshot of the collection's previous state is created and linked to
+      # the current collection.
+      CollectionVersioning: false
 
-If @true@, collection versioning is enabled, meaning that new version records can be created. Note that if you set @collection_versioning@ to @false@ after being enabled, old versions will still be accessible, but further changes will not be versioned.
+      # This setting control the auto-save aspect of collection versioning, and can be set to:
+      #   0s = auto-create a new version on every update.
+      #  -1s = never auto-create new versions.
+      # > 0s = auto-create a new version when older than the specified number of seconds.
+      PreserveVersionIfIdle: -1s
+
-h4. Setting: @preserve_version_if_idle@ (Numeric. Default: -1) - -This setting control the auto-save aspect of collection versioning, and can be set to: -* @-1@: Never auto-save versions. Only save versions when the client ask for it by setting @preserve_version@ to @true@ on any given collection. -* @0@: Preserve all versions every time a collection gets a versionable update. -* @N@ (being N > 0): Preserve version when a collection gets a versionable update after a period of at least N seconds since the last time it was modified. +Note that if you set @collection_versioning@ to @false@ after being enabled, old versions will still be accessible, but further changes will not be versioned. h3. Using collection versioning -"Discussed in the user guide":{{site.baseurl}}/user/topics/collection-versioning.html \ No newline at end of file +"Discussed in the user guide":{{site.baseurl}}/user/topics/collection-versioning.html diff --git a/doc/admin/controlling-container-reuse.html.textile.liquid b/doc/admin/controlling-container-reuse.html.textile.liquid index 76f57f31a5..787828c14e 100644 --- a/doc/admin/controlling-container-reuse.html.textile.liquid +++ b/doc/admin/controlling-container-reuse.html.textile.liquid @@ -1,7 +1,7 @@ --- layout: default navsection: admin -title: Controlling container reuse +title: Preventing container reuse ... {% comment %} @@ -10,12 +10,8 @@ Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} -This page describes how an admin can control container reuse using the @arv@ command. This can be utilized to avoid reusing a completed container without disabling reuse for the corresponding steps in affected workflows. For example, if a container exited successfully but produced bad output, it may not be feasible to update the workflow immediately. Meanwhile, changing the state of the container from @Complete@ to @Cancelled@ will prevent it from being used in subsequent workflows. +Sometimes a container exited successfully but produced bad output, and re-running the workflow will cause it to re-use the bad container instead of running a new container. One way to deal with this is to re-run the entire workflow with reuse disable. Another way is for the workflow author to tweak the input data or workflow so that on re-run it produces a distinct container request. However, for large or complex workflows both these options may be impractical. -If a container is in the @Complete@ state, the following @arv@ command will change its state to @Cancelled@, where @xxxxx-xxxxx-xxxxxxxxxxxxxxx@ is the @UUID@ of the container: +To prevent an individual container from being reused in later workflows, an admin can manually change the state of the bad container record from @Complete@ to @Cancelled@. The following @arv@ command demonstrates how change a container state to @Cancelled@, where @xxxxx-xxxxx-xxxxxxxxxxxxxxx@ is the @UUID@ of the container: 
arv container update -u xxxxx-xxxxx-xxxxxxxxxxxxxxx -c '{"state":"Cancelled"}'
- -Use the following command to list all containers that exited with 0 and were then cancelled: - -
arv container list --filters='[["state", "=", "Cancelled"], ["exit_code", "=", 0]]'
See the "arv CLI tool overview":{{site.baseurl}}/sdk/cli/index.html for more details about using the @arv@ command. diff --git a/doc/admin/favorites.html.textile.liquid b/doc/admin/favorites.html.textile.liquid new file mode 100644 index 0000000000..623cb114b8 --- /dev/null +++ b/doc/admin/favorites.html.textile.liquid @@ -0,0 +1,57 @@ +--- +layout: default +navsection: admin +title: Setting favorites for users +... + +A "favorite" is a shortcut to a project that is displayed in the user interface (Workbench). Users can mark their own favorites, but it is also possible to have favorites that are displayed for all members of a group (including the "All Users" group). + +The schema for a "favorite" link is: + +table(table table-bordered table-condensed). +|_. Field|_. Value|_. Description| +|owner_uuid|user or group uuid|The user or group that "owns" the favorite| +|head_uuid|project uuid|The project being favorited| +|link_class|string of value "star"|Indicates this represents a link to a user favorite| + +h2. Cluster wide favorites + +The "All Users" group for a given cluster has the uuid @{prefix}-j7d0g-ffffffffffffff@. Cluster-wide favorites that will show up for all users should belong to the "All Users" group. + +Favorites can be owned by other groups, in which case they will only be visibile to members of that group. + +h2. Creating a favorite + +@owner_uuid@ controls who will see the favorite, @head_uuid@ is the project being favorited, and @link_class@ indicates this record is a favorite. Set "tail_uuid" to the same value as "owner_uuid". + +
+$ arv link create --link '{
+    "owner_uuid": "c97qk-j7d0g-fffffffffffffff",
+    "tail_uuid":  "c97qk-j7d0g-fffffffffffffff",
+    "head_uuid":  "c97qk-j7d0g-khm44br99mz40hk",
+    "link_class": "star"}'
+
+ +h2. Deleting a favorite + +
+$ arv link delete --uuid c97qk-o0j2j-haadun4x0vmpvnd
+
+ +h2. Listing favorites + +To list all 'star' links readable by the current user + +
+$ arv link list --filters '[["link_class", "=", "star"]]' --order owner_uuid
+
+ +This will include favorites belonging any group or project that is readable by the user. + +Alternately, the query can be restricted to only show favorites associated with the "All Users" group (or some other group) by filtering on owner_uuid: + +
+$ arv link list --filters '[
+  ["link_class", "=", "star"],
+  ["owner_uuid", "=", "c97qk-j7d0g-fffffffffffffff"]]'
+
diff --git a/doc/admin/logs-table-management.html.textile.liquid b/doc/admin/logs-table-management.html.textile.liquid index a1cdb18dcf..ef794054a7 100644 --- a/doc/admin/logs-table-management.html.textile.liquid +++ b/doc/admin/logs-table-management.html.textile.liquid @@ -21,47 +21,44 @@ This database table currently serves three purposes: As a result, this table grows indefinitely, even on sites where policy does not require an audit log; making backups, migrations, and upgrades unnecessarily slow and painful. -h3. API Server configuration +h3. Configuration -To solve the problem mentioned above, the API server offers the possibility to limit the amount of log information stored on the table: +To solve the problem mentioned above, the @AuditLogs@ section of @config.yml@ offers several options to limit the amount of log information stored on the table: 
-# Attributes to suppress in events and audit logs.  Notably,
-# specifying ["manifest_text"] here typically makes the database
-# smaller and faster.
-#
-# Warning: Using any non-empty value here can have undesirable side
-# effects for any client or component that relies on event logs.
-# Use at your own risk.
-unlogged_attributes: []
+    AuditLogs:
+      # Time to keep audit logs. (An audit log is a row added
+      # to the "logs" table in the PostgreSQL database each time an
+      # Arvados object is created, modified, or deleted.)
+      #
+      # Currently, websocket event notifications rely on audit logs, so
+      # this should not be set lower than 5 minutes.
+      MaxAge: 336h
+
+      # Maximum number of log rows to delete in a single SQL transaction,
+      # to prevent surprises and avoid bad database behavior
+      # (especially the first time the cleanup job runs on an existing
+      # cluster with a huge backlog) a maximum number of rows to
+      # delete in a single transaction.
+      #
+      # If MaxDeleteBatch is 0, log entries will never be
+      # deleted by Arvados. Cleanup can be done by an external process
+      # without affecting any Arvados system processes, as long as very
+      # recent (<5 minutes old) logs are not deleted.
+      #
+      # 100000 is a reasonable batch size for most sites.
+      MaxDeleteBatch: 0
+
+      # Attributes to suppress in events and audit logs.  Notably,
+      # specifying {"manifest_text": {}} here typically makes the database
+      # smaller and faster.
+      #
+      # Warning: Using any non-empty value here can have undesirable side
+      # effects for any client or component that relies on event logs.
+      # Use at your own risk.
+      UnloggedAttributes: {}
-The above setting affects all events being logged, independently of how much time they will be kept on the database. - -
-# Time to keep audit logs (a row in the log table added each time an
-# Arvados object is created, modified, or deleted) in the PostgreSQL
-# database. Currently, websocket event notifications rely on audit
-# logs, so this should not be set lower than 300 (5 minutes).
-max_audit_log_age: 1209600
-
- -...and to prevent surprises and avoid bad database behavior (especially the first time the cleanup job runs on an existing cluster with a huge backlog) a maximum number of rows to delete in a single transaction. - -
-# Maximum number of log rows to delete in a single SQL transaction.
-#
-# If max_audit_log_delete_batch is 0, log entries will never be
-# deleted by Arvados. Cleanup can be done by an external process
-# without affecting any Arvados system processes, as long as very
-# recent (<5 minutes old) logs are not deleted.
-#
-# 100000 is a reasonable batch size for most sites.
-max_audit_log_delete_batch: 0
-
- -This feature works when both settings are non-zero, periodically dispatching a background task that deletes all log rows older than @max_audit_log_age@. -The events being cleaned up by this process don't include job/container stderr logs (they're handled by the existing @delete job/container logs@ rake tasks) h3. Additional consideration diff --git a/doc/admin/storage-classes.html.textile.liquid b/doc/admin/storage-classes.html.textile.liquid index 1a6420d4c4..e5c9a3973f 100644 --- a/doc/admin/storage-classes.html.textile.liquid +++ b/doc/admin/storage-classes.html.textile.liquid @@ -15,19 +15,15 @@ Storage classes (alternately known as "storage tiers") allow you to control whic The storage classes for each volume are set in the per-volume "keepstore configuration":{{site.baseurl}}/install/install-keepstore.html 
-Volumes:
- - ... Volume configuration ...
-   #
-   # If no storage classes are specified, will use [default]
-   #
-   StorageClasses: null
-
- - ... Volume configuration ...
-   #
-   # Specify this volume is in the "archival" storage class.
-   #
-   StorageClasses: [archival]
-
+    Volumes:
+      ClusterID-nyw5e-000000000000000:
+        # This volume is in the "default" storage class.
+        StorageClasses:
+          default: true
+      ClusterID-nyw5e-000000000000001:
+        # Specify this volume is in the "archival" storage class.
+        StorageClasses:
+          archival: true
Names of storage classes are internal to the cluster and decided by the administrator. Aside from "default", Arvados currently does not define any standard storage class names. diff --git a/doc/admin/workbench2-vocabulary.html.textile.liquid b/doc/admin/workbench2-vocabulary.html.textile.liquid index e259f78625..9a8d7fcd01 100644 --- a/doc/admin/workbench2-vocabulary.html.textile.liquid +++ b/doc/admin/workbench2-vocabulary.html.textile.liquid @@ -1,7 +1,7 @@ --- layout: default navsection: admin -title: Workbench2 Vocabulary Format +title: User properties vocabulary ... {% comment %} @@ -64,4 +64,4 @@ Also, take into consideration that this example script does case-sensitive match {% codeblock as python %} {% include 'vocabulary_migrate_py' %} -{% endcodeblock %} \ No newline at end of file +{% endcodeblock %} -- 2.30.2