Merge branch '11016-doc-signing-ttl'

[arvados.git] / lib / config / generated_config.go

diff --git a/lib/config/generated_config.go b/lib/config/generated_config.go
index 40827f8e2fbeaff4b74b1f7aa8c46db35afbe087..d21bb2d284b57d5dfff01a346c0708d98ca8db13 100644 (file)
--- a/lib/config/generated_config.go
+++ b/lib/config/generated_config.go
@@ -374,13 +374,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.