Authors:

Feature pages are design documents that developers have created while collaborating on oVirt.

Most of them are outdated, but provide historical design context.

They are not user documentation and should not be treated as such.

Documentation is available here.

Detailed External Tasks

Adding External Jobs/Steps Support

Summary

Enable plug-in to inject tasks (Jobs) to the engine application using the REST API, change their statuses and track them from the UI. A task (Job) may have other nesting sub-tasks (Steps) under it.

Owner

  • Feature owner: Eli Mesika (emesika)

    • GUI Component owner: Eli Mesika (emesika)

    • REST Component owner: Eli Mesika (emesika)

    • Engine Component owner: Eli Mesika (emesika)

    • QA Owner: Yaniv Kaul (ykaul)

  • Email: emesika@redhat.com

Current status

  • Target Release: 3.3
  • Status: Design
  • Last updated date: APR 15 2013

Detailed Description

Enable plug-in to inject tasks (Jobs) to the engine application using the REST API, change their statuses and track them from the UI. A task (Job) may have other nesting sub-tasks (Steps) under it. A Job is actually a container of nexted steps. Each Step may have sub-steps under it. A steps represents one of the following:

  • An external command that is invoked and monitored by the plug-in
  • A supported internal command that is invoked by the plug-in and monitored internally by the oVirt engine.

Each Job may have unlimited list of external/internal steps.

The following should be supported:

  • Adding a job
  • Adding a step to a job or to a step (as sub-step)
  • Ending a step
  • Eding a job
  • Displaying all Jobs
  • Displaying a specific Job
  • Displaying all Steps under a specific Job
  • Dislaying a specific Step under a Job

Job can be in one of the following statuses:

  • STARTED - Job was started
  • FINISHED - Job has been finished successfully
  • FAILED - Job had failed
  • ABORTED - Job was aborted
  • UNKNOWN - Job is in unnknown state

Step can be in one of theabove statuses as in Job. In addition Step supports the following Step Types :

  • VALIDATING - Step is validating the requested operation
  • EXECUTING - Step is executing the requested operation
  • FINALIZING - Steps is finalysing the requested operation

CRUD

Adding a flag named is_external to both Job and Step tables This flag indicates that the Job/Step was invoked as part of a plug-in operation and may be used in future to filter such jobs/steps

DAO

Adding isExternal flag to both JobDAODBFacadeImpl and StepDAODBFacadeImpl and wrap it with getter/setter

Metadata

Adding is_external to Job and Step metadata in fixtures.xml

Business Logic

Adding the following to VdcActionParametersBase

  • jobId - The Job UUID
  • stepId - The parent step UUID

This will be used by plug-ins in order to invoke internal oVirt commands and still let them appaer under the given Job/Step in the task Monitor In case that such a command is invoked not in the context of an external Job, its jobId and stepId will be null The ExecutionHandler::getJob is modified to test if the jobId and stepId are null and according to the result generate a new job or use the given one.

New Supported Commands

  • AddExternalJob - Adds an external Job and returns its UUID
  • EndExternalJob - Ends the given Job
  • AddExternalStep - Adds an external step to a Job directly or under an existing Step. If command is an oVirt internal command, it cpould be added only if it is flagged as Monitored
  • EndExternalStep - Ends the given Step (For steps that represents plug-in operations only)

Flow

  • Add Job/Step Flow: use api/jobs to add a new job using POST and giving a job description as a parameter

    use api/jobs/<jobId>/steps to add a new step using POST and giving a step parentId , parentType, description and status as parameters (The parentId is the UUID of the parent of the new created step, the parentType may be Job or Step)

  • List Job(s)/Step(s):
    • use api/jobs to list all jobs
    • use api/jobs/<jobId> to list the job identified by <jobId>
    • use api/jobs/<jobId>/steps to list all steps of the job identified by <jobId>
    • use api/jobs/<jobId>/steps/<stepId> to list a specific step identified by <stepId> under the job identified by <jobId>
  • End Job/Step Flow:
    • use api/jobs/<jobId>/end to end a job using POST and giving a jobId status and an optional force flag
    • use api/jobs/<jobId>/steps/<stepId>/end to end a step using POST and giving a stepId stepType status and an optional force flag

