Beaker

HTTP resources

Beaker exposes machine-readable representations of certain HTTP resources, for programmatic access to Beaker’s data.

All URLs are given relative to the base URL of the Beaker server.

Note that all HTTP resources listed here support content negotiation (or will in future). Your API client must send a suitable Accept header in all requests. For example, clients expecting to receive JSON formatted responses should include Accept: application/json in all requests.

Pageable JSON collections

A number of Beaker server APIs return “pageable JSON collections”, which share some common characteristics described here.

The following query parameters are supported by pageable JSON collections:

page_size=<int>

Return this many elements per page in the response.

If this query parameter is not present, the response includes all elements in the collection. However, in cases where this would produce a very large response body, Beaker enforces pagination by redirecting the request to include a suitable page size. Therefore it is recommended that clients always include this parameter.

page=<int>
Return this page number within the collection. Pages are numbered from 1.
q=<query>

Apply this filter to the collection, prior to pagination. The query uses Lucene query parser syntax:

  • field:value finds rows where field is equal to value
  • value finds rows where any field is equal to value
  • " quotes phrases, as in field:"value with space"
  • -field:value finds rows where field is not equal to value
  • field:[1 TO 10] finds rows where field is between 1 and 10 inclusive

Each API endpoint lists the supported query fields, but in general the field names correspond to the keys in the JSON objects for each element.

sort_by=<field>
Sort elements by this field, prior to pagination. Each API endpoint lists the supported sort fields.
order=asc|desc
Must be asc or desc. Sorts in ascending or descending order, respectively.

The response is a JSON object with the following keys:

q
Filter which was applied to the collection.
count
Total number of elements in the (possibly filtered) collection.
page_size
Number of elements in each page. This is the same as the page_size query parameter if given, unless the requested page size was larger than allowed.
page
Index of this page within the entire collection. The index of the first page is 1.
sort_by, order
If a custom sort order was requested with the sort_by and order query parameters, their values are included in the response.
entries
A JSON array containing all the elements of the collection making up this page in sorted order.

Authentication

Beaker uses HTTP cookies to track sessions across HTTP calls. When calling the login_*() methods below, the response will include an HTTP cookie identifying the session. The caller must use this cookie in subsequent requests which belong with this session.

POST /auth/login_password

Authenticates the current session using the given username and password.

The caller may act as a proxy on behalf of another user by passing the proxy_user key. This requires that the caller has ‘proxy_auth’ permission. The request body must be a JSON object containing username and password. Proxy_user is optional.

JSON Parameters:
 
  • username (string) – Username
  • password (string) – Password
  • proxy_user (string) – Username on whose behalf the caller is proxying
POST /auth/login_krbv

Authenticates the current session using Kerberos. The caller may act as a proxy on behalf of another user by passing the proxy_user key. This requires that the caller has ‘proxy_auth’ permission. The request body must be a JSON object containing krb_request. Proxy_user is optional.

JSON Parameters:
 
  • krb_request (base64-encoded-string) – KRB_AP_REQ message containing client credentials, as produced by krb5_mk_req()
  • proxy_user (string) – Username on whose behalf the caller is proxying
POST /auth/login_oauth2

Authenticates the current session using OAuth2.

The caller may act as a proxy on behalf of another user by passing the proxy_user key. This requires that the caller has ‘proxy_auth’ permission. The request body must be a JSON object containing access_token. Proxy_user is optional.

JSON Parameters:
 
  • access_token (string) – The OAuth2 access token
  • proxy_user (string) – Username on whose behalf the caller is proxying
POST /auth/logout

Invalidates the current session.

GET /auth/whoami

Returns an JSON with information about the currently logged in user. Provided for testing purposes.

Systems

GET /
GET /available/
GET /free/
GET /mine/

These four URLs provide a list of systems in Beaker.

The first, /, includes all systems which are visible to the currently logged-in user. The second, /available/, lists only systems which are available for running jobs by the current user. /free/ is limited to those systems which are free to be used right now (that is, they are not currently running another job, nor are they reserved). The last, /mine/, lists only systems which are owned by the current user.

All four variations support the following query parameters:

tg_format

Desired format for the list of systems. Must be html, atom, or absent.

When this parameter is absent or set to html, Beaker will return the list of systems in an HTML table suitable for human consumption in a browser.

When set to atom, the response will be an Atom feed. Each system is represented by an <entry/> element in the feed. Each entry will contain a number of <link rel="alternate"/> elements which point to representations of the system (see below).

list_tgp_limit

Number of systems to return in the list.

By default, only the first 20 systems are returned in the list. (The HTML representation includes pagination links, but there is no such facility in the Atom representation.) Setting this parameter to 0 will return all systems in the list.

systemsearch-{N}.table
systemsearch-{N}.operation
systemsearch-{N}.value

A filter condition for the list of systems.

