13570: Add formulas. Add link from cwl-style to crunch discussion.
[arvados.git] / doc / api / execution.html.textile.liquid
index 998874763ec3ee39334e8499100c8e0282e2e322..f7772cb2f73f91b898c4f418a13138025abf9caa 100644 (file)
@@ -1,6 +1,6 @@
 ---
 layout: default
-navsection: api
+navsection: architecture
 title: Computing with Crunch
 ...
 {% comment %}
@@ -13,8 +13,6 @@ Crunch is the name for the Arvados system for managing computation.  It provides
 
 h2. Container API
 
-Note: although the preferred API for Arvados going forward, the Container API may not yet be available on all installations.
-
 # To submit work, create a "container request":{{site.baseurl}}/api/methods/container_requests.html in the @Committed@ state.
 # The system will fufill the container request by creating or reusing a "Container object":{{site.baseurl}}/api/methods/containers.html and assigning it to the @container_uuid@ field.  If the same request has been submitted in the past, it may reuse an existing container.  The reuse behavior can be suppressed with @use_existing: false@ in the container request.
 # The dispatcher process will notice a new container in @Queued@ state and submit a container executor to the underlying work queuing system (such as SLURM).
@@ -22,7 +20,35 @@ Note: although the preferred API for Arvados going forward, the Container API ma
 # When the container associated with the container request is completed, the container request will go into the @Final@ state.
 # The @output_uuid@ field of the container request contains the uuid of output collection produced by container request.
 
-!{{site.baseurl}}/images/Crunch_dispatch.svg!
+!(full-width){{site.baseurl}}/images/Crunch_dispatch.svg!
+
+h2(#RAM). Understanding RAM requests for containers
+
+The @runtime_constraints@ section of a container specifies working RAM (@ram@) and keep cache (@keep_cache_ram@).  If not specified, containers get a default keep cache (@container_default_keep_cache_ram@, default 256 MiB).  The total RAM requested for a container is the sum of working RAM, keep cache, and an additional RAM reservation configured by the admin (@ReserveExtraRAM@ in the dispatcher configuration, default zero).
+
+The total RAM request is used to schedule containers onto compute nodes.  On HPC systems, multiple containers may run on a multi-core node.  RAM allocation limits may be enforced using kernel controls such as cgroups.
+
+When running on the cloud, the memory request (along with CPU and disk) is used to select (and possibly boot) an instance type with adequate resources to run the container.  Instance type RAM is derated 5% from the published specification to accomodate virtual machine, kernel and system services overhead.
+
+h3. Calculate minimum instance type RAM for a container
+
+    (RAM request + keep cache + ReserveExtraRAM) * (100/95)
+
+For example, for a 3 GiB request, default keep cache, and no extra RAM reserved:
+
+    (3072 + 256) * 1.0526 = 3494 MiB
+
+To run this container, the instance type must have a published RAM size of at least 3494 MiB.
+
+h3. Calculate the maximum requestable RAM for an instance type
+
+    (Instance type RAM * (95/100)) - keep cache - ReserveExtraRAM
+
+For example, for a 3.75 GiB node, default keep cache, and no extra RAM reserved:
+
+    (3840 * 0.95) - 256 = 3392 MiB
+
+To run on this instance type, the container can request at most 3392 MiB of working RAM.
 
 h2. Job API (deprecated)