[ARVADOS] created: 769189c406bb42761f4d7bfe35fd2cc36edcef00

Git user git at public.curoverse.com
Wed Sep 7 19:18:58 EDT 2016


        at  769189c406bb42761f4d7bfe35fd2cc36edcef00 (commit)


commit 769189c406bb42761f4d7bfe35fd2cc36edcef00
Author: radhika <radhika at curoverse.com>
Date:   Wed Sep 7 19:18:40 2016 -0400

    9835: Container and ContainerRequest documentation.

diff --git a/doc/_config.yml b/doc/_config.yml
index 96b8a52..266a488 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -107,6 +107,8 @@ navbar:
       - api/methods/api_clients.html.textile.liquid
       - api/methods/authorized_keys.html.textile.liquid
       - api/methods/collections.html.textile.liquid
+      - api/methods/container_requests.html.textile.liquid
+      - api/methods/containers.html.textile.liquid
       - api/methods/groups.html.textile.liquid
       - api/methods/humans.html.textile.liquid
       - api/methods/jobs.html.textile.liquid
@@ -128,6 +130,8 @@ navbar:
       - api/schema/ApiClient.html.textile.liquid
       - api/schema/AuthorizedKey.html.textile.liquid
       - api/schema/Collection.html.textile.liquid
+      - api/schema/Container.html.textile.liquid
+      - api/schema/ContainerRequest.html.textile.liquid
       - api/schema/Group.html.textile.liquid
       - api/schema/Human.html.textile.liquid
       - api/schema/Job.html.textile.liquid
diff --git a/doc/api/methods/container_requests.html.textile.liquid b/doc/api/methods/container_requests.html.textile.liquid
new file mode 100644
index 0000000..491698e
--- /dev/null
+++ b/doc/api/methods/container_requests.html.textile.liquid
@@ -0,0 +1,72 @@
+---
+layout: default
+navsection: api
+navmenu: API Methods
+title: "container_requests"
+
+...
+
+See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
+
+API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/container_requests@
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
+h2(#create). create
+
+Create a new ContainerRequest.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|container_request|object|See "ContainerRequest resource":{{site.baseurl}}/api/schema/ContainerRequest.html|request body||
+
+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.
+
+h2. delete
+
+Delete an existing ContainerRequest.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
+
+h2. get
+
+Get a ContainerRequest's metadata by UUID.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
+
+h2. list
+
+List container_requests.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+|limit|integer (default 100)|Maximum number of container_requests to return.|query||
+|order|string|Order in which to return matching container_requests.|query||
+|filters|array|Conditions for filtering container_requests.|query||
+
+See the create method documentation for more information about ContainerRequest-specific filters.
+
+h2. update
+
+Update attributes of an existing ContainerRequest.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
+|container_request|object||query||
+
+Note: To cancel a ContainerRequest, set it's priority to zero.
diff --git a/doc/api/methods/containers.html.textile.liquid b/doc/api/methods/containers.html.textile.liquid
new file mode 100644
index 0000000..c39b092
--- /dev/null
+++ b/doc/api/methods/containers.html.textile.liquid
@@ -0,0 +1,76 @@
+---
+layout: default
+navsection: api
+navmenu: API Methods
+title: "containers"
+
+...
+
+See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
+
+API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/containers@
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
+h2(#create). create
+
+Create a new Container.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|container|object|See "Container resource":{{site.baseurl}}/api/schema/Container.html|request body||
+
+h2. delete
+
+Delete an existing Container.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
+
+h2. get
+
+Get a Container's metadata by UUID.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
+
+h2. list
+
+List containers.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+|limit|integer (default 100)|Maximum number of containers to return.|query||
+|order|string|Order in which to return matching containers.|query||
+|filters|array|Conditions for filtering containers.|query||
+
+See the create method documentation for more information about Container-specific filters.
+
+h2. update
+
+Update attributes of an existing Container.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the Container in question.|path||
+|container|object||query||
+
+h2. auth
+
+Get the api_client_authorization record indicated by this container's auth_uuid, which belongs to the container's locked_by_uuid.
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string||path||
diff --git a/doc/api/schema/Container.html.textile.liquid b/doc/api/schema/Container.html.textile.liquid
new file mode 100644
index 0000000..e690b82
--- /dev/null
+++ b/doc/api/schema/Container.html.textile.liquid
@@ -0,0 +1,45 @@
+---
+layout: default
+navsection: api
+navmenu: Schema
+title: Container
+
+...
+
+A Container:
+* Captures information about the environment in which a Crunch2 process was run. For example, git trees, data collections, and docker images are stored as content addresses. This makes it possible to reason about the difference between two processes, and to replay a process at a different time and place.
+* Clients can read Container records, but only the system can create or modify them.
+
+h2. Methods
+
+See "containers":{{site.baseurl}}/api/methods/containers.html
+
+h2. Resource
+
+Each Container offers the following attributes, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+
+table(table table-bordered table-condensed).
+|_. Attribute|_. Type|_. Description|_. Notes|
+|state|string|The allowed states are "Queued", "Locked", "Running", "Cancelled" and "Complete".|See <A href="https://dev.arvados.org/projects/arvados/wiki/Containers_API#Container-states">Container states</A> for additional details.|
+|started_at|datetime|When this container started running.|Null if container has not yet started.|
+|finished_at|datetime|When this container finished.|Null if container has not yet finished.|
+|log|string|Portable data hash of the log collection.|Null if the container is not yet finished.|
+|environment|hash|Environment variables and values that should be set in the container environment (@docker run --env@). This augments and (when conflicts exist) overrides environment variables given in the image's Dockerfile.|Must be equal to a ContainerRequest's environment in order to satisfy the ContainerRequest.|
+|cwd|string|Initial working directory.|Must be equal to a ContainerRequest's cwd in order to satisfy the ContainerRequest|
+|command|array of strings|Command to execute.| Must be equal to a ContainerRequest's command in order to satisfy the ContainerRequest.|
+|output_path|string|Path to a directory or file inside the container that should be preserved as this container's output when it finishes.|Must be equal to a ContainerRequest's output_path in order to satisfy the ContainerRequest.|
+|mounts|hash|Must contain the same keys as the ContainerRequest being satisfied. Each value must be within the range of values described in the ContainerRequest at the time the Container is assigned to the ContainerRequest.|See <A href="https://dev.arvados.org/projects/arvados/wiki/Containers_API#Mount-types">Mount types</A> for additional details.|
+|runtime_constraints|hash|Compute resources, and access to the outside world, that are / were available to the container.
+Generally this will contain additional keys that are not present in any corresponding ContainerRequests: for example, even if no ContainerRequests specified constraints on the number of CPU cores, the number of cores actually used will be recorded here.|e.g.,
+<pre><code>{
+  "ram":12000000000,
+  "vcpus":2,
+  "API":true
+}</code></pre>|
+|output|string|Portable data hash of the output collection.|Null if the container is not yet finished.|
+|container_image|string|Portable data hash of a collection containing the docker image used to run the container.||
+|progress|number|A number between 0.0 and 1.0 describing the fraction of work done.||
+|priority|integer|Priority assigned by the system, taking into account the priorities of all associated ContainerRequests.||
+|exit_code|integer|Process exit code.|Null if state!="Complete"|
+|auth_uuid|string|UUID of a token to be passed into the container itself, used to access Keep-backed mounts, etc.|Null if state∉{"Locked","Running"}|
+|locked_by_uuid|string|UUID of a token, indicating which dispatch process changed state to Locked. If null, any token can be used to lock. If not null, only the indicated token can modify this container.|Null if state∉{"Locked","Running"}|
diff --git a/doc/api/schema/ContainerRequest.html.textile.liquid b/doc/api/schema/ContainerRequest.html.textile.liquid
new file mode 100644
index 0000000..15a0c1d
--- /dev/null
+++ b/doc/api/schema/ContainerRequest.html.textile.liquid
@@ -0,0 +1,46 @@
+---
+layout: default
+navsection: api
+navmenu: Schema
+title: ContainerRequest
+
+...
+
+A ContainerRequest:
+* Is a client's expression of interest in knowing the outcome of a computational process.
+* The system is responsible for finding suitable containers and assigning them to container_requests.
+* The client's description of the ContainerRequest is less precise than of a Container: a ContainerRequest describes container constraints which can have different interpretations over time. For example, a ContainerRequest with a {"kind":"git_tree","commit_range":"abc123..master",...} mount might be satisfiable by any of several different source trees, and this set of satisfying source trees can change when the repository's "master" branch is updated.
+
+h2. Methods
+
+See "container_requests":{{site.baseurl}}/api/methods/container_requests.html
+
+h2. Resource
+
+Each ContainerRequest offers the following attributes, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+
+table(table table-bordered table-condensed).
+|_. Attribute|_. Type|_. Description|_. Notes|
+|name|string|The name of the container_request.||
+|description|string|The description of the container_request.||
+|properties|hash|Client-defined structured data that does not affect how the container is run.||
+|state|string|The allowed states are "Uncommitted", "Committed", and "Final".|Once a request is Committed, the only attributes that can be modified are priority, container_uuid, and container_count_max. A request in the "Final" state cannot have any of its functional parts modified (i.e., only name, description, and properties fields can be modified).|
+|requesting_container_uuid|string|Set by the system to the uuid of a container corresponding to the user's token, if one exists.|When the referenced container ends, the container request is automatically completed.|
+|container_uuid|string|The container that satisfies this container_request.||
+|container_count_max|integer|Maximum number of containers to start, i.e., the maximum number of "attempts" to be made.||
+|mounts|hash|Objects to attach to the container's filesystem and stdin/stdout.|See <A href="https://dev.arvados.org/projects/arvados/wiki/Containers_API#Mount-types">Mount types</A> for additional details.|
+|runtime_constraints|hash|Restrict the container's access to compute resources and the outside world. Required and must specify ram and vcpus when the container_request is in Committed state.|e.g.,
+<pre><code>{
+  "ram":12000000000,
+  "vcpus":2,
+  "API":true
+}</code></pre>|
+|container_image|string|Portable data hash of a collection containing the docker image to run the container.|Required.|
+|environment|hash|Environment variables and values that should be set in the container environment (@docker run --env@). This augments and (when conflicts exist) overrides environment variables given in the image's Dockerfile.||
+|cwd|string|Initial working directory, given as an absolute path (in the container) or a path relative to the WORKDIR given in the image's Dockerfile.|Required.|
+|command|array of strings|Command to execute in the container.|Required.
+e.g., @["echo","hello"]@|
+|output_path|string|Path to a directory or file inside the container that should be preserved as container's output when it finishes. This path must be, or be inside, one of the mount targets. For best performance, point output_path to a writable collection mount.|Required.|
+|priority|integer|Higher value means spend more resources on this container_request, i.e., go ahead of other queued containers, bring up more nodes etc.|Priority 0 means a container should not be run on behalf of this request. Clients are expected to submit ContainerRequests with zero priority in order to prevew the container that will be used to satisfy it. Priority can be null if and only if state!="Committed".|
+|expires_at|datetime|After this time, priority is considered to be zero.|Not yet implemented.|
+|filters|string|Additional constraints for satisfying the container_request, given in the same form as the filters parameter accepted by the container_requests.list API.||

-----------------------------------------------------------------------


hooks/post-receive
-- 




More information about the arvados-commits mailing list