All three parameters should be passed together, with <N> replaced by an index to group them. For example, to limit the list to systems which belong to the “devel” group, pass these three parameters:

systemsearch-0.table=System%2FGroup&
systemsearch-0.operation=is&
systemsearch-0.value=devel

Additional filters can be applied by repeating the three parameters with a different index. For example, to also limit the list to systems with more than four logical CPUs, append these three parameters:

systemsearch-1.table=CPU%2FProcessors&
systemsearch-1.operation=greater+than&
systemsearch-1.value=4

For a list of supported filter criteria, please refer to the search box on the system listing page.

xmlsearch

As an alternative to the systemsearch filter, you can pass XML filter criteria in this parameter. It supports the same criteria as in the <hostRequires/> element in Beaker job XML.

GET /view/(fqdn)

Provides detailed information about a system.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
Query Parameters:
 
  • tg_format – Desired format for the system information. Must be html, rdfxml, turtle, or absent.

When the tg_format parameter is absent or set to html, Beaker will return the system information in HTML suitable for human consumption in a browser. When set to rdfxml or turtle, an RDF description of the system is returned (serialized as RDF/XML or Turtle, respectively). For a detailed description of the RDF schema used, refer to Common/bkr/common/schema/beaker-inventory.ttl.

GET /systems/(fqdn)/

Provides detailed information about a system in JSON format. In a future release this will be consolidated with the GET /view/(fqdn) resource.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
POST /systems/

Adds a new system to Beaker. The request must be application/json.

JSON Parameters:
 
  • fqdn (string) – Fully-qualified domain name for the new system.
  • owner (object) – JSON object containing a user_name key identifying the new owner for the system.
  • status (string) – System status: Automated, Manual, Broken, or Removed.
  • status_reason (string) – Description of why the status has been changed. Only valid when the status is Broken or Removed.
  • type (string) – System type: Machine, Prototype, Resource.
  • arches (array) – Array of architecture names (strings) supported by the system, for example ['i386', 'x86_64'].
  • lab_controller_id (int) – Lab controller which the system is attached to.
  • lab_controller (object) – JSON object containing a fqdn key identifying the lab controller which the system is attached to.
  • power_type (string) – Remote power control type. This value must be a valid power type configured by the Beaker administrator (or one of the Beaker defaults).
  • power_address (string) – Address passed to the power control script.
  • power_user (string) – Username passed to the power control script.
  • power_password (string) – Password passed to the power control script.
  • power_id (string) – Unique identifier passed to the power control script. The meaning of the power ID depends on which power type is selected. Typically this field identifies a particular plug, socket, port, or virtual guest name.
  • power_quiescent_period (int) – Quiescent period for power control. Beaker will delay at least this long between consecutive power commands.
  • release_action (string) – Action to take whenever a reservation for this system is returned: PowerOff, LeaveOn, ReProvision.
  • reprovision_distro_tree (object) – JSON object containing an id key identifying the distro tree to be installed when the release action is ReProvision.
  • location (string) – Physical location of the system.
  • lender (string) – Organization who lent this system to Beaker’s inventory.
  • kernel_type (string) – Kernel types are only relevant for the ARM architecture.
  • hypervisor (string) – Type of hypervisor which this system is hosted on, or null if it is not virtualized. Valid values are configurable by the Beaker administrator, but by default include: KVM, Xen, HyperV, VMWare.
  • vendor (string) – Vendor who produced the system.
  • model (string) – Model name or number.
  • serial_number (string) – Serial number.
  • mac_address (string) – MAC address of the default network interface.
  • memory (int) – Amount of memory (MB) installed in the system.
  • numa_nodes (int) – Number of nodes in the system’s NUMA topology.
  • active_access_policy (object) – JSON object containing a pool_name key with the name of the system pool or a custom key set to True to change the active access policy for the system.
Status Codes:
  • 302 Found – The system was successfully created and can be found at the redirected location.
PATCH /systems/(fqdn)/

Updates attributes of an existing system. The request body must be a JSON object containing one or more of the following keys.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • fqdn (string) – New FQDN for the system (it will be renamed).

See POST /systems/ for more parameters.

Status Codes:
  • 200 OK – System was updated.
  • 400 Bad Request – Invalid data was given.
  • 409 Conflict – Attempted to change the lab controller while the system is reserved. Return the system (cancel the running recipe) before changing which lab controller it is attached to.
POST /systems/(fqdn)/notes/

Records a new note for a system. System owners can use notes to record important, long-term information about a system in human-readable form. Use this to record any known limitations or unusual configurations which other users may need to be aware of.

Notes are shown on the system page, rendered as Markdown.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • text (string) – The text of the new note.
GET /systems/(fqdn)/notes/(id)

Returns details of a note recorded against a system.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
  • id – The id of the note.
PATCH /systems/(fqdn)/notes/(id)

