Merge branch '14366-crunch2-upgrade' refs #14366
[arvados.git] / doc / user / cwl / cwl-style.html.textile.liquid
index 0debd16a15cfae5a5bad1aa7279494837cdc19de..fe53f4a4548b40c0ecd076db36186118da3cb14d 100644 (file)
@@ -3,6 +3,11 @@ layout: default
 navsection: userguide
 title: Best Practices for writing CWL
 ...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
 
 * To run on Arvados, a workflow should provide a @DockerRequirement@ in the @hints@ section.
 
@@ -108,6 +113,8 @@ steps:
         tmpdirMin: 90000
 </pre>
 
+* Available compute nodes types vary over time and across different cloud providers, so try to limit the RAM requirement to what the program actually needs.  However, if you need to target a specific compute node type, see this discussion on "calculating RAM request and choosing instance type for containers.":{{site.baseurl}}/api/execution.html#RAM
+
 * Instead of scattering separate steps, prefer to scatter over a subworkflow.
 
 With the following pattern, @step1@ has to wait for all samples to complete before @step2@ can start computing on any samples.  This means a single long-running sample can prevent the rest of the workflow from moving on:
@@ -168,3 +175,11 @@ steps:
           out: [out]
           run: tool3.cwl
 </pre>
+
+h2(#migrate). Migrating running CWL on jobs API to containers API
+
+When migrating from jobs API (--api=jobs) (sometimes referred to as "crunch v1") to the containers API (--api=containers) ("crunch v2") there are a few differences in behavior:
+
+* A tool may fail to find an input file that could be found when run under the jobs API.  This is because tools are limited to accessing collections explicitly listed in the input, and further limited to those individual files or subdirectories that are listed.  For example, given an explicit file input @/dir/subdir/file1.txt@, a tool will not be allowed to implicitly access a file in the parent directory @/dir/file2.txt@.  Use @secondaryFiles@ or a @Directory@ for files that need to be grouped together.
+* A tool may fail when attempting to rename or delete a file in the output directory.  This may happen because files listed in @InitialWorkDirRequirement@ appear in the output directory as normal files (not symlinks) but cannot be moved, renamed or deleted unless marked as "writable" in CWL.  These files will be added to the output collection but without any additional copies of the underlying data.
+* A tool may fail when attempting to access the network.  This may happen because, unlike the jobs API, under the containers API network access is disabled by default.  Tools which require network access should add @arv:APIRequirement: {}@ to the @requirements@ section.