container_requests

API endpoint base: https://pirca.arvadosapi.com/arvados/v1/container_requests

Object type: xvhdp

Example UUID: zzzzz-xvhdp-0123456789abcde

Resource

A container request is a request for the Arvados cluster to perform some computational work. See computing with Crunch for details.

Each ContainerRequest offers the following attributes, in addition to the Common resource fields:

All attributes are optional, unless otherwise marked as required.

{
  "ram":12000000000,
  "vcpus":2,
  "API":true
}

{
"partitions":["fastcpu","vfastcpu"]
}

Priority

The priority field has a range of 0-1000.

Priority 0 means no container should run on behalf of this request, and containers already running will be terminated (setting container priority to 0 is the cancel operation.)

Priority 1 is the lowest priority.

Priority 1000 is the highest priority.

The actual order that containers execute is determined by the underlying scheduling software (e.g. SLURM) and may be based on a combination of container priority, submission time, available resources, and other factors.

In the current implementation, the magnitude of difference in priority between two containers affects the weight of priority vs age in determining scheduling order. If two containers have only a small difference in priority (for example, 500 and 501) and the lower priority container has a longer queue time, the lower priority container may be scheduled before the higher priority container. Use a greater magnitude difference (for example, 500 and 600) to give higher weight to priority over queue time.

Mount types

The “mounts” hash is the primary mechanism for adding data to the container at runtime (beyond what is already in the container image).

Each value of the “mounts” hash is itself a hash, whose “kind” key determines the handler used to attach data to the container.

{
 "kind":"collection",
 "uuid":"...",
 "path":"/foo.txt"
}
{
 "kind":"collection",
 "uuid":"..."
}

{
 "kind":"git_tree",
 "uuid":"zzzzz-s0uqq-xxxxxxxxxxxxxxx",
 "commit":"f315c59f90934cccae6381e72bba59d27ba42099"
}

{
 "kind":"tmp",
 "capacity":100000000000
}
{
 "kind":"tmp",
 "capacity":1000000000,
 "device_type":"ram"
}

{
 "kind":"keep"
}

{
 "kind":"file",
 "path":"/mounted_tmp/a.out"
}

{

 “kind”:“json”,

 “content”:{"foo":"bar"}

}

Pre-populate output using Mount points

When a container’s output_path is a tmp mount backed by local disk, this output directory can be pre-populated with content from existing collections. This content can be specified by mounting collections at mount points that are subdirectories of output_path. Certain restrictions apply:

1. Only mount points of kind collection are supported.

2. Mount points underneath output_path which have "writable":true are copied into output_path during container initialization and may be updated, renamed, or deleted by the running container. The original collection is not modified. On container completion, files remaining in the output are saved to the output collection. The mount at output_path must be big enough to accommodate copies of the inner writable mounts.

3. If any such mount points are configured as exclude_from_output":true, they will be excluded from the output.

If any process in the container tries to modify, remove, or rename these mount points or anything underneath them, the operation will fail and the container output and the underlying collections used to pre-populate are unaffected.

Example mount point configurations

All the below examples are based on this collection:

portable_data_hash cdfbe2e823222d26483d52e5089d553c+175

manifest_text: ./alice 03032680d3fa0561ef4f85071140861e+13+A04e9d06459cda00aa997565bd78001061cf5bffb@58ab593d 0:13:hello.txt\n./bob d820b9df970e1b498e7723c50b107e1b+11+A42d162a60210479d1cfaf9fbb98d494ac6322ae6@58ab593d 0:11:hello.txt\n./carol cf72b172ff969250ae14a893a6745440+13+A476a2fd39e14e9c03af3076bd17e3612c075ff66@58ab593d 0:13:hello.txt\n

"mounts": {
  "/tmp/foo": {
    "kind": "collection",
    "portable_data_hash": "cdfbe2...+175"
  },
},
"output_path": "/tmp"

"mounts": {
  "/tmp/foo/bar": {
    "kind": "collection",
    "portable_data_hash": "cdfbe2...+175"
    "path": "alice"
  },
},
"output_path": "/tmp"

"mounts": {
  "/tmp/foo/bar": {
    "kind": "collection",
    "portable_data_hash": "cdfbe2...+175"
    "path": "alice/hello.txt"
  },
},
"output_path": "/tmp"

Symlinks in output

When a container’s output_path is a tmp mount backed by local disk, this output directory can contain symlinks to other files in the output directory, or to collection mount points. If the symlink leads to a collection mount, efficiently copy the collection into the output collection. Symlinks leading to files or directories are expanded and created as regular files in the output collection. Further, whether symlinks are relative or absolute, every symlink target (even targets that are symlinks themselves) must point to a path in either the output directory or a collection mount.

Runtime constraints

Runtime constraints restrict the container’s access to compute resources and the outside world (in addition to its explicitly stated inputs and output).

Scheduling parameters

Parameters to be passed to the container scheduler (e.g., SLURM) when running a container.

Container reuse

When a container request is “Committed”, the system will try to find and reuse an existing Container with the same command, cwd, environment, output_path, container_image, mounts, secret_mounts, runtime_constraints, runtime_user_uuid, and runtime_auth_scopes being requested. (Hashes in the serialized fields environment, mounts and runtime_constraints use normalized key order.)

In order of preference, the system will use:

• The first matching container to have finished successfully (i.e., reached state “Complete” with an exit_code of 0) whose log and output collections are still available.
• The oldest matching “Running” container with the highest progress, i.e., the container that is most likely to finish first.
• The oldest matching “Locked” container with the highest priority, i.e., the container that is most likely to start first.
• The oldest matching “Queued” container with the highest priority, i.e,, the container that is most likely to start first.
• A new container.

Canceling a container request

A container request may be canceled by setting its priority to 0, using an update call.

When a container request is canceled, it will still reflect the state of the Container it is associated with via the container_uuid attribute. If that Container is being reused by any other container_requests that are still active, i.e., not yet canceled, that Container may continue to run or be scheduled to run by the system in future. However, if no other container_requests are using that Contianer, then the Container will get canceled as well.

Methods

See Common resource methods for more information about create, delete, get, list, and update.

Required arguments are displayed in green.

Supports federated create, delete, get, list, and update.

create

Create a new container request.

Arguments:

The request body must include the required attributes command, container_image, cwd, and output_path. It can also inlcude other attributes such as environment, mounts, and runtime_constraints.

delete

Delete an existing container request.

Arguments:

get

Get a container request’s metadata by UUID.

Arguments:

list

List container requests.

See common resource list method.

The filters argument can also filter on attributes of the container referenced by container_uuid. For example, [["container.state", "=", "Running"]] will match any container request whose container is running now.

update

Update attributes of an existing container request.

Arguments: