Rhythm API

API documentation for Apache Mesos framework - Rhythm.

Authorization ¶

Rhythm has the concept of authorization backend. Authorization backend tells the level of access for particular project. There’re 3 access levels:

no access
read-only (jobs can be listed)
read-write (jobs can be listed, modified and created)

There are three built-in authorization backends:

None (default one, gives read-write access to everyone)
GitLab
LDAP

GitLab

Permissions in GitLab are described in official documentation.

Developer, Maintainer or Owner permission levels gives read-write access.
Report permission level gives read-only access
Everything else gives no access

How it works?

Client must pass X-Token HTTP header while talking to any endpoint requiring authorization. Header contains personal access token. Under the hood backend connects to GitLab server and checks permissions associated with supplied token.

If client want to access job under a/b/c then backend checks permissions of token for project b and group a on GitLab.

LDAP

How it works?

Client must authenticate using Basic auth passing username and password. Under the hood backend first checks useracl from config file (configuration doc). If useracl gives read-write or read-only access then such access is granted. Otherwise LDAP is queried for groups user is a member of. For each group groupacl from config file is checked to see what access level is granted for that group. Maximum access level across all user’s group is granted.

API v1 ¶

Available under /api/v1/.

Jobs ¶

List all jobs
GET`/api/v1/jobs`

Example URI

GET /api/v1/jobs

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "Group": "group",
    "Project": "project",
    "ID": "id",
    "Schedule": {
      "Type": "Cron",
      "Cron": "*/1 * * * *"
    },
    "LastStart": "0001-01-01T00:00:00Z",
    "CurrentTaskID": "",
    "CurrentAgentID": "",
    "Env": {},
    "Secrets": {},
    "Container": {
      "Type": "Docker",
      "Docker": {
        "Image": "alpine:3.8",
        "ForcePullImage": false
      }
    },
    "State": "Idle",
    "CPUs": 4,
    "Mem": 7168,
    "Cmd": "echo $FOO",
    "User": "someone",
    "Shell": true,
    "Arguments": [],
    "Labels": {},
    "MaxRetries": 3,
    "Retries": 0
  },
  {
    "Group": "group2",
    "Project": "project",
    "ID": "id",
    "Schedule": {
      "Type": "Cron",
      "Cron": "*/2 * * * *"
    },
    "LastStart": "0001-01-01T00:00:00Z",
    "CurrentTaskID": "",
    "CurrentAgentID": "",
    "Env": {},
    "Secrets": {},
    "Container": {
      "Type": "Docker",
      "Docker": {
        "Image": "alpine:3.8",
        "ForcePullImage": false
      }
    },
    "State": "Idle",
    "CPUs": 1,
    "Mem": 7168,
    "Cmd": "echo $FOO",
    "User": "someone",
    "Shell": true,
    "Arguments": [],
    "Labels": {},
    "MaxRetries": 0,
    "Retries": 0
  }
]

Create new job
POST`/api/v1/jobs`

Example URI

POST /api/v1/jobs

Request

HideShow

Body

{
  "id": "id",
  "group": "group",
  "project": "project",
  "cpus": 4,
  "mem": 7168,
  "cmd": "echo $FOO",
  "user": "someone",
  "env": {
    "FOO": "foo"
  },
  "schedule": {
    "cron": "*/1 * * * *"
  },
  "container": {
    "docker": {
      "image": "alpine:3.8"
    }
  }
}

Schema

{
    "type": "object",
    "properties": {
        "group": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9-_]+$"
        },
        "project": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9-_]+$"
        },
        "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9-_]+$"
        },
        "schedule": {
            "type": "object",
            "properties": {
                "cron": {
                    "type": "string",
                    "format": "cron"
                }
            },
            "required": ["cron"]
        },
        "env": {
            "type": "object"
        },
        "secrets": {
            "type": "object"
        },
        "container": {
            "type": "object",
            "oneOf": [
                {
                    "properties": {
                        "docker": {
                            "type": "object",
                            "properties": {
                                "image": {
                                    "type": "string",
                                    "minLength": 1,
                                }
                            }
                        }
                    }
                },
                {
                    "properties": {
                        "mesos": {
                            "type": "object",
                            "properties": {
                                "image": {
                                    "type": "string",
                                    "minLength": 1,
                                }
                            }
                        }
                    }
                }
            ]
        },
        "cpus": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        },
        "mem": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        },
        "disk": {
            "type": "number",
            "minimum": 0
        },
        "cmd": {
            "type": "string"
        },
        "user": {
            "type": "string"
        },
        "shell": {
            "type": "boolean"
        },
        "arguments": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "labels": {
            "type": "object"
        },
        "maxretries": {
            "type": "integer",
            "minimum": 0
        }
    },
    "required": ["group", "project", "id", "schedule", "mem", "cpus"]
}

Response 204

Group's jobs ¶

List all group's jobs
GET`/api/v1/jobs/{group}`

Example URI

GET /api/v1/jobs/a

URI Parameters

HideShow

group: string (required) Example: a
ID of the group

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "Group": "group",
    "Project": "project",
    "ID": "id",
    "Schedule": {
      "Type": "Cron",
      "Cron": "*/1 * * * *"
    },
    "LastStart": "0001-01-01T00:00:00Z",
    "CurrentTaskID": "",
    "CurrentAgentID": "",
    "Env": {},
    "Secrets": {},
    "Container": {
      "Type": "Docker",
      "Docker": {
        "Image": "alpine:3.8",
        "ForcePullImage": false
      }
    },
    "State": "Idle",
    "CPUs": 4,
    "Mem": 7168,
    "Cmd": "echo $FOO",
    "User": "someone",
    "Shell": true,
    "Arguments": [],
    "Labels": {},
    "MaxRetries": 0,
    "Retries": 0
  },
  {
    "Group": "group",
    "Project": "project2",
    "ID": "id",
    "Schedule": {
      "Type": "Cron",
      "Cron": "*/2 * * * *"
    },
    "LastStart": "0001-01-01T00:00:00Z",
    "CurrentTaskID": "",
    "CurrentAgentID": "",
    "Env": {},
    "Secrets": {},
    "Container": {
      "Type": "Docker",
      "Docker": {
        "Image": "alpine:3.8",
        "ForcePullImage": false
      }
    },
    "State": "Idle",
    "CPUs": 1,
    "Mem": 7168,
    "Cmd": "echo $FOO",
    "User": "someone",
    "Shell": true,
    "Arguments": [],
    "Labels": {},
    "MaxRetries": 0,
    "Retries": 0
  }
]

Project's jobs ¶

List all project's jobs
GET`/api/v1/jobs/{group}/{project}`

Example URI

GET /api/v1/jobs/a/b

URI Parameters

HideShow

group: string (required) Example: a
ID of the group
project: string (required) Example: b
ID of the project

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "Group": "group",
    "Project": "project",
    "ID": "id",
    "Schedule": {
      "Type": "Cron",
      "Cron": "*/1 * * * *"
    },
    "LastStart": "0001-01-01T00:00:00Z",
    "CurrentTaskID": "",
    "CurrentAgentID": "",
    "Env": {},
    "Secrets": {},
    "Container": {
      "Type": "Docker",
      "Docker": {
        "Image": "alpine:3.8",
        "ForcePullImage": false
      }
    },
    "State": "Idle",
    "CPUs": 4,
    "Mem": 7168,
    "Cmd": "echo $FOO",
    "User": "user",
    "Shell": true,
    "Arguments": [],
    "Labels": {},
    "MaxRetries": 0,
    "Retries": 0
  },
  {
    "Group": "group",
    "Project": "project",
    "ID": "id2",
    "Schedule": {
      "Type": "Cron",
      "Cron": "*/2 * * * *"
    },
    "LastStart": "0001-01-01T00:00:00Z",
    "CurrentTaskID": "",
    "CurrentAgentID": "",
    "Env": {},
    "Secrets": {},
    "Container": {
      "Type": "Docker",
      "Docker": {
        "Image": "alpine:3.8",
        "ForcePullImage": false
      }
    },
    "State": "Idle",
    "CPUs": 1,
    "Mem": 7168,
    "Cmd": "echo $FOO",
    "User": "user",
    "Shell": true,
    "Arguments": [],
    "Labels": {},
    "MaxRetries": 0,
    "Retries": 0
  }
]

Job ¶

List job
GET`/api/v1/jobs/{group}/{project}/{job}`

Example URI

GET /api/v1/jobs/a/b/c

URI Parameters

HideShow

group: string (required) Example: a
ID of the group
project: string (required) Example: b
ID of the project
job: string (required) Example: c
ID of the job

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "Group": "group",
  "Project": "project",
  "ID": "id",
  "Schedule": {
    "Type": "Cron",
    "Cron": "*/1 * * * *"
  },
  "LastStart": "0001-01-01T00:00:00Z",
  "CurrentTaskID": "",
  "CurrentAgentID": "",
  "Env": {
    "FOO": "foo"
  },
  "Secrets": {},
  "Container": {
    "Type": "Docker",
    "Docker": {
      "Image": "alpine:3.8",
      "ForcePullImage": false
    }
  },
  "State": "Idle",
  "CPUs": 4,
  "Mem": 7168,
  "Cmd": "echo $FOO",
  "User": "someone",
  "Shell": true,
  "Arguments": [],
  "Labels": {},
  "MaxRetries": 0,
  "Retries": 0
}

Delete job
DELETE`/api/v1/jobs/{group}/{project}/{job}`

Example URI

DELETE /api/v1/jobs/a/b/c

URI Parameters

HideShow

group: string (required) Example: a
ID of the group
project: string (required) Example: b
ID of the project
job: string (required) Example: c
ID of the job

Response 204

Modify job
PUT`/api/v1/jobs/{group}/{project}/{job}`

Example URI

PUT /api/v1/jobs/a/b/c

URI Parameters

HideShow

group: string (required) Example: a
ID of the group
project: string (required) Example: b
ID of the project
job: string (required) Example: c
ID of the job

Request

HideShow

Body

{
  "schedule": {
    "cron": "*/2 * * * *"
  }
}

Schema

{
    "type": "object",
    "properties": {
        "schedule": {
            "type": ["object", "null"],
            "properties": {
                "cron": {
                    "type": "string",
                    "format": "cron"
                }
            },
            "required": ["cron"]
        },
        "env": {
            "type": "object"
        },
        "secrets": {
            "type": "object"
        },
        "container": {
            "type": ["object", "null"],
            "oneOf": [
                {
                    "properties": {
                        "docker": {
                            "type": "object",
                            "properties": {
                                "image": {
                                    "type": ["string", "null"],
                                    "minLength": 1,
                                },
                                "forcepullimage": {
                                    "type": ["boolean", "null"]
                                }
                            }
                        }
                    },
                    "required": []
                },
                {
                    "properties": {
                        "mesos": {
                            "type": "object",
                            "properties": {
                                "image": {
                                    "type": "string",
                                    "minLength": 1,
                                }
                            }
                        }
                    }
                }
            ]
        },
        "cpus": {
            "type": ["number", "null"],
            "minimum": 0,
            "exclusiveMinimum": true
        },
        "mem": {
            "type": ["number", "null"],
            "minimum": 0,
            "exclusiveMinimum": true
        },
        "disk": {
            "type": ["number", "null"],
            "minimum": 0
        },
        "cmd": {
            "type": "string"
        },
        "user": {
            "type": "string"
        },
        "shell": {
            "type": "boolean"
        },
        "arguments": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "labels": {
            "type": "object"
        },
        "maxretries": {
            "type": ["integer", "null"],
            "minimum": 0
        },
    }
}

Response 204

Run ¶

Schedule job for immediate run
POST`/api/v1/jobs/{group}/{project}/{job}/run`

If job is already queued (scheduled but not launched yet) then request will be no-op.

Example URI

POST /api/v1/jobs/a/b/c/run

URI Parameters

HideShow

group: string (required) Example: a
ID of the group
project: string (required) Example: b
ID of the project
job: string (required) Example: c
ID of the job

Response 204

Tasks ¶

List history of job's tasks (runs)
GET`/api/v1/jobs/{group}/{project}/{job}/tasks`

Sorted in ascending order (oldest tasks first). If job doesn’t exist then empty list is returned with 200 HTTP status code. Properties Message, Reason and Source are set to empty strings only for successful tasks.

Example URI

GET /api/v1/jobs/a/b/c/tasks

URI Parameters

HideShow

group: string (required) Example: a
ID of the group
project: string (required) Example: b
ID of the project
job: string (required) Example: c
ID of the job

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "Start": "2018-10-30T18:09:56.195107735+01:00",
    "End": "2018-10-30T18:09:57.621237867+01:00",
    "TaskID": "group:project:id:fa3623ff-819a-4ceb-a62c-1ce52797fb60",
    "ExecutorID": "group:project:id:fa3623ff-819a-4ceb-a62c-1ce52797fb60",
    "AgentID": "3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-S0",
    "FrameworkID": "3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-0000",
    "ExecutorURL": "http://example.com:5050/#/agents/3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-S0/frameworks/3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-0000/executors/group:project:id:fa3623ff-819a-4ceb-a62c-1ce52797fb60",
    "Message": "",
    "Reason": "",
    "Source": ""
  },
  {
    "Start": "2018-10-30T18:11:07.865192348+01:00",
    "End": "2018-10-30T18:11:09.390047795+01:00",
    "TaskID": "group:project:id:b1fc414e-3745-4389-99a8-f1d7dd4da021",
    "ExecutorID": "group:project:id:b1fc414e-3745-4389-99a8-f1d7dd4da021",
    "AgentID": "3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-S0",
    "FrameworkID": "3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-0000",
    "ExecutorURL": "http://example.com:5050/#/agents/3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-S0/frameworks/3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-0000/executors/group:project:id:b1fc414e-3745-4389-99a8-f1d7dd4da021",
    "Message": "",
    "Reason": "",
    "Source": ""
  },
  {
    "Start": "2018-10-30T18:13:07.889906135+01:00",
    "End": "2018-10-30T18:13:09.245713177+01:00",
    "TaskID": "group:project:id:a837bd5d-4050-4592-93e3-7c6b6bf424b0",
    "ExecutorID": "group:project:id:a837bd5d-4050-4592-93e3-7c6b6bf424b0",
    "AgentID": "3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-S0",
    "FrameworkID": "3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-0000",
    "ExecutorURL": "http://example.com:5050/#/agents/3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-S0/frameworks/3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-0000/executors/group:project:id:a837bd5d-4050-4592-93e3-7c6b6bf424b0",
    "Message": "Failed to create executor directory '/tmp/mesos/agent/slaves/3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-S0/frameworks/3be69eb1-6b0b-4ab7-a7d1-3d3a813be77a-0000/executors/group:project:id:a837bd5d-4050-4592-93e3-7c6b6bf424b0/runs/80031a57-829e-4d0c-aeb3-2cf6d0bc30bf': Failed to chown directory to 'someone': No such user 'someone'",
    "Reason": "REASON_EXECUTOR_TERMINATED",
    "Source": "SOURCE_AGENT"
  }
]

Metrics ¶

Backed by Prometheus instrumenting library.

Metrics
GET`/api/v1/metrics`

Example URI

GET /api/v1/metrics

Response 200

HideShow

Headers

Content-Type: text/plain

Body

...
# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 14
...
# HELP leader Indicates if instance is elected as leader.
# TYPE leader gauge
leader 1 
...

Health ¶

Health
GET`/api/v1/health`

Example URI

GET /api/v1/health

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "ServerTime": "Wed Oct 24 20:54:08 CEST 2018",
  "Version": "0.2",
  "Leader": true
}

Authorization ¶

GitLab ¶

LDAP ¶

API v1 ¶

Jobs ¶

List all jobsGET/api/v1/jobs

Example URI

Headers

Body

Create new jobPOST/api/v1/jobs

Example URI

Body

Schema

Group's jobs ¶

List all group's jobsGET/api/v1/jobs/{group}

Example URI

Headers

Body

Project's jobs ¶

List all project's jobsGET/api/v1/jobs/{group}/{project}

Example URI

Headers

Body

Job ¶

List jobGET/api/v1/jobs/{group}/{project}/{job}

Example URI

Headers

Body

Delete jobDELETE/api/v1/jobs/{group}/{project}/{job}

Example URI

Modify jobPUT/api/v1/jobs/{group}/{project}/{job}

Example URI

Body

Schema

Run ¶

Schedule job for immediate runPOST/api/v1/jobs/{group}/{project}/{job}/run

Example URI

Tasks ¶

List history of job's tasks (runs)GET/api/v1/jobs/{group}/{project}/{job}/tasks

Example URI

Headers

Body

Metrics ¶

MetricsGET/api/v1/metrics

Example URI

Headers

Body

Health ¶

HealthGET/api/v1/health

Example URI

Headers

Body

GitLab

LDAP

List all jobs
GET`/api/v1/jobs`

Create new job
POST`/api/v1/jobs`

List all group's jobs
GET`/api/v1/jobs/{group}`

List all project's jobs
GET`/api/v1/jobs/{group}/{project}`

List job
GET`/api/v1/jobs/{group}/{project}/{job}`

Delete job
DELETE`/api/v1/jobs/{group}/{project}/{job}`

Modify job
PUT`/api/v1/jobs/{group}/{project}/{job}`

Schedule job for immediate run
POST`/api/v1/jobs/{group}/{project}/{job}/run`

List history of job's tasks (runs)
GET`/api/v1/jobs/{group}/{project}/{job}/tasks`

Metrics
GET`/api/v1/metrics`

Health
GET`/api/v1/health`