diff --git a/api/task_execution.openapi.yaml b/api/task_execution.openapi.yaml new file mode 100644 index 0000000..eeec731 --- /dev/null +++ b/api/task_execution.openapi.yaml @@ -0,0 +1,653 @@ +openapi: 3.0.0 +info: + title: Task Execution Service + version: "0.4.0-fds-patch" + contact: + name: Susheel Varma + email: susheel.varma@hdruk.ac.uk + license: + name: MIT + description: GA4GH Task Execution Service (with FDS extenstions) +tags: + - Task Service + - name: TaskService +paths: + /tasks: + get: + summary: List Tasks + operationId: ListTasks + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/tesListTasksResponse' + parameters: + - name: name_prefix + description: |- + OPTIONAL. Filter the list to include tasks where the name matches this prefix. + If unspecified, no task name filtering is done. + in: query + required: false + schema: + type: string + - name: page_size + description: |- + OPTIONAL. Number of tasks to return in one page. + Must be less than 2048. Defaults to 256. + in: query + required: false + schema: + type: integer + format: int64 + - name: page_token + description: |- + OPTIONAL. Page token is used to retrieve the next page of results. + If unspecified, returns the first page of results. + See ListTasksResponse.next_page_token + in: query + required: false + schema: + type: string + - name: view + description: |- + OPTIONAL. Affects the fields included in the returned Task messages. + See TaskView below. + + - MINIMAL: Task message will include ONLY the fields: + Task.Id + Task.State + - BASIC: Task message will include all fields EXCEPT: + Task.ExecutorLog.stdout + Task.ExecutorLog.stderr + Input.content + TaskLog.system_logs + - FULL: Task message includes all fields. + in: query + required: false + schema: + type: string + enum: + - MINIMAL + - BASIC + - FULL + default: MINIMAL + description: 'List tasks.TaskView is requested as such: "v1/tasks?view=BASIC"' + tags: + - TaskService + post: + summary: Create a new task. + operationId: CreateTask + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/tesCreateTaskResponse' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/tesTask' + required: true + tags: + - TaskService + description: Create a new task. + /tasks/service-info: + get: + summary: Service Info + operationId: GetServiceInfo + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/tesServiceInfo' + tags: + - TaskService + description: 'GetServiceInfo provides information about the service,such as storage details, resource availability, and other documentation.' + '/tasks/{id}': + get: + summary: Get a task. + operationId: GetTask + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/tesTask' + parameters: + - name: id + in: path + required: true + schema: + type: string + - name: view + description: |- + OPTIONAL. Affects the fields included in the returned Task messages. + See TaskView below. + + - MINIMAL: Task message will include ONLY the fields: + Task.Id + Task.State + - BASIC: Task message will include all fields EXCEPT: + Task.ExecutorLog.stdout + Task.ExecutorLog.stderr + Input.content + TaskLog.system_logs + - FULL: Task message includes all fields. + in: query + required: false + schema: + type: string + enum: + - MINIMAL + - BASIC + - FULL + default: MINIMAL + tags: + - TaskService + description: 'Get a task. TaskView is requested as such: "v1/tasks/{id}?view=FULL"' + '/tasks/{id}/cancel': + post: + summary: Cancel a task. + operationId: CancelTask + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/tesCancelTaskResponse' + tags: + - TaskService + description: Cancel a task. + parameters: + - schema: + type: string + name: id + in: path + required: true + description: Task ID + '/tasks/validate': + post: + summary: Validate a Task + tags: + - TaskService + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/tesValidateTaskResponse' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/tesCancelTaskResponse' + operationId: ValidateTask + requestBody: + content: + application/json: + schema: + type: object + properties: {} + application/xml: + schema: + $ref: '#/components/schemas/tesTask' + description: Validate a Task +servers: + - url: /ga4gh/tes/v1 +components: + schemas: + tesCancelTaskResponse: + type: object + description: CancelTaskResponse describes a response from the CancelTask endpoint. + readOnly: true + tesCreateTaskResponse: + type: object + properties: + id: + type: string + description: Task identifier assigned by the server. + description: CreateTaskResponse describes a response from the CreateTask endpoint. + readOnly: true + required: + - id + tesExecutor: + type: object + properties: + image: + type: string + description: |- + Name of the container image, for example: + ubuntu + quay.io/aptible/ubuntu + gcr.io/my-org/my-image + etc... + command: + type: array + items: + type: string + description: |- + A sequence of program arguments to execute, where the first argument + is the program to execute (i.e. argv). + workdir: + type: string + description: |- + The working directory that the command will be executed in. + Defaults to the directory set by the container image. + stdin: + type: string + description: |- + Path inside the container to a file which will be piped + to the executor's stdin. Must be an absolute path. + stdout: + type: string + description: |- + Path inside the container to a file where the executor's + stdout will be written to. Must be an absolute path. + stderr: + type: string + description: |- + Path inside the container to a file where the executor's + stderr will be written to. Must be an absolute path. + env: + type: object + additionalProperties: + type: string + description: Enviromental variables to set within the container. + description: 'Executor describes a command to be executed, and its environment.' + required: + - image + - command + tesExecutorLog: + type: object + properties: + start_time: + type: string + description: 'Time the executor started, in RFC 3339 format.' + end_time: + type: string + description: 'Time the executor ended, in RFC 3339 format.' + stdout: + type: string + description: |- + Stdout content. + + This is meant for convenience. No guarantees are made about the content. + Implementations may chose different approaches: only the head, only the tail, + a URL reference only, etc. + + In order to capture the full stdout users should set Executor.stdout + to a container file path, and use Task.outputs to upload that file + to permanent storage. + stderr: + type: string + description: |- + Stderr content. + + This is meant for convenience. No guarantees are made about the content. + Implementations may chose different approaches: only the head, only the tail, + a URL reference only, etc. + + In order to capture the full stderr users should set Executor.stderr + to a container file path, and use Task.outputs to upload that file + to permanent storage. + exit_code: + type: integer + format: int32 + description: Exit code. + description: ExecutorLog describes logging information related to an Executor. + required: + - exit_code + readOnly: true + tesFileType: + type: string + enum: + - FILE + - DIRECTORY + default: FILE + tesInput: + type: object + properties: + name: + type: string + description: + type: string + url: + type: string + description: |- + REQUIRED, unless "content" is set. + + URL in long term storage, for example: + s3://my-object-store/file1 + gs://my-bucket/file2 + file:///path/to/my/file + /path/to/my/file + etc... + path: + type: string + description: |- + Path of the file inside the container. + Must be an absolute path. + type: + $ref: '#/components/schemas/tesFileType' + content: + type: string + description: |- + File content literal. + Implementations should support a minimum of 128 KiB in this field and may define its own maximum. + UTF-8 encoded + + If content is not empty, "url" must be ignored. + description: Input describes Task input files. + required: + - type + - path + tesListTasksResponse: + type: object + properties: + tasks: + type: array + items: + $ref: '#/components/schemas/tesTask' + description: List of tasks. + next_page_token: + type: string + description: |- + Token used to return the next page of results. + See TaskListRequest.next_page_token + description: ListTasksResponse describes a response from the ListTasks endpoint. + required: + - tasks + readOnly: true + tesOutput: + type: object + properties: + name: + type: string + description: + type: string + url: + type: string + description: |- + URL in long term storage, for example: + s3://my-object-store/file1 + gs://my-bucket/file2 + file:///path/to/my/file + /path/to/my/file + etc... + path: + type: string + description: |- + Path of the file inside the container. + Must be an absolute path. + type: + $ref: '#/components/schemas/tesFileType' + description: Output describes Task output files. + required: + - url + - path + - type + tesOutputFileLog: + type: object + properties: + url: + type: string + description: 'URL of the file in storage, e.g. s3://bucket/file.txt' + path: + type: string + description: Path of the file inside the container. Must be an absolute path. + size_bytes: + type: string + format: int64 + description: Size of the file in bytes. + description: |- + OutputFileLog describes a single output file. This describes + file details after the task has completed successfully, + for logging purposes. + readOnly: true + required: + - url + - path + - size_bytes + tesResources: + type: object + properties: + cpu_cores: + type: integer + format: int64 + description: Requested number of CPUs + preemptible: + type: boolean + format: boolean + description: Is the task allowed to run on preemptible compute instances (e.g. AWS Spot)? + ram_gb: + type: number + format: double + description: Requested RAM required in gigabytes (GB) + disk_gb: + type: number + format: double + description: Requested disk size in gigabytes (GB) + zones: + type: array + items: + type: string + description: Request that the task be run in these compute zones. + description: Resources describes the resources requested by a task. + tesServiceInfo: + type: object + description: |- + ServiceInfo describes information about the service, + such as storage details, resource availability, + and other documentation. + readOnly: true + properties: + name: + type: string + description: 'Returns the name of the service, e.g. "ohsu-compbio-funnel".' + doc: + type: string + description: 'Returns a documentation string, e.g. "Hey, we''re OHSU Comp. Bio!".' + storage: + type: array + description: |- + Lists some, but not necessarily all, storage locations supported by the service. + + Must be in a valid URL format. + e.g. + file:///path/to/local/funnel-storage + s3://ohsu-compbio-funnel/storage + etc. + items: + type: string + registries: + type: array + items: + type: object + properties: + registry_id: + type: string + registry_name: + type: string + registry_host: + type: string + registry_url: + type: string + tesState: + type: string + enum: + - UNKNOWN + - QUEUED + - INITIALIZING + - RUNNING + - PAUSED + - COMPLETE + - EXECUTOR_ERROR + - SYSTEM_ERROR + - CANCELED + default: UNKNOWN + description: |- + Task states. + + - UNKNOWN: The state of the task is unknown. + + This provides a safe default for messages where this field is missing, + for example, so that a missing field does not accidentally imply that + the state is QUEUED. + - QUEUED: The task is queued. + - INITIALIZING: The task has been assigned to a worker and is currently preparing to run. + For example, the worker may be turning on, downloading input files, etc. + - RUNNING: The task is running. Input files are downloaded and the first Executor + has been started. + - PAUSED: The task is paused. + + An implementation may have the ability to pause a task, but this is not required. + - COMPLETE: The task has completed running. Executors have exited without error + and output files have been successfully uploaded. + - EXECUTOR_ERROR: The task encountered an error in one of the Executor processes. Generally, + this means that an Executor exited with a non-zero exit code. + - SYSTEM_ERROR: The task was stopped due to a system error, but not from an Executor, + for example an upload failed due to network issues, the worker's ran out + of disk space, etc. + - CANCELED: The task was canceled by the user. + readOnly: true + tesTask: + type: object + properties: + id: + type: string + description: Task identifier assigned by the server. + readOnly: true + state: + $ref: '#/components/schemas/tesState' + name: + type: string + description: + type: string + inputs: + type: array + items: + $ref: '#/components/schemas/tesInput' + description: |- + Input files. + Inputs will be downloaded and mounted into the executor container. + outputs: + type: array + items: + $ref: '#/components/schemas/tesOutput' + description: |- + Output files. + Outputs will be uploaded from the executor container to long-term storage. + resources: + $ref: '#/components/schemas/tesResources' + executors: + type: array + items: + $ref: '#/components/schemas/tesExecutor' + description: |- + A list of executors to be run, sequentially. Execution stops + on the first error. + volumes: + type: array + items: + type: string + description: |- + Volumes are directories which may be used to share data between + Executors. Volumes are initialized as empty directories by the + system when the task starts and are mounted at the same path + in each Executor. + + For example, given a volume defined at "/vol/A", + executor 1 may write a file to "/vol/A/exec1.out.txt", then + executor 2 may read from that file. + + (Essentially, this translates to a `docker run -v` flag where + the container path is the same for each executor). + tags: + type: object + additionalProperties: + type: string + description: A key-value map of arbitrary tags. + logs: + type: array + items: + $ref: '#/components/schemas/tesTaskLog' + description: |- + Task logging information. + Normally, this will contain only one entry, but in the case where + a task fails and is retried, an entry will be appended to this list. + readOnly: true + creation_time: + type: string + description: |- + Date + time the task was created, in RFC 3339 format. + This is set by the system, not the client. + readOnly: true + description: Task describes an instance of a task. + required: + - executors + tesTaskLog: + type: object + properties: + logs: + type: array + items: + $ref: '#/components/schemas/tesExecutorLog' + description: Logs for each executor + metadata: + type: object + additionalProperties: + type: string + description: Arbitrary logging metadata included by the implementation. + start_time: + type: string + description: 'When the task started, in RFC 3339 format.' + end_time: + type: string + description: 'When the task ended, in RFC 3339 format.' + outputs: + type: array + items: + $ref: '#/components/schemas/tesOutputFileLog' + description: |- + Information about all output files. Directory outputs are + flattened into separate items. + system_logs: + type: array + items: + type: string + description: |- + System logs are any logs the system decides are relevant, + which are not tied directly to an Executor process. + Content is implementation specific: format, size, etc. + + System logs may be collected here to provide convenient access. + + For example, the system may include the name of the host + where the task is executing, an error message that caused + a SYSTEM_ERROR state (e.g. disk is full), etc. + + System logs are only included in the FULL task view. + description: TaskLog describes logging information related to a Task. + required: + - logs + - outputs + readOnly: true + tesValidateTaskResponse: + title: tesValidateTaskResponse + type: object + properties: + success: + type: string + enum: + - 'true' + - 'false'