To use Arvados CWL extensions, add the following @$namespaces@ section at the top of your CWL file:
-<pre>
+{% codeblock as yaml %}
$namespaces:
arv: "http://arvados.org/cwl#"
cwltool: "http://commonwl.org/cwltool#"
-</pre>
+{% endcodeblock %}
-For portability, Arvados extensions should go into the @hints@ section of your CWL file, for example:
+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@.
-<pre>
+{% codeblock as yaml %}
hints:
arv:RunInSingleContainer: {}
+
arv:RuntimeConstraints:
keep_cache: 123456
outputDirType: keep_output_dir
+
arv:PartitionRequirement:
partition: dev_partition
+
arv:APIRequirement: {}
- cwltool:LoadListingRequirement:
- loadListing: shallow_listing
+
arv:IntermediateOutput:
outputTTL: 3600
- arv:ReuseRequirement:
- enableReuse: false
+
cwltool:Secrets:
secrets: [input1, input2]
- cwltool:TimeLimit:
- timelimit: 14400
+
arv:WorkflowRunnerResources:
ramMin: 2048
coresMin: 2
keep_cache: 512
+
arv:ClusterTarget:
cluster_id: clsr1
project_uuid: clsr1-j7d0g-qxc4jcji7n4lafx
-</pre>
-The one exception to this is @arv:APIRequirement@, see note below.
+ arv:OutputStorageClass:
+ intermediateStorageClass: fast_storage
+ finalStorageClass: robust_storage
+
+ arv:ProcessProperties:
+ processProperties:
+ property1: value1
+ property2: $(inputs.value2)
+
+ arv:OutputCollectionProperties:
+ outputProperties:
+ property1: value1
+ property2: $(inputs.value2)
-h2. arv:RunInSingleContainer
+ cwltool:CUDARequirement:
+ cudaVersionMin: "11.0"
+ cudaComputeCapability: "9.0"
+ cudaDeviceCountMin: 1
+ cudaDeviceCountMax: 1
-Indicates that a subworkflow should run in a single container and not be scheduled as separate steps.
+ arv:UsePreemptible:
+ usePreemptible: true
+{% endcodeblock %}
+
+h2(#RunInSingleContainer). arv:RunInSingleContainer
+
+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.
h2. arv:RuntimeConstraints
|_. Field |_. Type |_. Description |
|partition|string or array of strings||
-h2. arv:APIRequirement
+h2(#APIRequirement). arv:APIRequirement
+
+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.
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.
Use @arv:APIRequirement@ in @hints@ to enable general (non-Arvados-specific) network access for a tool.
-h2. cwltool:LoadListingRequirement
+h2. arv:IntermediateOutput
-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.
+Specify desired handling of intermediate output collections.
table(table table-bordered table-condensed).
|_. Field |_. Type |_. Description |
-|loadListing|string|One of @no_listing@, @shallow_listing@, or @deep_listing@|
+|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).
+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.|
-*no_listing*: Do not expand directory listing at all. The @listing@ field on the Directory object will be undefined.
+h2. cwltool:Secrets
-*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.
+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.
-*deep_listing*: Recursively expand all levels of directory listing. The @listing@ field will be provided on the toplevel object and all subdirectories.
+*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.*
-h2. arv:IntermediateOutput
+table(table table-bordered table-condensed).
+|_. Field |_. Type |_. Description |
+|secrets|array<string>|Input parameters which are considered "secret". Must be strings.|
-Specify desired handling of intermediate output collections.
+h2. arv:WorkflowRunnerResources
+
+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.
table(table table-bordered table-condensed).
|_. Field |_. Type |_. Description |
-|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).
-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.|
+|ramMin|int|RAM, in mebibytes, to reserve for the arvados-cwl-runner process. Default 1 GiB|
+|coresMin|int|Number of cores to reserve to the arvados-cwl-runner process. Default 1 core.|
+|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.|
-h2. arv:ReuseRequirement
+h2(#clustertarget). arv:ClusterTarget
-Enable/disable work reuse for current process. Default true (work reuse enabled).
+Specify which Arvados cluster should execute a container or subworkflow, and the parent project for the container request.
table(table table-bordered table-condensed).
|_. Field |_. Type |_. Description |
-|enableReuse|boolean|Enable/disable work reuse for current process. Default true (work reuse enabled).|
+|cluster_id|string|The five-character alphanumeric cluster id (uuid prefix) where a container or subworkflow will execute. May be an expression.|
+|project_uuid|string|The uuid of the project which will own container request and output of the container. May be an expression.|
-h2. cwltool:Secrets
+h2(#OutputStorageClass). arv:OutputStorageClass
-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.
+Specify the "storage class":{{site.baseurl}}/user/topics/storage-classes.html to use for intermediate and final outputs.
table(table table-bordered table-condensed).
|_. Field |_. Type |_. Description |
-|secrets|array<string>|Input parameters which are considered "secret". Must be strings.|
+|intermediateStorageClass|string or array of strings|The storage class for output of intermediate steps. For example, faster "hot" storage.|
+|finalStorageClass_uuid|string or array of strings|The storage class for the final output. |
+h2(#ProcessProperties). arv:ProcessProperties
-h2. cwltool:TimeLimit
+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.
-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.
+table(table table-bordered table-condensed).
+|_. Field |_. Type |_. Description |
+|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.|
+
+h2(#OutputCollectionProperties). arv:OutputCollectionProperties
+
+Specify custom "properties":{{site.baseurl}}/api/methods.html#subpropertyfilters that will be set on the output collection of the workflow step.
table(table table-bordered table-condensed).
|_. Field |_. Type |_. Description |
-|timelimit|int|Execution time limit in seconds. If set to zero, no limit is enforced.|
+|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.|
-h2. arv:WorkflowRunnerResources
+h2(#CUDARequirement). cwltool:CUDARequirement
-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.
+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).
table(table table-bordered table-condensed).
|_. Field |_. Type |_. Description |
-|ramMin|int|RAM, in mebibytes, to reserve for the arvados-cwl-runner process. Default 1 GiB|
-|coresMin|int|Number of cores to reserve to the arvados-cwl-runner process. Default 1 core.|
-|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.|
+|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).|
+|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).|
+|cudaDeviceCountMin|integer|Minimum number of GPU devices to allocate on a single node. Required.|
+|cudaDeviceCountMax|integer|Maximum number of GPU devices to allocate on a single node. Optional. If not specified, same as @cudaDeviceCountMin@.|
-h2(#clustertarget). arv:ClusterTarget
+h2(#UsePreemptible). arv:UsePreemptible
-Specify which Arvados cluster should execute a container or subworkflow, and the parent project for the container request.
+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.
table(table table-bordered table-condensed).
|_. Field |_. Type |_. Description |
-|cluster_id|string|The five-character alphanumeric cluster id (uuid prefix) where a container or subworkflow will execute. May be an expression.|
-|project_uuid|string|The uuid of the project which will own container request and output of the container. May be an expression.|
+|usePreemptible|boolean|Required, true to opt-in to using preemptible instances, false to opt-out.|
h2. arv:dockerCollectionPDH
<pre>
requirements:
DockerRequirement:
- dockerPull: "debian:8"
+ dockerPull: "debian:10"
arv:dockerCollectionPDH: "feaf1fc916103d7cdab6489e1f8c3a2b+174"
</pre>
+
+h1. Deprecated extensions
+
+The following extensions are deprecated because equivalent features are part of the CWL v1.1 standard.
+
+{% codeblock as yaml %}
+hints:
+ cwltool:LoadListingRequirement:
+ loadListing: shallow_listing
+ arv:ReuseRequirement:
+ enableReuse: false
+ cwltool:TimeLimit:
+ timelimit: 14400
+{% endcodeblock %}
+
+h2. cwltool:LoadListingRequirement
+
+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
+
+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.
+
+table(table table-bordered table-condensed).
+|_. Field |_. Type |_. Description |
+|loadListing|string|One of @no_listing@, @shallow_listing@, or @deep_listing@|
+
+*no_listing*: Do not expand directory listing at all. The @listing@ field on the Directory object will be undefined.
+
+*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.
+
+*deep_listing*: Recursively expand all levels of directory listing. The @listing@ field will be provided on the toplevel object and all subdirectories.
+
+h2. arv:ReuseRequirement
+
+For CWL v1.1 scripts, this is deprecated in favor of "WorkReuse":https://www.commonwl.org/v1.1/CommandLineTool.html#WorkReuse .
+
+Enable/disable work reuse for current process. Default true (work reuse enabled).
+
+table(table table-bordered table-condensed).
+|_. Field |_. Type |_. Description |
+|enableReuse|boolean|Enable/disable work reuse for current process. Default true (work reuse enabled).|
+
+h2. cwltool:TimeLimit
+
+For CWL v1.1 scripts, this is deprecated in favor of "ToolTimeLimit":https://www.commonwl.org/v1.1/CommandLineTool.html#ToolTimeLimit
+
+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.
+
+table(table table-bordered table-condensed).
+|_. Field |_. Type |_. Description |
+|timelimit|int|Execution time limit in seconds. If set to zero, no limit is enforced.|
projects / arvados.git / blobdiff