Updates an existing note for a system.

Currently, the only permitted operation is to mark a note as deleted, by setting the “deleted” key to “now”. Deleted notes are hidden by default in the web UI, although users can still view them by requesting them explicitly.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
  • id – The id of the note to be updated.
JSON Parameters:
 
  • deleted (string) – Timestamp at which the note should be deleted. The only permitted value is “now”.
POST /systems/(fqdn)/problem-reports/

Submits a problem report about a system. The report is forwarded to the system owner and any other addresses on the system’s notification cc list.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • message (string) – Description of the problem being reported.
Status Codes:
GET /systems/(fqdn)/activity/

Returns a pageable JSON collection of the historical activity records for a system. Refer to Pageable JSON collections.

The following fields are supported for filtering and sorting:

id
ID of the activity.
user
Username of the user who performed the action.
user.user_name
Username of the user who performed the action.
user.email_address
Email address of the user who performed the action.
user.display_name
Full display name of the user who performed the action.
service
Service through which the action was performed. Usually this is XMLRPC, WEBUI, HTTP, or Scheduler.
created
Timestamp at which the activity was recorded.
action
Action which was recorded.
field_name
Field in the system data which was affected by the action.
old_value
Previous value of the field before the action was performed (if applicable).
new_value
New value of the field after the action was performed (if applicable).
GET /systems/(fqdn)/executed-tasks/

Returns a pageable JSON collection of the executed task records for a system. Refer to Pageable JSON collections.

The following fields are supported for filtering and sorting:

id
ID of the task.
name
Name of the task.
distro_tree.distro
Name of the distro being used on the task.
distro_tree.distro.name
Name of the distro being used on the task.
distro_tree.variant
Variant of the distro tree being used on the task.
distro_tree.arch
Arch of the distro tree being used on the task.
start_time
Timestamp at which the task was started.
finish_time
Timestamp at which the task was finished.
status
Current status of the task. Must be Running, Completed, or Aborted.
result
The result. Must be Pass, Warn, Fail, or None.

System access policy

GET /systems/(fqdn)/access-policy

Returns the custom access policy for a system, including all the rules making up the policy.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
GET /systems/(fqdn)/active-access-policy/

Returns the active access policy for a system, including all the rules making up the policy.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
PUT /systems/(fqdn)/access-policy

Updates the custom access policy for a system.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • rules (array) – List of rules to include in the new policy. This replaces all existing rules in the policy. Each rule is a JSON object with user, group, and everybody keys.
POST /systems/(fqdn)/access-policy

Updates the custom access policy for a system.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • rules (array) – List of rules to include in the new policy. This replaces all existing rules in the policy. Each rule is a JSON object with user, group, and everybody keys.
POST /systems/(fqdn)/access-policy/rules/

Adds a new rule to the custom access policy for a system. Each rule in the policy grants a permission to a single user, a group of users, or to everybody.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • permission (string) – Name of the permission to grant. See Access policies.
  • user (string) – User name of the user to whom the permission is granted.
  • group (string) – Name of the group to which the permission is granted.
  • everybody (bool) – If true, the permission is granted to everybody.

A rule can only apply to a user, or a group, or everybody, therefore the user, group, and everybody keys are mutually exclusive. It is invalid for more than one of them to be non-null.

DELETE /systems/(fqdn)/access-policy/rules/

Deletes one or more matching rules from a system’s custom access policy.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
Query Parameters:
 
  • permission – Delete rules which grant the named permission. See Access policies.
  • user – Delete rules which apply to the user with this username.
  • group – Delete rules which apply to this group.
  • everybody – Delete rules which apply to everybody. The value of this parameter is ignored.
Status Codes:

System reservations

POST /systems/(fqdn)/reservations/

Reserves the system “manually” (that is, bypassing the scheduler).

Parameters:
  • fqdn – The system’s fully-qualified domain name.
PATCH /systems/(fqdn)/reservations/+current

Updates the system’s current reservation. The only permitted update is to end the reservation (returning the system).

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • finish_time (string) – Must be the string now, indicating that the reservation should end now. The system will be returned.

System loans

POST /systems/(fqdn)/loan-requests/

Submits a loan request for a system. The loan request is forwarded to the system owner and any other addresses on the system’s notification cc list for their action.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • message (string) – Reason for the loan request.
Status Codes:
POST /systems/(fqdn)/loans/

Lends the system to the specified user, or borrows the system for the current user if no other user is specified.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • recipient (object) – JSON object containing a user_name key identifying the user to whom the loan will be granted. If this parameter is null or absent, the loan is granted to the user submitting this request.
  • comment (string) – Comment recorded with the loan. Used to record the purpose or conditions of the loan.
PATCH /systems/(fqdn)/loans/+current

Updates the current loan for a system. Currently, the only permitted update is to end the loan.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • finish (string) – Must be the string now, indicating that the reservation should end now. The system will be returned.

