RETIRED, Tricircle is to provide networking automation across Neutron.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

8.4 KiB

Tricircle Asynchronous Job Management API

Background

In the Tricircle, XJob provides OpenStack multi-region functionality. It receives and processes jobs from the Admin API or Tricircle Central Neutron Plugin and handles them in an asynchronous way. For example, when booting an instance in the first time for the project, router, security group rule, FIP and other resources may have not already been created in the local Neutron(s), these resources could be created asynchronously to accelerate response for the initial instance booting request, different from network, subnet and security group resources that must be created before an instance booting. Central Neutron could send such creation jobs to local Neutron(s) through XJob and then local Neutron(s) handle them with their own speed.

Implementation

XJob server may strike occasionally so tenants and cloud administrators need to know the job status and delete or redo the failed job if necessary. Asynchronous job management APIs provide such functionality and they are listed as following:

  • Create a job

    Create a job to synchronize resource if necessary.

    Create Job Request:

    POST /v1.0/jobs
    {
        "job": {
            "type": "port_delete",
            "project_id": "d01246bc5792477d9062a76332b7514a",
            "resource": {
                "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
                "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
            }
        }
    }
    
    Response:
    {
        "job": {
            "id": "3f4ecf30-0213-4f1f-9cb0-0233bcedb767",
            "project_id": "d01246bc5792477d9062a76332b7514a",
            "type": "port_delete",
            "timestamp": "2017-03-03 11:05:36",
            "status": "NEW",
            "resource": {
                "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
                "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
            }
        }
    }
    
    Normal Response Code: 202
  • Get a job

    Retrieve a job from the Tricircle database.

    The detailed information of the job will be shown. Otherwise it will return "Resource not found" exception.

    List Request:

    GET /v1.0/jobs/3f4ecf30-0213-4f1f-9cb0-0233bcedb767
    
    Response:
    {
        "job": {
            "id": "3f4ecf30-0213-4f1f-9cb0-0233bcedb767",
            "project_id": "d01246bc5792477d9062a76332b7514a",
            "type": "port_delete",
            "timestamp": "2017-03-03 11:05:36",
            "status": "NEW",
            "resource": {
                "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
                "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
            }
        }
    }
    
    Normal Response Code: 200
  • Get all jobs

    Retrieve all of the jobs from the Tricircle database.

    List Request:

    GET /v1.0/jobs/detail
    
    Response:
    {
       "jobs":
           [
                {
                    "id": "3f4ecf30-0213-4f1f-9cb0-0233bcedb767",
                    "project_id": "d01246bc5792477d9062a76332b7514a",
                    "type": "port_delete",
                    "timestamp": "2017-03-03 11:05:36",
                    "status": "NEW",
                    "resource": {
                        "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
                        "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
                    }
                },
                {
                    "id": "b01fe514-5211-4758-bbd1-9f32141a7ac2",
                    "project_id": "d01246bc5792477d9062a76332b7514a",
                    "type": "seg_rule_setup",
                    "timestamp": "2017-03-01 17:14:44",
                    "status": "FAIL",
                    "resource": {
                        "project_id": "d01246bc5792477d9062a76332b7514a"
                    }
                }
           ]
    }
    
    Normal Response Code: 200
  • Get all jobs with filter(s)

    Retrieve job(s) from the Tricircle database. We can filter them by project ID, job type and job status. If no filter is provided, GET /v1.0/jobs will return all jobs.

    The response contains a list of jobs. Using filters, a subset of jobs will be returned.

    List Request:

    GET /v1.0/jobs?project_id=d01246bc5792477d9062a76332b7514a
    
    Response:
    {
       "jobs":
           [
                {
                    "id": "3f4ecf30-0213-4f1f-9cb0-0233bcedb767",
                    "project_id": "d01246bc5792477d9062a76332b7514a",
                    "type": "port_delete",
                    "timestamp": "2017-03-03 11:05:36",
                    "status": "NEW",
                    "resource": {
                        "pod_id": "0eb59465-5132-4f57-af01-a9e306158b86",
                        "port_id": "8498b903-9e18-4265-8d62-3c12e0ce4314"
                    }
                },
                {
                    "id": "b01fe514-5211-4758-bbd1-9f32141a7ac2",
                    "project_id": "d01246bc5792477d9062a76332b7514a",
                    "type": "seg_rule_setup",
                    "timestamp": "2017-03-01 17:14:44",
                    "status": "FAIL",
                    "resource": {
                        "project_id": "d01246bc5792477d9062a76332b7514a"
                    }
                }
           ]
    }
    
    Normal Response Code: 200
  • Get all jobs' schemas

    Retrieve all jobs' schemas. User may want to know what the resources are needed for a specific job.

    List Request:

    GET /v1.0/jobs/schemas
    
    return all jobs' schemas.
    Response:
    {
       "schemas":
           [
                {
                    "type": "configure_route",
                    "resource": ["router_id"]
                },
                {
                    "type": "router_setup",
                    "resource": ["pod_id", "router_id", "network_id"]
                },
                {
                    "type": "port_delete",
                    "resource": ["pod_id", "port_id"]
                },
                {
                    "type": "seg_rule_setup",
                    "resource": ["project_id"]
                },
                {
                    "type": "update_network",
                    "resource": ["pod_id", "network_id"]
                },
                {
                    "type": "subnet_update",
                    "resource": ["pod_id", "subnet_id"]
                },
                {
                    "type": "shadow_port_setup",
                    "resource": [pod_id", "network_id"]
                }
           ]
    }
    
    Normal Response Code: 200
  • Delete a job

    Delete a failed or duplicated job from the Tricircle database. A pair of curly braces will be returned if succeeds, otherwise an exception will be thrown. What's more, we can list all jobs to verify whether it is deleted successfully or not.

    Delete Job Request:

    DELETE /v1.0/jobs/{id}
    
    Response:
    This operation does not return a response body.
    
    Normal Response Code: 200
  • Redo a job

    Redo a halted job brought by the XJob server corruption or network failures. The job handler will redo a failed job with time interval, but this Admin API will redo a job immediately. Nothing will be returned for this request, but we can monitor its status through the execution state.

    Redo Job Request:

    PUT /v1.0/jobs/{id}
    
    Response:
    This operation does not return a response body.
    
    Normal Response Code: 200

Data Model Impact

In order to manage the jobs for each tenant, we need to filter them by project ID. So project ID is going to be added to the AsyncJob model and AsyncJobLog model.

Dependencies

None

Documentation Impact

  • Add documentation for asynchronous job management API
  • Add release note for asynchronous job management API

References

None