Merge branch '11016-doc-signing-ttl'

[arvados.git] / lib / config / config.default.yml

diff --git a/lib/config/config.default.yml b/lib/config/config.default.yml
index 4cbb7784f82c16dd78dd2528fbc182b8c72e2636..4e3bf6d6c937d89ccdc8cdd1781e5f3d76425965 100644 (file)
--- a/lib/config/config.default.yml
+++ b/lib/config/config.default.yml
@@ -368,13 +368,26 @@ Clusters:
       # collection's replication_desired attribute is nil.
       DefaultReplication: 2
 
-      # Lifetime (in seconds) of blob permission signatures generated by
-      # the API server. This determines how long a client can take (after
-      # retrieving a collection record) to retrieve the collection data
-      # from Keep. If the client needs more time than that (assuming the
-      # collection still has the same content and the relevant user/token
-      # still has permission) the client can retrieve the collection again
-      # to get fresh signatures.
+      # BlobSigningTTL determines the minimum lifetime of transient
+      # data, i.e., blocks that are not referenced by
+      # collections. Unreferenced blocks exist for two reasons:
+      #
+      # 1) A data block must be written to a disk/cloud backend device
+      # before a collection can be created/updated with a reference to
+      # it.
+      #
+      # 2) Deleting or updating a collection can remove the last
+      # remaining reference to a data block.
+      #
+      # If BlobSigningTTL is too short, long-running
+      # processes/containers will fail when they take too long (a)
+      # between writing blocks and writing collections that reference
+      # them, or (b) between reading collections and reading the
+      # referenced blocks.
+      #
+      # If BlobSigningTTL is too long, data will still be stored long
+      # after the referring collections are deleted, and you will
+      # needlessly fill up disks or waste money on cloud storage.
       #
       # Modifying BlobSigningTTL invalidates existing signatures; see
       # BlobSigningKey note above.