System provisioning

POST /systems/(fqdn)/installations/

Instructs Beaker to begin provisioning a system (installing an operating system).

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • distro_tree (object) – JSON object containing an id key identifying the distro tree to be provisionied.
  • ks_meta (string) – Kickstart metadata variables. See Kickstart metadata (ks_meta).
  • koptions (string) – Kernel options to be passed to the installer. See Kernel options.
  • koptions_post (string) – Kernel options to be configured after installation.
  • reboot (boolean) – If true, the system will be rebooted immediately after the installer netboot configuration has been set up.
GET /systems/(fqdn)/commands/

Returns a pageable JSON collection of the power commands for a system. Refer to Pageable JSON collections.

The following fields are supported for filtering and sorting:

id
ID of the power command.
user
Username of the user who performed the action.
user.user_name
Username of the user who performed the action.
user.email_address
Email address of the user who performed the action.
user.display_name
Full display name of the user who performed the action.
service
Service through which the power command was submitted. Usually this is XMLRPC, HTTP, or Scheduler.
submitted
Timestamp at which the command was submitted (enqueued).
start_time
Timestamp at which the command started running. This is null for commands which are still queued.
finish_time
Timestamp at which the command finished. This is null for commands which are still queued or which were aborted due to a problem with command processing.
action
Power action to be performed: on, off, interrupt, clear_netboot, configure_netboot, truncate_logs.
status
Status of this command: Queued, Running, Completed, Failed, Aborted.
message
If the command is failed or aborted, the message gives further information. For queued, running, and completed commands the message is empty.
POST /systems/(fqdn)/commands/

Queues a power command for a system. After a command is queued the lab controller will pick it up and execute it.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • action (string) – Action to be queued: on, off, interrupt, clear_netboot.
  • only_if_current_user_matches (bool) – Queue a power command only if the current user matches the system user.

System pools

GET /pools/

Returns a pageable JSON collection of system pools in Beaker. Refer to Pageable JSON collections.

The following fields are supported for filtering and sorting:

id
ID of the pool.
name
Name of the pool.
owner.user_name
Username of the pool owner (if the pool is owned by a user rather than by a group).
owner.group_name
Name of the pool’s owning group (if the pool is owned by a group rather than by a user).
GET /pools/(pool_name)/

Provides detailed information about a system pool in JSON format.

Parameters:
  • pool_name – System pool’s name.
POST /pools/

Creates a new system pool in Beaker. The request must be application/x-www-form-urlencoded or application/json.

JSON Parameters:
 
  • name (string) – Name for the system pool.
  • description (string) – Description of the system pool.
  • owner (object) – JSON object containing a user_name key or group_name key identifying the owner for the system pool.
Status Codes:
  • 201 Created – The system pool was successfully created.
PATCH /pools/(pool_name)/

Updates attributes of an existing system pool. The request body must be a JSON object containing one or more of the following keys.

Parameters:
  • pool_name – System pool’s name.
JSON Parameters:
 
  • name (string) – New name for the system pool.
  • description (string) – Description of the system pool.
  • owner (object) – JSON object containing a user_name key or group_name key identifying the new owner for the system pool.
Status Codes:
DELETE /pools/(pool_name)/

Deletes a system pool

Parameters:
  • pool_name – System pool’s name
POST /pools/(pool_name)/systems/

Add a system to a system pool

Parameters:
  • pool_name – System pool’s name.
JSON Parameters:
 
  • fqdn – System’s fully-qualified domain name.
DELETE /pools/(pool_name)/systems/

Remove a system from a system pool

Parameters:
  • pool_name – System pool’s name.
Query Parameters:
 
  • fqdn – System’s fully-qualified domain name
GET /pools/(pool_name)/access-policy/

Get access policy for pool

Parameters:
  • pool_name – System pool’s name.
PUT /pools/(pool_name)/access-policy/

Updates the access policy for a system pool.

Parameters:
  • pool_name – System pool’s name.
JSON Parameters:
 
  • rules (array) – List of rules to include in the new policy. This replaces all existing rules in the policy. Each rule is a JSON object with user, group, and everybody keys.
POST /pools/(pool_name)/access-policy/

Updates the access policy for a system pool.

Parameters:
  • pool_name – System pool’s name.
JSON Parameters:
 
  • rules (array) – List of rules to include in the new policy. This replaces all existing rules in the policy. Each rule is a JSON object with user, group, and everybody keys.
POST /pools/(pool_name)/access-policy/rules/

Adds a new rule to the access policy for a system pool. Each rule in the policy grants a permission to a single user, a group of users, or to everybody.

See System access policy for a description of the expected JSON parameters.

Parameters:
  • pool_name – System pool’s name.
DELETE /pools/(pool_name)/access-policy/rules/

Deletes one or more matching rules from a system pool’s access policy.

