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 {% codeblock as yaml %}
  17 $namespaces:
  18   arv: "http://arvados.org/cwl#"
  19   cwltool: "http://commonwl.org/cwltool#"
  20 {% endcodeblock %}
  21
  22 For portability, most Arvados extensions should go into the @hints@ section of your CWL file.  This makes it possible for your workflows to run other CWL runners that do not recognize Arvados hints.  The difference between @hints@ and @requirements@ is that @hints@ are optional features that can be ignored by other runners and still produce the same output, whereas @requirements@ will fail the workflow if they cannot be fulfilled.  For example, @arv:IntermediateOutput@ should go in @hints@ as it will have no effect on non-Arvados platforms, however if your workflow explicitly accesses the Arvados API and will fail without it, you should put @arv:APIRequirement@ in @requirements@.
  23
  24 {% codeblock as yaml %}
  25 hints:
  26   arv:RunInSingleContainer: {}
  27
  28   arv:RuntimeConstraints:
  29     keep_cache: 123456
  30     outputDirType: keep_output_dir
  31
  32   arv:PartitionRequirement:
  33     partition: dev_partition
  34
  35   arv:APIRequirement: {}
  36
  37   arv:IntermediateOutput:
  38     outputTTL: 3600
  39
  40   cwltool:Secrets:
  41     secrets: [input1, input2]
  42
  43   arv:WorkflowRunnerResources:
  44     ramMin: 2048
  45     coresMin: 2
  46     keep_cache: 512
  47
  48   arv:ClusterTarget:
  49     cluster_id: clsr1
  50     project_uuid: clsr1-j7d0g-qxc4jcji7n4lafx
  51
  52   arv:OutputStorageClass:
  53     intermediateStorageClass: fast_storage
  54     finalStorageClass: robust_storage
  55
  56   arv:ProcessProperties:
  57     processProperties:
  58       property1: value1
  59       property2: $(inputs.value2)
  60
  61   arv:OutputCollectionProperties:
  62     outputProperties:
  63       property1: value1
  64       property2: $(inputs.value2)
  65
  66   cwltool:CUDARequirement:
  67     cudaVersionMin: "11.0"
  68     cudaComputeCapability: "9.0"
  69     cudaDeviceCountMin: 1
  70     cudaDeviceCountMax: 1
  71
  72   arv:UsePreemptible:
  73     usePreemptible: true
  74
  75   arv:OutOfMemoryRetry:
  76     memoryRetryMultiplier: 2
  77     memoryErrorRegex: "custom memory error"
  78 {% endcodeblock %}
  79
  80 h2(#RunInSingleContainer). arv:RunInSingleContainer
  81
  82 Apply this to a workflow step that runs a subworkflow.  Indicates that all the steps of the subworkflow should run together in a single container and not be scheduled separately.  If you have a sequence of short-running steps (less than 1-2 minutes each) this enables you to avoid scheduling and data transfer overhead by running all the steps together at once.  To use this feature, @cwltool@ must be installed in the container image.
  83
  84 h2. arv:RuntimeConstraints
  85
  86 Set Arvados-specific runtime hints.
  87
  88 table(table table-bordered table-condensed).
  89 |_. Field |_. Type |_. Description |
  90 |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.|
  91 |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*|
  92
  93 *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.
  94
  95 *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.|
  96
  97 h2. arv:PartitionRequirement
  98
  99 Select preferred compute partitions on which to run jobs.
 100
 101 table(table table-bordered table-condensed).
 102 |_. Field |_. Type |_. Description |
 103 |partition|string or array of strings||
 104
 105 h2(#APIRequirement). arv:APIRequirement
 106
 107 For CWL v1.1 scripts, if a step requires network access but not specifically access to the Arvados API server, prefer the standard feature "NetworkAccess":https://www.commonwl.org/v1.1/CommandLineTool.html#NetworkAccess .  In the future, these may be differentiated by whether ARVADOS_API_HOST and ARVADOS_API_TOKEN is injected into the container or not.
 108
 109 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.
 110
 111 Use @arv:APIRequirement@ in @hints@ to enable general (non-Arvados-specific) network access for a tool.
 112
 113 h2. arv:IntermediateOutput
 114
 115 Specify desired handling of intermediate output collections.
 116
 117 table(table table-bordered table-condensed).
 118 |_. Field |_. Type |_. Description |
 119 |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).
 120 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 workflow.|
 121
 122 h2. cwltool:Secrets
 123
 124 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.
 125
 126 *Note: currently, workflows with secrets must be submitted on the command line using @arvados-cwl-runner@.  Workflows with secrets submitted through Workbench will not properly obscure the secret inputs.*
 127
 128 table(table table-bordered table-condensed).
 129 |_. Field |_. Type |_. Description |
 130 |secrets|array<string>|Input parameters which are considered "secret".  Must be strings.|
 131
 132 h2. arv:WorkflowRunnerResources
 133
 134 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.
 135
 136 table(table table-bordered table-condensed).
 137 |_. Field |_. Type |_. Description |
 138 |ramMin|int|RAM, in mebibytes, to reserve for the arvados-cwl-runner process. Default 1 GiB|
 139 |coresMin|int|Number of cores to reserve to the arvados-cwl-runner process. Default 1 core.|
 140 |keep_cache|int|Size of collection metadata cache for the workflow runner, in MiB.  Default 256 MiB.  Will be added on to the RAM request when determining node size to request.|
 141
 142 h2(#clustertarget). arv:ClusterTarget
 143
 144 Specify which Arvados cluster should execute a container or subworkflow, and the parent project for the container request.
 145
 146 table(table table-bordered table-condensed).
 147 |_. Field |_. Type |_. Description |
 148 |cluster_id|string|The five-character alphanumeric cluster id (uuid prefix) where a container or subworkflow will execute.  May be an expression.|
 149 |project_uuid|string|The uuid of the project which will own container request and output of the container.  May be an expression.|
 150
 151 h2(#OutputStorageClass). arv:OutputStorageClass
 152
 153 Specify the "storage class":{{site.baseurl}}/user/topics/storage-classes.html to use for intermediate and final outputs.
 154
 155 table(table table-bordered table-condensed).
 156 |_. Field |_. Type |_. Description |
 157 |intermediateStorageClass|string or array of strings|The storage class for output of intermediate steps.  For example, faster "hot" storage.|
 158 |finalStorageClass_uuid|string or array of strings|The storage class for the final output.  |
 159
 160 h2(#ProcessProperties). arv:ProcessProperties
 161
 162 Specify extra "properties":{{site.baseurl}}/api/methods.html#subpropertyfilters that will be set on container requests created by the workflow.  May be set on a Workflow or a CommandLineTool.  Setting custom properties on a container request simplifies queries to find the workflow run later on.
 163
 164 table(table table-bordered table-condensed).
 165 |_. Field |_. Type |_. Description |
 166 |processProperties|key-value map, or list of objects with the fields {propertyName, propertyValue}|The properties that will be set on the container request.  May include expressions that reference @$(inputs)@ of the current workflow or tool.|
 167
 168 h2(#OutputCollectionProperties). arv:OutputCollectionProperties
 169
 170 Specify custom "properties":{{site.baseurl}}/api/methods.html#subpropertyfilters that will be set on the output collection of the workflow step.
 171
 172 table(table table-bordered table-condensed).
 173 |_. Field |_. Type |_. Description |
 174 |outputProperties|key-value map, or list of objects with the fields {propertyName, propertyValue}|The properties that will be set on the output collection.  May include expressions that reference @$(inputs)@ of the current workflow or tool.|
 175
 176 h2(#CUDARequirement). cwltool:CUDARequirement
 177
 178 Request support for Nvidia CUDA GPU acceleration in the container.  Assumes that the CUDA runtime (SDK) is installed in the container, and the host will inject the CUDA driver libraries into the container (equal or later to the version requested).
 179
 180 table(table table-bordered table-condensed).
 181 |_. Field |_. Type |_. Description |
 182 |cudaVersionMin|string|Required.  The CUDA SDK version corresponding to the minimum driver version supported by the container (generally, the SDK version 'X.Y' the application was compiled against).|
 183 |cudaComputeCapability|string|Required.  The minimum CUDA hardware capability (in 'X.Y' format) required by the application's PTX or C++ GPU code (will be JIT compiled for the available hardware).|
 184 |cudaDeviceCountMin|integer|Minimum number of GPU devices to allocate on a single node. Required.|
 185 |cudaDeviceCountMax|integer|Maximum number of GPU devices to allocate on a single node. Optional.  If not specified, same as @cudaDeviceCountMin@.|
 186
 187 h2(#UsePreemptible). arv:UsePreemptible
 188
 189 Specify whether a workflow step should request preemptible (e.g. AWS Spot market) instances.  Such instances are generally cheaper, but can be taken back by the cloud provider at any time (preempted) causing the step to fail.  When this happens, Arvados will automatically re-try the step, up to the configuration value of @Containers.MaxRetryAttempts@ (default 3) times.
 190
 191 table(table table-bordered table-condensed).
 192 |_. Field |_. Type |_. Description |
 193 |usePreemptible|boolean|Required, true to opt-in to using preemptible instances, false to opt-out.|
 194
 195
 196 h2(#OutOfMemoryRetry). arv:OutOfMemoryRetry
 197
 198 Specify that when a workflow step appears to have failed because it did not request enough RAM, it should be re-submitted with more RAM.  Out of memory conditions are detected either by the container being unexpectedly killed (exit code 137) or by matching a pattern in the container's output (see @memoryErrorRegex@).  Retrying will increase the base RAM request by the value of @memoryRetryMultiplier@.  For example, if the original RAM request was 10 GiB and the multiplier is 1.5, then it will re-submit with 15 GiB.
 199
 200 Containers are only re-submitted once.  If it fails a second time after increasing RAM, then the worklow step will still fail.
 201
 202 Also note that expressions that use @$(runtime.ram)@ (such as dynamic command line parameters) are not reevaluated when the container is resubmitted.
 203
 204 table(table table-bordered table-condensed).
 205 |_. Field |_. Type |_. Description |
 206 |memoryRetryMultiplier|float|Optional, default value is 2.  The retry will multiply the base memory request by this factor to get the retry memory request.|
 207 |memoryErrorRegex|string|Optional, a custom regex that, if found in the stdout, stderr or crunch-run logging of a program, will trigger a retry with greater RAM.  If not provided, the default pattern matches "out of memory" (with or without spaces), "memory error" (with or without spaces), "bad_alloc" and "container using over 90% of memory".|
 208
 209 h2. arv:dockerCollectionPDH
 210
 211 This is an optional extension field appearing on the standard @DockerRequirement@.  It specifies the portable data hash of the Arvados collection containing the Docker image.  If present, it takes precedence over @dockerPull@ or @dockerImageId@.
 212
 213 <pre>
 214 requirements:
 215   DockerRequirement:
 216     dockerPull: "debian:10"
 217     arv:dockerCollectionPDH: "feaf1fc916103d7cdab6489e1f8c3a2b+174"
 218 </pre>
 219
 220 h1. Deprecated extensions
 221
 222 The following extensions are deprecated because equivalent features are part of the CWL v1.1 standard.
 223
 224 {% codeblock as yaml %}
 225 hints:
 226   cwltool:LoadListingRequirement:
 227     loadListing: shallow_listing
 228   arv:ReuseRequirement:
 229     enableReuse: false
 230   cwltool:TimeLimit:
 231     timelimit: 14400
 232 {% endcodeblock %}
 233
 234 h2. cwltool:LoadListingRequirement
 235
 236 For CWL v1.1 scripts, this is deprecated in favor of "loadListing":https://www.commonwl.org/v1.1/CommandLineTool.html#CommandInputParameter or "LoadListingRequirement":https://www.commonwl.org/v1.1/CommandLineTool.html#LoadListingRequirement
 237
 238 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.
 239
 240 table(table table-bordered table-condensed).
 241 |_. Field |_. Type |_. Description |
 242 |loadListing|string|One of @no_listing@, @shallow_listing@, or @deep_listing@|
 243
 244 *no_listing*: Do not expand directory listing at all.  The @listing@ field on the Directory object will be undefined.
 245
 246 *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.
 247
 248 *deep_listing*: Recursively expand all levels of directory listing.  The @listing@ field will be provided on the toplevel object and all subdirectories.
 249
 250 h2. arv:ReuseRequirement
 251
 252 For CWL v1.1 scripts, this is deprecated in favor of "WorkReuse":https://www.commonwl.org/v1.1/CommandLineTool.html#WorkReuse .
 253
 254 Enable/disable work reuse for current process.  Default true (work reuse enabled).
 255
 256 table(table table-bordered table-condensed).
 257 |_. Field |_. Type |_. Description |
 258 |enableReuse|boolean|Enable/disable work reuse for current process.  Default true (work reuse enabled).|
 259
 260 h2. cwltool:TimeLimit
 261
 262 For CWL v1.1 scripts, this is deprecated in favor of "ToolTimeLimit":https://www.commonwl.org/v1.1/CommandLineTool.html#ToolTimeLimit
 263
 264 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.
 265
 266 table(table table-bordered table-condensed).
 267 |_. Field |_. Type |_. Description |
 268 |timelimit|int|Execution time limit in seconds. If set to zero, no limit is enforced.|