Jobs¶
Jobs are used to track progress of long running tasks. A good example for a long running task is cloning of drives and servers. Depending on the current cloud resource usage and the users preferences ( Creating Drives in a Different Availability Group (Create/Clone Avoid) ), a drive clone operation can take a while.
- Currently, the operations that create a job for tracking are:
- Drive cloning
- Server cloning
How it works¶
Drive cloning¶
After successfully starting a cloning operation via the API, you will receive the definition of the newly created drive. All drives have a jobs field, containing references to the all the long running tasks executed on them. The destination, since it is a newly created drive, references only 1 job - the currently running one. The source might contain more jobs, depending on how many times it was cloned. History of completed jobs is kept for 3 days. Older jobs are discarded.
Example clone request:
POST /api/2.0/drives/db7a095c-622d-4b98-88fd-25a7e34d402e/action/?do=clone HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop { "affinities": [], "media": "cdrom", "name": "test_drive_y" }Example clone response:
HTTP/1.1 202 ACCEPTED Content-Type: application/json; charset=utf-8 { "objects": [ { "affinities": [], "allow_multimount": false, "jobs": [ { "resource_uri": "/api/2.0/jobs/305867d6-5652-41d2-be5c-bbae1eed5676/", "uuid": "305867d6-5652-41d2-be5c-bbae1eed5676" } ], "licenses": [], "media": "cdrom", "meta": {}, "mounted_on": [], "name": "test_drive_y", "owner": { "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/", "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf" }, "resource_uri": "/api/2.0/drives/df05497c-1504-4fea-af24-2825fc5133cf/", "runtime": { "is_snapshotable": null, "snapshots_allocated_size": 0, "storage_type": "dssd" }, "size": 1073741824, "snapshots": [], "status": "cloning_dst", "storage_type": "dssd", "tags": [], "uuid": "df05497c-1504-4fea-af24-2825fc5133cf" } ] }
Using the the jobs field we could examine how is our cloning operation doing:
Example request:
GET /api/2.0/jobs/305867d6-5652-41d2-be5c-bbae1eed5676/ HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDopExample response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "children": [], "created": "2014-01-30T15:24:42.205092+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T15:24:42.937432+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/305867d6-5652-41d2-be5c-bbae1eed5676/", "resources": [ "/api/2.0/drives/df05497c-1504-4fea-af24-2825fc5133cf/", "/api/2.0/drives/db7a095c-622d-4b98-88fd-25a7e34d402e/" ], "state": "success", "uuid": "305867d6-5652-41d2-be5c-bbae1eed5676" }
The interesting field here is data.progress. 100 means the job has finished.
Server cloning¶
Cloning a server is a bit more complex. Since servers generally contain drives, drives must also be cloned. That is why jobs support sub-jobs. When you send a clone server request, you receive the definition of the newly created server. It also has a jobs field containing the definitions of jobs and sub-jobs.
Example clone request:
POST /api/2.0/servers/a0b4db4f-d09b-4eda-8b67-29b090b17b9c/action/?do=clone HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop { "name": "test_cloned_server_name", "random_vnc_password": true }Example clone response:
HTTP/1.1 202 ACCEPTED Content-Type: application/json; charset=utf-8 { "context": true, "cpu": 1000, "cpu_model": null, "cpus_instead_of_cores": false, "drives": [], "enable_numa": false, "hv_relaxed": false, "hv_tsc": false, "jobs": [ { "resource_uri": "/api/2.0/jobs/f1a4fb2f-8825-43b7-9fdf-39d228fce4db/", "uuid": "f1a4fb2f-8825-43b7-9fdf-39d228fce4db" } ], "mem": 536870912, "meta": {}, "name": "test_cloned_server_name", "nics": [], "owner": { "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/", "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf" }, "requirements": [], "resource_uri": "/api/2.0/servers/65127d1a-4766-4677-90da-418246cedc6f/", "runtime": null, "smp": 1, "status": "stopped", "tags": [], "uuid": "65127d1a-4766-4677-90da-418246cedc6f", "vnc_password": "GjZ7bn2S" }
Each job has children field with containing its sub-jobs. Note that each sub-job contains a children field, too. Meaning that a sub-job could have a sub-jobs, too.
Example request:
Example response:
List all jobs¶
All jobs can be listed and examined quite easily.
Example request:
GET /api/2.0/jobs/ HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDopExample response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "meta": { "limit": 20, "offset": 0, "total_count": 665 }, "objects": [ { "children": [], "created": "2014-01-30T11:26:56.105319+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T11:26:57.065820+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/ec01d3bc-1ec0-440d-a1c3-0a6421d0d511/", "resources": [], "state": "success", "uuid": "ec01d3bc-1ec0-440d-a1c3-0a6421d0d511" }, { "children": [], "created": "2014-01-30T10:58:01.274906+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T10:58:01.306311+00:00", "operation": "server_clone", "resource_uri": "/api/2.0/jobs/98c4a0ad-e9e0-4864-9b15-dbfd75450555/", "resources": [], "state": "success", "uuid": "98c4a0ad-e9e0-4864-9b15-dbfd75450555" }, { "children": [], "created": "2014-01-30T14:14:50.622515+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T14:15:06.033297+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/094b0318-13f9-4556-b927-f9be130d3407/", "resources": [], "state": "success", "uuid": "094b0318-13f9-4556-b927-f9be130d3407" }, { "children": [], "created": "2014-01-30T00:11:00.792036+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T00:11:01.602770+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/a9435fe2-2404-4c8f-890f-8a4775ca7c10/", "resources": [], "state": "success", "uuid": "a9435fe2-2404-4c8f-890f-8a4775ca7c10" }, { "children": [], "created": "2014-01-29T11:28:18.475138+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-29T11:28:22.706801+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/086a0b34-6c9e-439e-89df-e99eec2fb2dd/", "resources": [], "state": "success", "uuid": "086a0b34-6c9e-439e-89df-e99eec2fb2dd" }, { "children": [], "created": "2014-01-30T10:24:11.208241+00:00", "data": { "progress": 0 }, "last_modified": "2014-01-30T10:29:14.246692+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/0092ed11-1a8d-4077-814c-2b49d32f3d7c/", "resources": [], "state": "failed", "uuid": "0092ed11-1a8d-4077-814c-2b49d32f3d7c" }, { "children": [], "created": "2014-01-30T07:23:54.476364+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T07:23:55.508287+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/9f99ad90-17a6-406c-9756-be036e823be6/", "resources": [], "state": "success", "uuid": "9f99ad90-17a6-406c-9756-be036e823be6" }, { "children": [], "created": "2014-01-29T10:11:26.564677+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-29T10:11:27.339788+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/953140bd-6955-4836-a096-775714ddadd1/", "resources": [], "state": "success", "uuid": "953140bd-6955-4836-a096-775714ddadd1" }, { "children": [], "created": "2014-01-30T06:11:31.423674+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T06:11:32.242493+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/faca1dea-2567-48fe-9052-e7a1ee81ec73/", "resources": [], "state": "success", "uuid": "faca1dea-2567-48fe-9052-e7a1ee81ec73" }, { "children": [ { "children": [], "created": "2014-01-30T07:23:54.476364+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T07:23:55.508287+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/9f99ad90-17a6-406c-9756-be036e823be6/", "resources": [], "state": "success", "uuid": "9f99ad90-17a6-406c-9756-be036e823be6" } ], "created": "2014-01-30T07:23:54.247819+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T07:23:55.486757+00:00", "operation": "server_clone", "resource_uri": "/api/2.0/jobs/95625523-3b19-4ec2-8c32-91ea4070e79b/", "resources": [], "state": "success", "uuid": "95625523-3b19-4ec2-8c32-91ea4070e79b" }, { "children": [], "created": "2014-01-29T14:21:43.834219+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-29T14:21:44.602062+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/eec067c9-3546-486b-bad5-d6374096e6ca/", "resources": [], "state": "success", "uuid": "eec067c9-3546-486b-bad5-d6374096e6ca" }, { "children": [], "created": "2014-01-30T09:09:17.821269+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T09:09:18.782439+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/40522101-5a11-4abb-b928-36d5a91cba69/", "resources": [], "state": "success", "uuid": "40522101-5a11-4abb-b928-36d5a91cba69" }, { "children": [], "created": "2014-01-30T13:24:01.529922+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T13:24:01.560640+00:00", "operation": "server_clone", "resource_uri": "/api/2.0/jobs/2427de0f-35f1-42c2-baec-33f9e24e51bb/", "resources": [], "state": "success", "uuid": "2427de0f-35f1-42c2-baec-33f9e24e51bb" }, { "children": [], "created": "2014-01-29T10:46:12.801333+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-29T10:46:13.597175+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/622a8a80-86e9-4391-9a32-68b5ccefa0a1/", "resources": [], "state": "success", "uuid": "622a8a80-86e9-4391-9a32-68b5ccefa0a1" }, { "children": [], "created": "2014-01-29T09:41:55.913186+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-29T09:41:57.039622+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/f4f5afea-7073-4084-a250-3cfd20112147/", "resources": [], "state": "success", "uuid": "f4f5afea-7073-4084-a250-3cfd20112147" }, { "children": [], "created": "2014-01-30T09:11:25.617527+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T09:11:26.401838+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/6d33e559-a9d2-45a9-a491-5b92feab7d6e/", "resources": [], "state": "success", "uuid": "6d33e559-a9d2-45a9-a491-5b92feab7d6e" }, { "children": [], "created": "2014-01-29T22:25:29.974650+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-29T22:25:30.995240+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/5fdce9da-801e-4e64-b8ee-3e8632c3adea/", "resources": [], "state": "success", "uuid": "5fdce9da-801e-4e64-b8ee-3e8632c3adea" }, { "children": [], "created": "2014-01-30T12:24:17.199731+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-30T12:24:31.632651+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/8492cd9c-8660-4a1f-9395-f331b33fa08b/", "resources": [], "state": "success", "uuid": "8492cd9c-8660-4a1f-9395-f331b33fa08b" }, { "children": [], "created": "2014-01-29T14:03:51.215749+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-29T14:03:51.939867+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/18e73d11-a677-4aa6-b5e4-cd0f2b8b4b10/", "resources": [], "state": "success", "uuid": "18e73d11-a677-4aa6-b5e4-cd0f2b8b4b10" }, { "children": [], "created": "2014-01-29T10:23:38.612503+00:00", "data": { "progress": 100 }, "last_modified": "2014-01-29T10:24:02.363589+00:00", "operation": "drive_clone", "resource_uri": "/api/2.0/jobs/8bacb5b3-6392-4f74-8094-ba3376a3f5f7/", "resources": [], "state": "success", "uuid": "8bacb5b3-6392-4f74-8094-ba3376a3f5f7" } ] }
Schema¶
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "allowed_detail_http_methods": [ "get" ], "allowed_list_http_methods": [ "get" ], "default_format": "application/json", "default_limit": 20, "fields": { "children": { "blank": false, "default": "No default provided.", "help_text": "Background jobs, initiated by this job.", "nullable": true, "readonly": false, "type": "related", "unique": false }, "created": { "blank": false, "default": "2014-01-30T15:28:35.527093+00:00", "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"", "nullable": false, "readonly": false, "type": "datetime", "unique": false }, "data": { "blank": false, "default": "No default provided.", "help_text": "Meta information related to this background job's execution.", "nullable": true, "readonly": false, "type": "object", "unique": false }, "last_modified": { "blank": false, "default": "2014-01-30T15:28:35.527109+00:00", "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"", "nullable": false, "readonly": false, "type": "datetime", "unique": false }, "operation": { "blank": false, "default": "No default provided.", "help_text": "Unicode string data. Ex: \"Hello World\"", "nullable": true, "readonly": false, "type": "string", "unique": false }, "resource_uri": { "blank": false, "default": "No default provided.", "help_text": "Unicode string data. Ex: \"Hello World\"", "nullable": false, "readonly": true, "type": "string", "unique": false }, "resources": { "blank": false, "default": "No default provided.", "help_text": "Resources linked to this background job.", "nullable": true, "readonly": false, "type": "list", "unique": false }, "state": { "blank": false, "default": "started", "help_text": "Unicode string data. Ex: \"Hello World\"", "nullable": false, "readonly": false, "type": "string", "unique": false }, "uuid": { "blank": false, "default": "No default provided.", "help_text": "Unicode string data. Ex: \"Hello World\"", "nullable": false, "readonly": false, "type": "string", "unique": true } }, "filtering": { "state": 1 }, "ordering": [ "-last_modified" ] }