See System access policy for description of the expected query parameters

Parameters:
  • pool_name – System pool’s name.

Jobs

GET /jobs/(int: id)

Provides detailed information about a job in JSON format.

Parameters:
  • id – ID of the job.
GET /jobs/(int: id).junit.xml

Returns the job in JUnit-compatible XML format.

PATCH /jobs/(int: id)

Updates metadata of an existing job including retention settings and comments. The request body must be a JSON object containing one or more of the following keys.

Parameters:
  • id – Job’s id.
JSON Parameters:
 
  • retention_tag (string) – Retention tag of the job.
  • product (string) – Product of the job.
  • whiteboard (string) – Whiteboard of the job.
Status Codes:
POST /jobs/(int: id)/status

Updates the status of a job. The request must be application/json.

Currently the only allowed value for status is ‘Cancelled’, which has the effect of cancelling all recipes in the job that have not finished yet.

Parameters:
  • id – Job’s id
JSON Parameters:
 
  • status (string) – The new status. Must be ‘Cancelled’.
  • msg (string) – A message describing the reason for updating the status.
DELETE /jobs/(int: id)

Delete a job.

Parameters:
  • id – Job’s id
GET /jobs/(int: id)/activity/

Returns a JSON array of the historical activity records for a job.

POST /jobs/+inventory

Submit a inventory job with the most suitable distro selected automatically.

Returns a dictionary consisting of the job_id, recipe_id, status (recipe status) and the job XML. If dryrun is set to True in the request, the first three are set to None.

JSON Parameters:
 
  • fqdn (string) – Fully-qualified domain name for the system.
  • dryrun (bool) – If True, do not submit the job

Recipe sets

GET /recipesets/(int: id)

Provides detailed information about a recipe set in JSON format.

Parameters:
  • id – ID of the recipe set.
PATCH /recipesets/(int: id)

Updates the attributes of a recipe set. The request must be application/json.

Parameters:
  • id – ID of the recipe set.
JSON Parameters:
 
  • priority (string) – Priority for the recipe set. Must be one of ‘Low’, ‘Medium’, ‘Normal’, ‘High’, or ‘Urgent’. This can only be changed while a recipe set is still queued. Job owners can generally only decrease the priority of their recipe set, queue admins can increase it.
  • waived (boolean) – If true, the recipe set will be waived, regardless of its result.
PATCH /recipesets/by-taskspec/(taskspec)

Updates the attributes of a recipe set identified by a taskspec. The valid type of a taskspec is either J(job) or RS(recipe-set). If a taskspec format is J:<id>, all the recipe sets in this job will be updated. The request must be application/json.

Parameters:
  • taskspec – A taskspec argument that identifies a job or recipe set.
JSON Parameters:
 
  • priority (string) – Priority for the recipe set. Must be one of ‘Low’, ‘Medium’, ‘Normal’, ‘High’, or ‘Urgent’. This can only be changed while a recipe set is still queued. Job owners can generally only decrease the priority of their recipe set, queue admins can increase it.
  • waived (boolean) – If true, the recipe set will be waived, regardless of its result.
POST /recipesets/(int: id)/status

Updates the status of a recipe set. The request must be application/json.

Currently the only allowed value for status is ‘Cancelled’, which has the effect of cancelling all recipes in the recipe set that have not finished yet.

Parameters:
  • id – ID of the recipe set.
JSON Parameters:
 
  • status (string) – The new status. Must be ‘Cancelled’.
  • msg (string) – A message describing the reason for updating the status.

Recipes

GET /recipes/(int: id)

Provides detailed information about a recipe in JSON format.

Parameters:
  • id – Recipe’s id.
PATCH /recipes/(int: id)

Updates the attributes of a recipe. The request must be application/json.

Parameters:
  • id – Recipe’s id.
JSON Parameters:
 
  • whiteboard (string) – Whiteboard of the recipe.
Status Codes:
GET /recipes/(int: id)/logs/(path: path)

Redirects to the actual storage location for the requested recipe log.

Parameters:
  • id – Recipe’s id.
  • path – Log path.
PATCH /recipes/(int: id)/reservation-request

Updates the reservation request of a recipe. The request must be application/json.

Parameters:
  • id – Recipe’s id.
JSON Parameters:
 
  • reserve (boolean) – Whether the system will be reserved at the end of the recipe. If true, the system will be reserved. If false, the system will not be reserved.
  • duration (int) – Number of seconds to reserve the system.
  • when (string) –

    Circumstances under which the system will be reserved. Valid values are:

    onabort
    If the recipe status is Aborted.
    onfail
    If the recipe status is Aborted, or the result is Fail.
    onwarn
    If the recipe status is Aborted, or the result is Fail or Warn.
    always
    Unconditionally.
POST /recipes/(recipe_id)/watchdog

