doc/user/cwl/cwl-extensions.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: Arvados CWL Extensions
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 Arvados provides several extensions to CWL for workflow optimization, site-specific configuration, and to enable access the Arvados API.
  13
  14 To use Arvados CWL extensions, add the following @$namespaces@ section at the top of your CWL file:
  15
  16 <pre>
  17 $namespaces:
  18   arv: "http://arvados.org/cwl#"
  19   cwltool: "http://commonwl.org/cwltool#"
  20 </pre>
  21
  22 For portability, Arvados extensions should go into the @hints@ section of your CWL file, for example:
  23
  24 <pre>
  25 hints:
  26   arv:RunInSingleContainer: {}
  27   arv:RuntimeConstraints:
  28     keep_cache: 123456
  29     outputDirType: keep_output_dir
  30   arv:PartitionRequirement:
  31     partition: dev_partition
  32   arv:APIRequirement: {}
  33   cwltool:LoadListingRequirement:
  34     loadListing: shallow_listing
  35   arv:IntermediateOutput:
  36     outputTTL: 3600
  37   arv:ReuseRequirement:
  38     enableReuse: false
  39   cwltool:Secrets:
  40     secrets: [input1, input2]
  41   cwltool:TimeLimit:
  42     timelimit: 14400
  43   arv:WorkflowRunnerResources:
  44     ramMin: 2048
  45     coresMin: 2
  46 </pre>
  47
  48 The one exception to this is @arv:APIRequirement@, see note below.
  49
  50 h2. arv:RunInSingleContainer
  51
  52 Indicates that a subworkflow should run in a single container and not be scheduled as separate steps.
  53
  54 h2. arv:RuntimeConstraints
  55
  56 Set Arvados-specific runtime hints.
  57
  58 table(table table-bordered table-condensed).
  59 |_. Field |_. Type |_. Description |
  60 |keep_cache|int|Size of file data buffer for Keep mount in MiB. Default is 256 MiB. Increase this to reduce cache thrashing in situations such as accessing multiple large (64+ MiB) files at the same time, or performing random access on a large file.|
  61 |outputDirType|enum|Preferred backing store for output staging.  If not specified, the system may choose which one to use.  One of *local_output_dir* or *keep_output_dir*|
  62
  63 *local_output_dir*: Use regular file system local to the compute node. There must be sufficient local scratch space to store entire output; specify this with @outdirMin@ of @ResourceRequirement@.  Files are batch uploaded to Keep when the process completes.  Most compatible, but upload step can be time consuming for very large files.
  64
  65 *keep_output_dir*: Use writable Keep mount.  Files are streamed to Keep as they are written.  Does not consume local scratch space, but does consume RAM for output buffers (up to 192 MiB per file simultaneously open for writing.)  Best suited to processes which produce sequential output of large files (non-sequential writes may produced fragmented file manifests).  Supports regular files and directories, does not support special files such as symlinks, hard links, named pipes, named sockets, or device nodes.|
  66
  67 h2. arv:PartitionRequirement
  68
  69 Select preferred compute partitions on which to run jobs.
  70
  71 table(table table-bordered table-condensed).
  72 |_. Field |_. Type |_. Description |
  73 |partition|string or array of strings||
  74
  75 h2. arv:APIRequirement
  76
  77 Indicates that process wants to access to the Arvados API.  Will be granted network access and have @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ set in the environment.  Tools which rely on the Arvados API being present should put @arv:APIRequirement@ in the @requirements@ section of the tool (rather than @hints@) to indicate that that it is not portable to non-Arvados CWL runners.
  78
  79 Use @arv:APIRequirement@ in @hints@ to enable general (non-Arvados-specific) network access for a tool.
  80
  81 h2. cwltool:LoadListingRequirement
  82
  83 In CWL v1.0 documents, the default behavior for Directory objects is to recursively expand the @listing@ for access by parameter references an expressions.  For directory trees containing many files, this can be expensive in both time and memory usage.  Use @cwltool:LoadListingRequirement@ to change the behavior for expansion of directory listings in the workflow runner.
  84
  85 table(table table-bordered table-condensed).
  86 |_. Field |_. Type |_. Description |
  87 |loadListing|string|One of @no_listing@, @shallow_listing@, or @deep_listing@|
  88
  89 *no_listing*: Do not expand directory listing at all.  The @listing@ field on the Directory object will be undefined.
  90
  91 *shallow_listing*: Only expand the first level of directory listing.  The @listing@ field on the toplevel Directory object will contain the directory contents, however @listing@ will not be defined on subdirectories.
  92
  93 *deep_listing*: Recursively expand all levels of directory listing.  The @listing@ field will be provided on the toplevel object and all subdirectories.
  94
  95 h2. arv:IntermediateOutput
  96
  97 Specify desired handling of intermediate output collections.
  98
  99 table(table table-bordered table-condensed).
 100 |_. Field |_. Type |_. Description |
 101 |outputTTL|int|If the value is greater than zero, consider intermediate output collections to be temporary and should be automatically trashed. Temporary collections will be trashed @outputTTL@ seconds after creation.  A value of zero means intermediate output should be retained indefinitely (this is the default behavior).
 102 Note: arvados-cwl-runner currently does not take workflow dependencies into account when setting the TTL on an intermediate output collection. If the TTL is too short, it is possible for a collection to be trashed before downstream steps that consume it are started.  The recommended minimum value for TTL is the expected duration of the entire the workflow.|
 103
 104 h2. arv:ReuseRequirement
 105
 106 Enable/disable work reuse for current process.  Default true (work reuse enabled).
 107
 108 table(table table-bordered table-condensed).
 109 |_. Field |_. Type |_. Description |
 110 |enableReuse|boolean|Enable/disable work reuse for current process.  Default true (work reuse enabled).|
 111
 112 h2. cwltool:Secrets
 113
 114 Indicate that one or more input parameters are "secret".  Must be applied at the top level Workflow.  Secret parameters are not stored in keep, are hidden from logs and API responses, and are wiped from the database after the workflow completes.
 115
 116 table(table table-bordered table-condensed).
 117 |_. Field |_. Type |_. Description |
 118 |secrets|array<string>|Input parameters which are considered "secret".  Must be strings.|
 119
 120
 121 h2. cwltool:TimeLimit
 122
 123 Set an upper limit on the execution time of a CommandLineTool or ExpressionTool.  A tool execution which exceeds the time limit may be preemptively terminated and considered failed.  May also be used by batch systems to make scheduling decisions.
 124
 125 table(table table-bordered table-condensed).
 126 |_. Field |_. Type |_. Description |
 127 |timelimit|int|Execution time limit in seconds. If set to zero, no limit is enforced.|
 128
 129 h2. arv:WorkflowRunnerResources
 130
 131 Specify resource requirements for the workflow runner process (arvados-cwl-runner) that manages a workflow run.  Must be applied to the top level workflow.  Will also be set implicitly when using @--submit-runner-ram@ on the command line along with @--create-workflow@ or @--update-workflow@.  Use this to adjust the runner's allocation if the workflow runner is getting "out of memory" exceptions or being killed by the out-of-memory (OOM) killer.
 132
 133 table(table table-bordered table-condensed).
 134 |_. Field |_. Type |_. Description |
 135 |ramMin|int|RAM, in mebibytes, to reserve for the arvados-cwl-runner process. Default 1 GiB|
 136 |coresMin|int|Number of cores to reserve to the arvados-cwl-runner process. Default 1 core.|