Permissions

Command Permissions

A new permission to access those commands will be added by default only to superuser role. A new role that can inject External Tasks will be added and may be attached/added to any user in the system

Permissions on Entity Instances

Since each Job may have steps that invoke internal oVirt command or external plug-in comamnds, on internal oVirt command we have already permissions on entities and on external commands it is in teh plug-in scope. So, nothing have to be specifically written in oVirt to support that.

API

  • Add the list of monitored commands to api/capabilities
  • Add support for job_id and step_id parameters in QueryHelper such that commands can pass job_id and step_id in the URI
  • Add Job business entity
  • Add Step business entity
  • Adding JobMapper to map backend to REST entities and vice versa
  • Adding StepMapper to map backend to REST entities and vice versa
  • Add JobsResource/BackendJobsResource implementation to handle add() & get operations
  • Add StepsResource/BackendStepsResource implementation to handle add() & get operations
  • Add JobResource/BackendJobResource implementation to handle actions on a specific resource
  • Add StepResource/BackendStepResource implementation to handle actions on a specific resource
  • Add signatures to meta-data file (rsdl_metadata_v-3.1.yaml)
  • Add tests

Note that no update is required.

Get

Add support for the following:

  • /api/jobs
  • /api/jobs/<job_id>
  • /api/jobs/<job_id>/steps
  • /api/jobs/<job_id>/steps/<step_id>
<jobs>
   <job id = "xxx" href="api/jobs/xxx">
      <description>a description</description>
      <action_type> the action type</action_type>
      <status>[STARTED|FINISHED|FAILED|ABORTED|UNKNOWN]</status>
      <owner>the owner</owner>
             <start_time>...</start_time>
      <end_time>...</end_time>
      <last_updated>...</last_updated>
      <external>[true|false]</external>
      <auto_cleared>[true|false]</auto_cleared>
   <job>
   ...
</jobs>

<steps>
    <step id="yyy" href="api/jobs/xxx/steps/yyy">
              [<parent_job id="xxx" href="api/jobs/xxx"/> | <parent_step id="yyy" href="api/jobs/xxx/steps/yyy"/>]
        <description>a description</description>
        <type>[VALIDATING|EXECUTING|FINALIZING]</type>
        <number>...</number>
        <status>[STARTED|FINISHED|FAILED|ABORTED|UNKNOWN]</status>
              <start_time>...</start_time>
        <end_time>...</end_time>
        <external>[true|false]</external>
   </step>
         ....
</steps>

Post

Adding a new Job/Step will be implemented by the POST operation

Job:

<job>
    <description></description>
    <auto_cleared>[true|false]</auto_cleared>
</job>

Step:

<step>
    <description></description>
    <type></type>
    <status>
         <state></state>
    </status>
</step>

Sub-step:

<step>
    <parent_step  id="yyy" />
    <description></description>
    <type></type>
    <status>
         <state></state>
    </status>
</step>

Ending an existing Job/Step will be done via a supported action on the Job/Step business entity

  • /api/Jobs/<job_id>/end - will end the given job
  • /api/Jobs/<job_id>/steps/<step_id>/end - will end the given step

End a job

<action>
  <status>
     <state>FAILED</state>
        </status>>
  <force>false</force>
</action>

End a Step

<action>
  <succeeded>true</succeeded>
</action>

User Experience

External Jobs and their Steps will be displayen in the oVirt Task Monitor

Installation/Upgrade

Add additional fields to job and step tables upon upgrade Add the permission(ActionGroup) to manipulate External tasks to other admin roles already defined upon upgrade.

User work-flows

Enforcement

Affected oVirt projects

Documentation / External references

RFE

Features/ExternalTasks

Future directions