Extend the watchdog for a recipe.

Parameters:
  • recipe_id – The id of the recipe.
JSON Parameters:
 
  • kill_time (string) – Time in seconds to extend the watchdog by.
POST /recipes/by-taskspec/(taskspec)/watchdog

Extend the watchdog for a recipe identified by a taskspec. The valid type of a taskspec is either R(recipe) or T(recipe-task). See Specifying tasks in bkr(1).

Parameters:
  • taskspec – A taskspec argument that identifies a recipe or recipe task.
JSON Parameters:
 
  • kill_time (string) – Time in seconds to extend the watchdog by.
POST /recipes/by-fqdn/(fqdn)/watchdog

Extend the watchdog for a recipe that is running on the system.

Parameters:
  • fqdn – The system’s fully-qualified domain name.
JSON Parameters:
 
  • kill_time (string) – Time in seconds to extend the watchdog by.

Recipe tasks

GET /recipes/(recipeid)/tasks/(taskid)/logs/(path: path)

Redirects to the actual storage location for the requested task log.

Parameters:
  • recipeid – Recipe id.
  • taskid – Recipe task id.
  • path – Log path.
GET /recipes/(recipeid)/tasks/(taskid)/results/(resultid)/logs/(path: path)

Redirects to the actual storage location for the requested result log.

Parameters:
  • recipeid – Recipe id.
  • taskid – Recipe task id.
  • resultid – Recipe task result id.
  • path – Log path.
GET /recipes/(recipeid)/tasks/(taskid)/comments/

Returns a JSON collection of comments made on a recipe task.

Parameters:
  • recipeid – Recipe id.
  • taskid – Recipe task id.
POST /recipes/(recipeid)/tasks/(taskid)/comments/

Adds a new comment to a recipe task. The request must be application/json.

Parameters:
  • recipeid – Recipe id.
  • taskid – Recipe task id.
JSON Parameters:
 
  • comment (string) – Comment text.
GET /recipes/(recipeid)/tasks/(taskid)/results/(resultid)/comments/

Returns a JSON collection of comments made on a recipe task result.

Parameters:
  • recipeid – Recipe id.
  • taskid – Recipe task id.
  • resultid – Recipe task result id.
POST /recipes/(recipeid)/tasks/(taskid)/results/(resultid)/comments/

Adds a new comment to a recipe task. The request must be application/json.

Parameters:
  • recipeid – Recipe id.
  • taskid – Recipe task id.
  • resultid – Recipe task result id.
JSON Parameters:
 
  • comment (string) – Comment text.

Activity

GET /activity/

Returns a pageable JSON collection of all activity records in Beaker. Refer to Pageable JSON collections.

The following fields are supported for filtering and sorting:

id
ID of the activity.
type
Type of the activity record. Possible values are: system_activity, lab_controller_activity, distro_activity, distro_tree_activity, job_activity, recipeset_activity, recipe_activity,``user_activity``, group_activity.
service
Service through which the action was performed. Usually this is XMLRPC, WEBUI, HTTP, or Scheduler.
created
Timestamp at which the activity was recorded.
action
Action which was recorded.
field_name
Field in the system data which was affected by the action.
old_value
Previous value of the field before the action was performed (if applicable).
new_value
New value of the field after the action was performed (if applicable).
GET /activity/distro

Returns a pageable JSON collection of all distro activity records.

Supports the same fields for filtering and sorting as GET /activity/, with the following additions:

distro
Name of the distro affected.
distro.name
Name of the distro affected.
GET /activity/distrotree

Returns a pageable JSON collection of all distro tree activity records.

Supports the same fields for filtering and sorting as GET /activity/, with the following additions:

distro_tree.distro
Distro name of the tree affected.
distro_tree.distro.name
Distro name of the tree affected.
distro_tree.variant
Variant of the tree affected.
distro_tree.arch
Arch of the tree affected.
GET /activity/group

Returns a pageable JSON collection of all group activity records.

Supports the same fields for filtering and sorting as GET /activity/, with the following additions:

group
Name of the group affected.
group.group_name
Name of the group affected.
GET /activity/labcontroller

Returns a pageable JSON collection of all lab controller activity records.

Supports the same fields for filtering and sorting as GET /activity/, with the following additions:

lab_controller
FQDN of the lab controller affected.
lab_controller.fqdn
FQDN of the lab controller affected.
GET /activity/system

Returns a pageable JSON collection of all system activity records.

Supports the same fields for filtering and sorting as GET /activity/, with the following additions:

system
FQDN of the system affected.
system.fqdn
FQDN of the system affected.

Power types

GET /powertypes/

Returns a JSON collection of all power types defined in Beaker.

DELETE /powertypes/(id)

Deletes a power type by the given id.

Parameters:
  • id – The id of the power type to be deleted.
Status Codes:
POST /powertypes/

