pyfarm.master.api.agents module

Agents

Contained within this module are an API handling functions which can manage or query agents using JSON.

class pyfarm.master.api.agents.AgentIndexAPI[source]

Bases: flask.views.MethodView

get()[source]

A GET to this endpoint will return a list of known agents, with id and name.

GET /api/v1/agents/ HTTP/1.1

Request

GET /api/v1/agents/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "hostname": "agent1",
        "id": "dd0c6da2-0c91-42cf-a82f-6d503aae43d3"
    },
    {
        "hostname": "agent2",
        "id": "8326779e-90b5-447c-8da8-1eaa154771d9"
    },
    {
        "hostname": "agent3.local",
        "id": "14b28230-64a1-4b62-803e-5fd1baa209e4"
    }
]

Request (with filters)

GET /api/v1/agents/?min_ram=4096&min_cpus=4 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "hostname": "foobar",
    "port": 50000,
    "remote_ip": "127.0.0.1",
    "id": "e20bae92-6472-442e-98a8-0ea4c9ee41cd"
  }
]
Qparam min_ram:If set, list only agents with min_ram ram or more
Qparam max_ram:If set, list only agents with max_ram ram or less
Qparam min_cpus:
 If set, list only agents with min_cpus cpus or more
Qparam max_cpus:
 If set, list only agents with max_cpus cpus or less
Qparam hostname:
 If set, list only agents matching hostname
Qparam remote_ip:
 If set, list only agents matching remote_ip
Qparam port:If set, list only agents matching port.
Statuscode 200:no error, host may or may not have been found
methods = ['GET', 'POST']
post()[source]

A POST to this endpoint will either create or update an existing agent. The port and id columns will determine if an agent already exists.

  • If an agent is found matching the port and id columns from the request the existing model will be updated and the resulting data and the OK code will be returned.
  • If we don’t find an agent matching the port and id however a new agent will be created and the resulting data and the CREATED code will be returned.

Note

The remote_ip field is not required and should typically not be included in a request. When not provided remote_ip is be populated by the server based off of the ip of the incoming request. Providing remote_ip in your request however will override this behavior.

POST /api/v1/agents/ HTTP/1.1

Request

POST /api/v1/agents/ HTTP/1.1
Accept: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "free_ram": 133,
    "hostname": "agent1",
    "id": "6a0c11df-660f-4c1e-9fb4-5fe2b8cd2437",
    "remote_ip": "10.196.200.115",
    "port": 64994,
    "ram": 2157,
    "ram_allocation": 0.8,
    "state": 8
 }

Response (agent created)

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "use_address": "remote",
    "free_ram": 133,
    "time_offset": 0,
    "hostname": "agent1",
    "id": "6a0c11df-660f-4c1e-9fb4-5fe2b8cd2437",
    "port": 64994,
    "ram": 2157,
    "ram_allocation": 0.8,
    "state": "online",
    "remote_ip": "10.196.200.115"
 }

Response (existing agent updated)

HTTP/1.1 200 OK
Content-Type: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "use_address": "remote",
    "free_ram": 133,
    "time_offset": 0,
    "hostname": "agent1",
    "id": "6a0c11df-660f-4c1e-9fb4-5fe2b8cd2437",
    "port": 64994,
    "ram": 2157,
    "ram_allocation": 0.8,
    "state": "online",
    "remote_ip": "10.196.200.115"
 }
Statuscode 201:a new agent was created
Statuscode 200:an existing agent is updated with data from the request
Statuscode 400:there was something wrong with the request (such as invalid columns being included)
class pyfarm.master.api.agents.SingleAgentAPI[source]

Bases: flask.views.MethodView

API view which is used for retrieving information about and updating single agents.

delete(agent_id)[source]

Delete a single agent

DELETE /api/v1/agents/(uuid: agent_id) HTTP/1.1

Request (agent exists)

DELETE /api/v1/agents/b25ee7eb-9586-439a-b131-f5d022e0d403 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json
Statuscode 204:the agent was deleted or did not exist
get(agent_id)[source]

Return basic information about a single agent

GET /api/v1/agents/(str: agent_id) HTTP/1.1

Request (agent exists)

GET /api/v1/agents/4eefca76-1127-4c17-a3df-c1a7de685541 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "use_address": 311,
    "free_ram": 133,
    "time_offset": 0,
    "hostname": "agent1",
    "id": "322360ad-976f-4103-9acc-a811d43fd24d",
    "ip": "10.196.200.115",
    "port": 64994,
    "ram": 2157,
    "ram_allocation": 0.8,
    "state": 202,
    "remote_ip": "10.196.200.115"
 }

Request (no such agent)

GET /api/v1/agents/4eefca76-1127-4c17-a3df-c1a7de685541 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{"error": "Agent `4eefca76-1127-4c17-a3df-c1a7de685541` not "
          "found"}
Statuscode 200:no error
Statuscode 400:something within the request is invalid
Statuscode 404:no agent could be found using the given id
methods = ['DELETE', 'GET', 'POST']
post(agent_id)[source]

Update an agent’s columns with new information by merging the provided data with the agent’s current definition in the database.

POST /api/v1/agents/(str: agent_id) HTTP/1.1

Request

