Conch::Controller::Build

SOURCE

https://github.com/joyent/conch-api/blob/master/lib/Conch/Controller/Build.pm

METHODS

get_all

If the user is a system admin, retrieve a list of all builds in the database; otherwise, limits the list to those build of which the user is a member.

Using optional query parameters, can include counts for device health, device phase and rack phase; as well as selecting inclusion of unstarted/started, or incomplete/completed builds.

Response uses the Builds json schema.

create

Creates a build.

Requires the user to be a system admin.

find_build

Chainable action that uses the build_id_or_name value provided in the stash (usually via the request URL) to look up a build, and stashes the query to get to it in build_rs.

If require_role is provided in the stash, it is used as the minimum required role for the user to continue; otherwise the user must have the ‘admin’ role.

get

Get the details of a single build. Requires the ‘read-only’ role on the build.

Response uses the Build json schema.

update

Modifies a build attribute: one or more of name, description, started, completed, links. Requires the ‘admin’ role on the build.

add_links

Appends the provided link(s) to the build. Requires the ‘admin’ role on the build.

remove_links

When a payload is specified, remove specified links from the build; with a null payload, removes all links.

get_users

Get a list of user members of the current build. (Does not include users who can access the build via an organization.)

Requires the ‘admin’ role on the build.

Response uses the BuildUsers json schema.

add_user

Adds a user to the current build, or upgrades an existing role entry to access the build. Requires the ‘admin’ role on the build.

Optionally takes a query parameter send_mail (defaulting to true), to send an email to the user and to all build admins.

This endpoint is nearly identical to “add_user” in Conch::Controller::Organization.

remove_user

Removes the indicated user from the build. Requires the ‘admin’ role on the build.

Optionally takes a query parameter send_mail (defaulting to true), to send an email to the user and to all build admins.

This endpoint is nearly identical to “remove_user” in Conch::Controller::Organization.

get_organizations

Get a list of organization members of the current build. Requires the ‘admin’ role on the build.

Response uses the BuildOrganizations json schema.

add_organization

Adds a organization to the current build, or upgrades an existing role entry to access the build. Requires the ‘admin’ role on the build.

Optionally takes a query parameter send_mail (defaulting to true), to send an email to all organization members and all build admins.

remove_organization

Removes the indicated organization from the build. Requires the ‘admin’ role on the build.

Optionally takes a query parameter send_mail (defaulting to true), to send an email to all organization members and to all build admins.

find_devices

Chainable action that stashes the query to get to all devices in build_devices_rs.

If phase_earlier_than is provided in the stash (defaulting to production), location data is omitted for devices in the provided phase (or later) (and build racks are not used to find such devices for such phases).

get_devices

Get the devices in this build. (Does not includes devices located in rack(s) in this build if the devices themselves are in other builds.)

Requires the ‘read-only’ role on the build.

Supports these query parameters to constrain results (which are ANDed together for the search, not ORed):

health=<value>      only devices with health matching the provided value
    (can be used more than once to search for ANY of the specified health values)
phase=<value>       only devices with phase matching the provided value
    (can be used more than once to search for ANY of the specified phase values)
active_minutes=X    only devices last seen (via a report relay) within X minutes
ids_only=1          only return device ids, not full data
serials_only=1      only return device serial numbers, not full data

Response uses the Devices json schema, or DeviceIds iff ids_only=1, or DeviceSerials iff serials_only=1.

get_pxe_devices

Response uses the DevicePXEs json schema.

create_and_add_devices

Adds the specified device(s) to the build (removing them from their previous builds). The device is created if necessary with all data provided (or updated with the data if it already exists, so the endpoint is idempotent).

Requires the ‘read/write’ role on the build and on existing device(s).

add_device

Adds the specified device to the build (removing it from its previous build).

Requires the ‘read/write’ role on the build and on the device.

remove_device

Removes the specified device from the build (if it is directly in the build, not via a rack).

Requires the ‘read/write’ role on the build.

get_racks

Get the racks in this build. Requires the ‘read-only’ role on the build.

Supports these query parameters to constrain results (which are ANDed together for the search, not ORed):

phase=<value>       only racks with phase matching the provided value
    (can be used more than once to search for ANY of the specified phase values)
ids_only=1          only return rack ids, not full data

Response uses the Racks json schema, or RackIds iff ids_only=1.

add_rack

Adds the specified rack to the build (removing it from its previous build).

Requires the ‘read/write’ role on the build and on the rack.

LICENSING

This Source Code Form is subject to the terms of the Mozilla Public License, v.2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://www.mozilla.org/en-US/MPL/2.0/.