Creates a new power type. The request must be application/json.

JSON Parameters:
 
  • name (string) – Name for the power type.
Status Codes:
  • 201 Created – The power type was successfully created.

Groups

GET /groups/

Returns a pageable JSON collection of Beaker groups.

The following fields are supported for filtering and sorting:

id
ID of the group.
group_name
Symbolic name of the group.
display_name
Human-friendly display name of the group.
created
Timestamp at which the group was created.
POST /groups/

Creates a new user group in Beaker. The request must be application/json.

JSON Parameters:
 
  • group_name (string) – Symbolic name for the group.
  • display_name (string) – Human-friendly display name for the group.
  • description (string) – Description of the group.
  • root_password (string) – Optional root password for group jobs. If this is not set, group jobs will use the root password preferences of the job submitter.
  • membership_type (string) –

    Specifies how group membership is populated. Possible values are:

    • normal: Group is initially empty, members are explicitly added and removed by group owner.
    • ldap: Membership is populated from the LDAP group with the same group name.
    • inverted: Group contains all Beaker users except users who have been explicitly excluded by the group owner.
Status Codes:
GET /groups/(group_name)

Provides detailed information about a group in JSON format.

Parameters:
  • group_name – Group’s name.
PATCH /groups/(group_name)

Updates attributes of an existing group. The request body must be a JSON object containing one or more of the following keys.

JSON Parameters:
 
  • group_name (string) – New name for the group.
  • display_name (string) – Display name of the group.
  • description (string) – Description of the group.
  • root_password (string) – Optional password. Can be an empty string. If empty, group jobs will use the root password preferences of the job submitter.
  • membership_type (string) – New membership type for the group. See POST /groups/ for more information.
Status Codes:
DELETE /groups/(group_name)

Deletes a group.

Status Codes:
  • 204 No Content – Group was successfully deleted.
  • 400 Bad Request – Group cannot be deleted because it is a predefined group, or because it has associated jobs.
POST /groups/(group_name)/members/

Add a user to a group.

Parameters:
  • group_name – Group’s name.
JSON Parameters:
 
  • user_name (string) – User’s username.
  • is_owner (boolean) – If true, the given user will become one of the group owners.
DELETE /groups/(group_name)/members/

Remove a user from a group. If the user has the group ownership, it will be revoked.

Parameters:
  • group_name – Group’s name.
JSON Parameters:
 
  • user_name (string) – User’s username.
POST /groups/(group_name)/owners/

Grant group ownership to a user. The user can either be the group member or not. If the user is not the group member, it will be added first.

Parameters:
  • group_name – Group’s name.
JSON Parameters:
 
  • user_name (string) – User’s username.
DELETE /groups/(group_name)/owners/

Revoke group ownership from an existing group user.

Parameters:
  • group_name – Group’s name.
Query Parameters:
 
  • user_name – User’s username.
POST /groups/(group_name)/permissions/

Add a permission to a group.

Parameters:
  • group_name – Group’s name.
JSON Parameters:
 
  • permission_name – Permission’s name.
DELETE /groups/(group_name)/permissions/

Remove a permission from a group.

Parameters:
  • group_name – Group’s name.
Query Parameters:
 
  • permission_name – Permission’s name.
POST /groups/(group_name)/excluded-users/

Exclude a user from an inverted group. Then the user will not have the group membership.

Parameters:
  • group_name – Group’s name.
JSON Parameters:
 
  • user_name (string) – User’s username.
DELETE /groups/(group_name)/excluded-users/

Re-add a user who has been excluded from the group.

Parameters:
  • group_name – Group’s name.
Query Parameters:
 
  • user_name (string) – User’s username.

Users

GET /users/

Returns a pageable JSON collection of all users accounts in Beaker. Refer to Pageable JSON collections.

The following fields are supported for filtering and sorting:

id
ID of the user.
user_name
The user’s username.
display_name
Full display name of the user.
email_address
The user’s email address.
disabled
A boolean field which is true if the user has been temporarily disabled by the Beaker administrator (preventing them from logging in or running jobs).
removed
Timestamp when the user account was deleted, or null for a user account which has not been deleted.
POST /users/

Creates a new user account in Beaker.

GET /users/(path: username)

Returns details about a Beaker user account.

Parameters:
  • username – The user’s username.
GET /users/+self

Returns details about the currently authenticated user account.

PATCH /users/(path: username)

Updates a Beaker user account.

Parameters:
  • username – The user’s username.