POST /api/v1/agents/29d466a5-34f8-408a-b613-e6c2715077a0 HTTP/1.1
Accept: application/json

{"ram": 1234}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "use_address": 311,
    "free_ram": 133,
    "time_offset": 0,
    "hostname": "agent1",
    "id": "29d466a5-34f8-408a-b613-e6c2715077a0",
    "ip": "10.196.200.115",
    "port": 64994,
    "ram": 1234,
    "ram_allocation": 0.8,
    "state": "running",
    "remote_ip": "10.196.200.115"
}
Statuscode 200:no error
Statuscode 400:something within the request is invalid
Statuscode 404:no agent could be found using the given id
class pyfarm.master.api.agents.SingleSoftwareInAgentAPI[source]

Bases: flask.views.MethodView

delete(agent_id, software_name, version_name)[source]

A DELETE to this endpoint will remove the specified software version from the list of supported software in this agent

DELETE /api/v1/agents/<str:agent_id>/software/<str:software>/versions/<str:version> HTTP/1.1

Request

DELETE /api/v1/agents/bbf55143-f2b1-4c15-9d41-139bd8057931/software/Blender/versions/2.72 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 NO CONTENT
Statuscode 204:the software version has been removed from the supported versions on this agent or has not been on the list in the first place
Statuscode 404:agent not found
methods = ['DELETE']
class pyfarm.master.api.agents.SoftwareInAgentIndexAPI[source]

Bases: flask.views.MethodView

get(agent_id)[source]

A GET to this endpoint will return a list of all software versions available on this agent.

GET /api/v1/agents/<str:agent_id>/software/ HTTP/1.1

Request

GET /api/v1/agents/bbf55143-f2b1-4c15-9d41-139bd8057931/software/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "software": "Blender",
        "version": "2.72"
    }
]
Statuscode 200:no error
Statuscode 404:agent not found
methods = ['GET', 'POST']
post(agent_id)[source]

A POST to this endpoint will mark the given version of the given software as available on this agent.

POST /api/v1/agents/<str:agent_id>/software/ HTTP/1.1

Request

POST /api/v1/agents/bbf55143-f2b1-4c15-9d41-139bd8057931/software/ HTTP/1.1
Accept: application/json

{
    "software": "Blender",
    "version": "2.72"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "software": "Blender",
    "version": "2.72"
}
Statuscode 200:no error
Statuscode 400:the request contained unknown keys or required keys were missing.
Statuscode 404:agent not found
class pyfarm.master.api.agents.TasksInAgentAPI[source]

Bases: flask.views.MethodView

get(agent_id)[source]

A GET to this endpoint will return a list of all tasks assigned to this agent.

GET /api/v1/agents/<str:agent_id>/tasks/ HTTP/1.1

Request

GET /api/v1/agents/bbf55143-f2b1-4c15-9d41-139bd8057931/tasks/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "state": "assign",
        "priority": 0,
        "job": {
            "jobtype": "TestJobType",
            "id": 1,
            "title": "Test Job",
            "jobtype_version": 1,
            "jobtype_id": 1
        },
        "hidden": false,
        "time_started": null,
        "project_id": null,
        "frame": 2.0
        "agent_id": "bbf55143-f2b1-4c15-9d41-139bd8057931",
        "id": 2,
        "attempts": 2,
        "project": null,
        "time_finished": null,
        "time_submitted": "2014-03-06T15:40:58.338904",
        "job_id": 1
    }
]
Statuscode 200:no error
Statuscode 404:agent not found
methods = ['GET', 'POST']
post(agent_id)[source]

A POST to this endpoint will assign am existing task to the agent.

POST /api/v1/agents/<str:agent_id>/tasks/ HTTP/1.1

Request

POST /api/v1/agents/238d7334-8ca5-4469-9f54-e76c66614a43/tasks/ HTTP/1.1
Accept: application/json

{
    "id": 2
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "agent_id": 1,
    "parents": [],
    "attempts": 2,
    "children": [],
    "job": {
        "title": "Test Job",
        "id": 1
    },
    "project_id": null,
    "agent": {
        "ip": null,
        "hostname": "agent1",
        "port": 50000,
        "id": "238d7334-8ca5-4469-9f54-e76c66614a43"
    },
    "hidden": false,
    "job_id": 1,
    "time_submitted": "2014-03-06T15:40:58.338904",
    "frame": 2.0,
    "priority": 0,
    "state": "assign",
    "time_finished": null,
    "id": 2,
    "project": null,
    "time_started": null
}
Statuscode 200:no error
Statuscode 404:agent not found
pyfarm.master.api.agents.fail_missing_assignments(agent, current_assignments)[source]
pyfarm.master.api.agents.schema()[source]

Returns the basic schema of Agent

GET /api/v1/agents/schema HTTP/1.1

Request

GET /api/v1/agents/schema HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ram": "INTEGER",
    "free_ram": "INTEGER",
    "time_offset": "INTEGER",
    "use_address": "INTEGER",
    "hostname": "VARCHAR(255)",
    "cpus": "INTEGER",
    "port": "INTEGER",
    "state": "INTEGER",
    "ram_allocation": "FLOAT",
    "cpu_allocation": "FLOAT",
    "id": "UUIDType",
    "remote_ip": "IPv4Address"
}
Statuscode 200:no error