JSON Parameters:
 
  • user_name (string) – New username. If the username is changed, the response will include a Location header referring to the new URL for newly renamed user resource.
  • display_name (string) – New display name.
  • email_address (string) – New email address.
  • password (string) – New password. Only valid when Beaker is not using external authentication for this account.
  • root_password (string) – Root password to be set on systems provisioned by Beaker.
  • use_old_job_page (boolean) – True if the user has opted to use the old, deprecated pre-Beaker-23 job page.
  • notify_job_completion (boolean) – True if the user receives notifications upon the completion of an owned job.
  • notify_broken_system (boolean) – True if the user receives notifications upon a system being automatically marked broken.
  • notify_system_loan (boolean) – True if the user receives notifications when their systems are loaned or loans are returned.
  • notify_group_membership (boolean) – True if the user receives notifications of modifications to the groups the user belongs to.
  • notify_reservesys (boolean) – True if the user receives notifications upon reservesys being ready.
  • disabled (boolean) – Whether the user should be temporarily disabled. Disabled users cannot log in or submit jobs, and any running jobs are cancelled when their account is disabled.
  • removed (string) – Pass the string ‘now’ to remove a user account. Pass null to un-remove a removed user account.
POST /users/(path: username)/ssh-public-keys/

Adds a new SSH public key for the given user account.

Accepts mimetype:text/plain request bodies containing the SSH public key in the conventional OpenSSH format: <keytype> <key> <ident>.

Parameters:
  • username – The user’s username.
DELETE /users/(path: username)/ssh-public-keys/(int: id)

Deletes a public SSH public key belonging to the given user account.

Parameters:
  • username – The user’s username.
  • id – Database id of the SSH public key to be deleted.
POST /users/(path: username)/submission-delegates/

Adds a submission delegate for a user account. Submission delegates are other users who are allowed to submit jobs on behalf of this user.

Parameters:
  • username – The user’s username.
JSON Parameters:
 
  • user_name (string) – The submission delegate’s username.
DELETE /users/(path: username)/submission-delegates/

Deletes a submission delegate for a user account.

Parameters:
  • username – The user’s username.
Query Parameters:
 
  • user_name (string) – The submission delegate’s username.
PUT /users/(path: username)/keystone-trust

Creates a Keystone trust between the Beaker Keystone account and this user. This allows the Beaker Keystone account to represent the delegated authority of this user when creating virtual machines on OpenStack.

Parameters:
  • username – The user’s username.
JSON Parameters:
 
  • openstack_username (string) – OpenStack username.
  • openstack_password (string) – OpenStack password.
  • openstack_project_name (string) – OpenStack project name.
  • openstack_project_domain_name (string) – OpenStack project domain name. Optional parameter. [Default value: “Default”].
  • openstack_user_domain_name (string) – OpenStack user domain name. Optional parameter. [Default value: “Default”].
Status Codes:
PUT /users/+self/keystone-trust

Creates a Keystone trust between the Beaker Keystone account and the currently authenticated user. This allows the Beaker Keystone account to represent the delegated authority of this user when creating virtual machines on OpenStack.

JSON Parameters:
 
  • openstack_username (string) – OpenStack username.
  • openstack_password (string) – OpenStack password.
  • openstack_project_name (string) – OpenStack project name.
  • openstack_project_domain_name (string) – OpenStack project domain name. Optional parameter. [Default: “Default”].
  • openstack_user_domain_name (string) – OpenStack user domain name. Optional parameter. [Default: “Default”].
Status Codes:
DELETE /users/(path: username)/keystone-trust

Deletes the Keystone trust for a user account.

Parameters:
  • username – The user’s username.

Lab Controllers

GET /labcontrollers/(fqdn)

Returns detailed information about a lab controller in JSON.

Parameters:
  • fqdn – The lab controllers FQDN
PATCH /labcontrollers/(fqdn)

Updates attributes of the lab controller identified by it’s FQDN. The request body must be a json object or only the FQDN if that is the only value to be updated.

Parameters:
  • fqdn (string) – Lab controller’s new fully-qualified domain name.
JSON Parameters:
 
  • user_name (string) – User name associated with the lab controller.
  • email_address (string) – Email of the user account associated with the lab controller.
  • password (string) – Optional password for the user account used to login.
  • removed (string) – If True, detaches all systems, cancels all running recipes and removes associated distro trees. If False, restores the lab controller.
  • disabled (bool) – Whether the lab controller should be disabled. New recipes are not scheduled on a lab controller while it is disabled.
Status Codes:
POST /labcontrollers/

Creates a new lab controller. The request must be application/json.

JSON Parameters:
 
  • fqdn (string) – Lab controller’s new fully-qualified domain name.
  • user_name (string) – User name associated with the lab controller.
  • email_address (string) – Email of the user account associated with the lab controller.
  • password (string) – Optional password for the user account used to login.
Status Codes:

Tasks

PATCH /tasks/(int: task_id)

Updates a task - only handles disabling at this time.

Parameters:
  • task_id – The task id to update/disable
JSON Parameters:
 
  • disabled (bool) – Whether the task should be disabled.
Status Codes:
  • 200 OK – Task was successfully updated/disabled
  • 404 Not Found – Task was not found (to be disabled)