MAAS API¶

Restful MAAS API.

This is the documentation for the API that lets you control and query MAAS. The API is “Restful”, which means that you access it through normal HTTP requests.

API versions¶

At any given time, MAAS may support multiple versions of its API. The version number is included in the API’s URL, e.g. /api/1.0/

For now, 1.0 is the only supported version.

HTTP methods and parameter-passing¶

The following HTTP methods are available for accessing the API:

GET (for information retrieval and queries),
POST (for asking the system to do things),
PUT (for updating objects), and
DELETE (for deleting objects).

All methods except DELETE may take parameters, but they are not all passed in the same way. GET parameters are passed in the URL, as is normal with a GET: “/item/?foo=bar” passes parameter “foo” with value “bar”.

POST and PUT are different. Your request should have MIME type “multipart/form-data”; each part represents one parameter (for POST) or attribute (for PUT). Each part is named after the parameter or attribute it contains, and its contents are the conveyed value.

All parameters are in text form. If you need to submit binary data to the API, don’t send it as any MIME binary format; instead, send it as a plain text part containing base64-encoded data.

Most resources offer a choice of GET or POST operations. In those cases these methods will take one special parameter, called op, to indicate what it is you want to do.

For example, to list all nodes, you might GET “/api/1.0/nodes/?op=list”.

Operations¶

Logged-in user¶

Manage the current logged-in user.

POST /api/1.0/account/ op=create_authorisation_token

Create an authorisation OAuth token and OAuth consumer.

return: a json dict with three keys: ‘token_key’, ‘token_secret’ and ‘consumer_key’ (e.g. {token_key: ‘s65244576fgqs’, token_secret: ‘qsdfdhv34’, consumer_key: ‘68543fhj854fg’}).

rtype: string (json)

POST /api/1.0/account/ op=delete_authorisation_token

Delete an authorisation OAuth token and the related OAuth consumer.

param token_key:

The key of the token to be deleted.

type token_key: unicode

Boot image¶

Manage a boot image.

GET /api/1.0/nodegroups/{uuid}/boot-images/{id}/: Read a boot image.

Boot images¶

Manage the collection of boot images.

GET /api/1.0/nodegroups/{uuid}/boot-images/

List boot images.

Get a listing of a cluster’s boot images.

param uuid:	The UUID of the cluster for which the images should be listed.

POST /api/1.0/nodegroups/{uuid}/boot-images/ op=report_boot_images

Report images available to net-boot nodes from.

param uuid: The UUID of the cluster for which the images are being reported.

param images: A list of dicts, each describing a boot image with these properties: os, architecture, subarchitecture, release, purpose, and optionally, label (which defaults to “release”). These should match the code that determines TFTP paths for these images.

Boot source¶

Manage a boot source.

DELETE /api/1.0/nodegroups/{uuid}/boot-sources/{id}/

Delete a specific boot source.

GET /api/1.0/nodegroups/{uuid}/boot-sources/{id}/

Read a boot source.

PUT /api/1.0/nodegroups/{uuid}/boot-sources/{id}/

Update a specific boot source.

param keyring_filename:
param url:	The URL of the BootSource.
	The path to the keyring file for this BootSource.
param keyring_filename:
	The GPG keyring for this BootSource, base64-encoded data.

Boot source selection¶

Manage a boot source selection.

DELETE /api/1.0/nodegroups/{uuid}/boot-sources/{boot_source_id}/selections/{id}/

Delete a specific boot source.

GET /api/1.0/nodegroups/{uuid}/boot-sources/{boot_source_id}/selections/{id}/

Read a boot source selection.

PUT /api/1.0/nodegroups/{uuid}/boot-sources/{boot_source_id}/selections/{id}/

Update a specific boot source.

param keyring_filename:
param url:	The URL of the BootSource.
	The path to the keyring file for this BootSource.
param keyring_filename:
	The GPG keyring for this BootSource, base64-encoded data.

Boot source selections¶

Manage the collection of boot source selections.

GET /api/1.0/nodegroups/{uuid}/boot-sources/{boot_source_id}/selections/

List boot source selections.

Get a listing of a boot source’s selections.

POST /api/1.0/nodegroups/{uuid}/boot-sources/{boot_source_id}/selections/

Create a new boot source selection.

param subarches:
param release:	The Ubuntu release for which to import resources.
param arches:	The architecture list for which to import resources.
	The subarchitecture list for which to import resources.
param labels:	The label lists for which to import resources.

Boot sources¶

Manage the collection of boot sources.

GET /api/1.0/nodegroups/{uuid}/boot-sources/

List boot sources.

Get a listing of a cluster’s boot sources.

param uuid:	The UUID of the cluster for which the images should be listed.

POST /api/1.0/nodegroups/{uuid}/boot-sources/

Create a new boot source.

param keyring_filename:
param url:	The URL of the BootSource.
	The path to the keyring file for this BootSource.
param keyring_data:
	The GPG keyring for this BootSource, base64-encoded.

Commissioning results¶

Read the collection of NodeCommissionResult in the MAAS.

GET /api/1.0/commissioning-results/ op=list

List NodeCommissionResult visible to the user, optionally filtered.

param system_id:

An optional list of system ids. Only the commissioning results related to the nodes with these system ids will be returned.

type system_id: iterable

param name: An optional list of names. Only the commissioning results with the specified names will be returned.

type name: iterable

Commissioning script¶

Manage a custom commissioning script.

This functionality is only available to administrators.

DELETE /api/1.0/commissioning-scripts/{name}: Delete a commissioning script.
GET /api/1.0/commissioning-scripts/{name}: Read a commissioning script.
PUT /api/1.0/commissioning-scripts/{name}: Update a commissioning script.

Commissioning scripts¶

Manage custom commissioning scripts.

This functionality is only available to administrators.

GET /api/1.0/commissioning-scripts/

List commissioning scripts.

POST /api/1.0/commissioning-scripts/

Create a new commissioning script.

Each commissioning script is identified by a unique name.

By convention the name should consist of a two-digit number, a dash, and a brief descriptive identifier consisting only of ASCII characters. You don’t need to follow this convention, but not doing so opens you up to risks w.r.t. encoding and ordering. The name must not contain any whitespace, quotes, or apostrophes.

A commissioning node will run each of the scripts in lexicographical order. There are no promises about how non-ASCII characters are sorted, or even how upper-case letters are sorted relative to lower-case letters. So where ordering matters, use unique numbers.

Scripts built into MAAS will have names starting with “00-maas” or “99-maas” to ensure that they run first or last, respectively.

Usually a commissioning script will be just that, a script. Ideally a script should be ASCII text to avoid any confusion over encoding. But in some cases a commissioning script might consist of a binary tool provided by a hardware vendor. Either way, the script gets passed to the commissioning node in the exact form in which it was uploaded.

param name:	Unique identifying name for the script. Names should follow the pattern of “25-burn-in-hard-disk” (all ASCII, and with numbers greater than zero, and generally no “weird” characters).
param content:	A script file, to be uploaded in binary form. Note: this is not a normal parameter, but a file upload. Its filename is ignored; MAAS will know it by the name you pass to the request.

File¶

Manage a FileStorage object.

The file is identified by its filename and owner.

DELETE /api/1.0/files/{filename}/

Delete a FileStorage object.

GET /api/1.0/files/{filename}/

GET a FileStorage object as a json object.

The ‘content’ of the file is base64-encoded.

POST /api/1.0/files/{filename}/ op=delete

Delete a FileStorage object.

Files¶

Manage the collection of all the files in this MAAS.

GET /api/1.0/files/ op=get

Get a named file from the file storage.

param filename: The exact name of the file you want to get.

type filename: string

return: The file is returned in the response content.

GET /api/1.0/files/ op=get_by_key

Get a file from the file storage using its key.

param key: The exact key of the file you want to get.

type key: string

return: The file is returned in the response content.

GET /api/1.0/files/ op=list

List the files from the file storage.

The returned files are ordered by file name and the content is excluded.

param prefix: Optional prefix used to filter out the returned files.

type prefix: string

POST /api/1.0/files/ op=add

Add a new file to the file storage.

param filename: The file name to use in the storage.

type filename: string

param file: Actual file data with content type application/octet-stream

MAAS server¶

Manage the MAAS server.

GET /api/1.0/maas/ op=get_config

Get a config value.

param name: The name of the config item to be retrieved.

type name: unicode

Available configuration items:

commissioning_distro_series: Default distro series used for commissioning. Available choices are: ‘trusty’ (Ubuntu 14.04 LTS “Trusty Tahr”).

check_compatibility: Check component compatibility and certification.

http_proxy: Proxy for HTTP and HTTPS traffic. This is used by the cluster and region controllers for downloading PXE boot images and other provisioning-related resources. This will also be passed onto provisioned nodes instead of the default proxy (the region controller proxy).

default_distro_series: Default distro series used for deployment. Available choices are: ‘’ (Default Ubuntu Release), ‘precise’ (Ubuntu 12.04 LTS “Precise Pangolin”), ‘quantal’ (Ubuntu 12.10 “Quantal Quetzal”), ‘raring’ (Ubuntu 13.04 “Raring Ringtail”), ‘saucy’ (Ubuntu 13.10 “Saucy Salamander”), ‘trusty’ (Ubuntu 14.04 LTS “Trusty Tahr”).

ntp_server: Address of NTP server for nodes. NTP server address passed to nodes via a DHCP response. e.g. for ntp.ubuntu.com: ‘91.189.94.4’

enlistment_domain: Default domain for new nodes. If ‘local’ is chosen, nodes must be using mDNS. Leave empty to use hostnames without a domain for newly enlisted nodes.

upstream_dns: Upstream DNS used to resolve domains not managed by this MAAS. Only used when MAAS is running its own DNS server. This value is used as the value of ‘forwarders’ in the DNS server config.

enable_third_party_drivers: Enable the installation of proprietary drivers (i.e. HPVSA).

kernel_opts: Boot parameters to pass to the kernel by default.

main_archive: Main archive. Archive used by nodes to retrieve packages for Intel architectures. E.g. http://archive.ubuntu.com/ubuntu.

maas_name: MAAS name.

ports_archive: Ports archive. Archive used by nodes to retrieve packages for non-Intel architectures. E.g. http://ports.ubuntu.com/ubuntu-ports.

POST /api/1.0/maas/ op=set_config

Set a config value.

param name: The name of the config item to be set.

type name: unicode

param value: The value of the config item to be set.

type value: json object

Available configuration items:

commissioning_distro_series: Default distro series used for commissioning. Available choices are: ‘trusty’ (Ubuntu 14.04 LTS “Trusty Tahr”).

check_compatibility: Check component compatibility and certification.

http_proxy: Proxy for HTTP and HTTPS traffic. This is used by the cluster and region controllers for downloading PXE boot images and other provisioning-related resources. This will also be passed onto provisioned nodes instead of the default proxy (the region controller proxy).

default_distro_series: Default distro series used for deployment. Available choices are: ‘’ (Default Ubuntu Release), ‘precise’ (Ubuntu 12.04 LTS “Precise Pangolin”), ‘quantal’ (Ubuntu 12.10 “Quantal Quetzal”), ‘raring’ (Ubuntu 13.04 “Raring Ringtail”), ‘saucy’ (Ubuntu 13.10 “Saucy Salamander”), ‘trusty’ (Ubuntu 14.04 LTS “Trusty Tahr”).

ntp_server: Address of NTP server for nodes. NTP server address passed to nodes via a DHCP response. e.g. for ntp.ubuntu.com: ‘91.189.94.4’

enlistment_domain: Default domain for new nodes. If ‘local’ is chosen, nodes must be using mDNS. Leave empty to use hostnames without a domain for newly enlisted nodes.

upstream_dns: Upstream DNS used to resolve domains not managed by this MAAS. Only used when MAAS is running its own DNS server. This value is used as the value of ‘forwarders’ in the DNS server config.

enable_third_party_drivers: Enable the installation of proprietary drivers (i.e. HPVSA).

kernel_opts: Boot parameters to pass to the kernel by default.

main_archive: Main archive. Archive used by nodes to retrieve packages for Intel architectures. E.g. http://archive.ubuntu.com/ubuntu.

maas_name: MAAS name.

ports_archive: Ports archive. Archive used by nodes to retrieve packages for non-Intel architectures. E.g. http://ports.ubuntu.com/ubuntu-ports.

Network¶

Manage a network.

DELETE /api/1.0/networks/{name}/

Delete network definition.

A network cannot be deleted while it still has nodes attached to it.

GET /api/1.0/networks/{name}/

Read network definition.

GET /api/1.0/networks/{name}/ op=list_connected_macs

Returns the list of MAC addresses connected to this network.

Only MAC addresses for nodes visible to the requesting user are returned.

POST /api/1.0/networks/{name}/ op=connect_macs

Connect the given MAC addresses to this network.

These MAC addresses must belong to nodes in the MAAS, and have been registered as such in MAAS.

Connecting a network interface to a network which it is already connected to does nothing.

param macs: A list of node MAC addresses, in text form.

POST /api/1.0/networks/{name}/ op=disconnect_macs

Disconnect the given MAC addresses from this network.

Removing a MAC address from a network which it is not connected to does nothing.

param macs: A list of node MAC addresses, in text form.

PUT /api/1.0/networks/{name}/

Update network definition.

param description:
param name:	A simple name for the network, to make it easier to refer to. Must consist only of letters, digits, dashes, and underscores.
param ip:	Base IP address for the network, e.g. 10.1.0.0. The host bits will be zeroed.
param netmask:	Subnet mask to indicate which parts of an IP address are part of the network address. For example, 255.255.255.0.
param vlan_tag:	Optional VLAN tag: a number between 1 and 0xffe (4094) inclusive, or zero for an untagged network.
	Detailed description of the network for the benefit of users and administrators.

Networks¶

Manage the networks.

GET /api/1.0/networks/

List networks.

param node:	Optionally, nodes which must be attached to any returned networks. If more than one node is given, the result will be restricted to networks that these nodes have in common.

POST /api/1.0/networks/

Define a network.

param description:
param name:	A simple name for the network, to make it easier to refer to. Must consist only of letters, digits, dashes, and underscores.
param ip:	Base IP address for the network, e.g. 10.1.0.0. The host bits will be zeroed.
param netmask:	Subnet mask to indicate which parts of an IP address are part of the network address. For example, 255.255.255.0.
param vlan_tag:	Optional VLAN tag: a number between 1 and 0xffe (4094) inclusive, or zero for an untagged network.
	Detailed description of the network for the benefit of users and administrators.

Nodegroup¶

Manage a NodeGroup.

NodeGroup is the internal name for a cluster.

The NodeGroup is identified by its UUID, a random identifier that looks something like:

5977f6ab-9160-4352-b4db-d71a99066c4f

Each NodeGroup has its own uuid.

GET /api/1.0/nodegroups/{uuid}/: GET a node group.

GET /api/1.0/nodegroups/{uuid}/ op=list_nodes

Get the list of node ids that are part of this group.

POST /api/1.0/nodegroups/{uuid}/ op=details

Obtain various system details for each node specified.

For example, LLDP and lshw XML dumps.

Returns a {system_id: {detail_type: xml, ...}, ...} map, where detail_type is something like “lldp” or “lshw”.

Note that this is returned as BSON and not JSON. This is for efficiency, but mainly because JSON can’t do binary content without applying additional encoding like base-64.

For security purposes:

Requests are only fulfilled for the worker assigned to the nodegroup.

Requests for nodes that are not part of the nodegroup are just ignored.

POST /api/1.0/nodegroups/{uuid}/ op=import_boot_images

Import the pxe files on this cluster controller.

POST /api/1.0/nodegroups/{uuid}/ op=probe_and_enlist_hardware

Add special hardware types.

param model: The type of special hardware, ‘seamicro15k’ and ‘virsh’ is supported.

type model: unicode

The following are only required if you are probing a seamicro15k:

param mac: The MAC of the seamicro15k chassis.

type mac: unicode

param username: The username for the chassis.

type username: unicode

param password: The password for the chassis.

type password: unicode

The following are optional if you are probing a seamicro15k:

param power_control:

The power_control to use, either ipmi (default) or restapi.

type power_control:

unicode

The following are only required if you are probing a virsh:

param power_address:

The connection string to virsh.

type power_address:

unicode

The following are optional if you are probing a virsh:

param power_pass:

The password to use, when qemu+ssh is given as a connection string and ssh key authentication is not being used.

type power_pass:

unicode

POST /api/1.0/nodegroups/{uuid}/ op=probe_and_enlist_ucsm

Add the nodes from a Cisco UCS Manager.

:param : The URL of the UCS Manager API. :type url: unicode :param username: The username for the API. :type username: unicode :param password: The password for the API. :type password: unicode

POST /api/1.0/nodegroups/{uuid}/ op=report_download_progress

Report progress of a download.

Cluster controllers can call this to update the region controller on file downloads they need to perform, such as kernels and initrd files. This gives the administrator insight into what downloads are in progress, how well downloads are going, and what failures may have occurred.

A file is identified by an arbitrary name, which must be consistent. It could be a URL, or a filesystem path, or even a symbolic name that the cluster controller makes up. A cluster controller can download the same file many times over, but not simultaneously.

Before downloading a file, a cluster controller first reports progress without the bytes_downloaded parameter. It may optionally report progress while downloading, passing the number of bytes downloaded so far. Finally, if the download succeeded, it should report one final time with the full number of bytes downloaded.

If the download fails, the cluster controller should report progress with an error string (and either the number of bytes that were successfully downloaded, or zero).

Progress reports should include the file’s size, if known. The final report after a successful download must include the size.

param filename: Arbitrary identifier for the file being downloaded.

type filename: unicode

param size: Optional size of the file, in bytes. Must be passed at least once, though it can still be passed on subsequent calls. If file size is not known, pass it at the end when reporting successful completion. Do not change the size once given.

param bytes_downloaded:

Number of bytes that have been successfully downloaded. Cannot exceed size, if known. This parameter must be omitted from the initial progress report before download starts, and must be included for all subsequent progress reports for that download.

type bytes_downloaded:

int

param error: Optional error string. A download that has submitted an error with its last progress report is considered to have failed.

type error: unicode

POST /api/1.0/nodegroups/{uuid}/ op=update_leases

Submit latest state of DHCP leases within the cluster.

The cluster controller calls this periodically to tell the region controller about the IP addresses it manages.

PUT /api/1.0/nodegroups/{uuid}/

Update a specific cluster.

param cluster_name:
param name:	The new DNS name for this cluster.
type name:	unicode
	The new name for this cluster.
type cluster_name:
	unicode
param status:	The new status for this cluster (see vocabulary NODEGROUP_STATUS).
type status:	int

Nodegroup interface¶

Manage a NodeGroupInterface.

A NodeGroupInterface is identified by the uuid for its NodeGroup, and the name of the network interface it represents: “eth0” for example.

DELETE /api/1.0/nodegroups/{uuid}/interfaces/{interface}/: Delete a specific NodeGroupInterface.
GET /api/1.0/nodegroups/{uuid}/interfaces/{interface}/: List of NodeGroupInterfaces of a NodeGroup.

POST /api/1.0/nodegroups/{uuid}/interfaces/{interface}/ op=report_foreign_dhcp

Report the result of a probe for foreign DHCP servers.

Cluster controllers probe for DHCP servers not managed by MAAS, and call this method to report their findings.

param foreign_dhcp_ip:

New value for the foreign DHCP server found during the last probe. Leave blank if none were found.

PUT /api/1.0/nodegroups/{uuid}/interfaces/{interface}/

Update a specific NodeGroupInterface.

param interface:
param ip:	Static IP of the interface.
type ip:	unicode (IP Address)
	Name of the interface.
type interface:	unicode
param management:
	The service(s) MAAS should manage on this interface.
type management:
	Vocabulary NODEGROUPINTERFACE_MANAGEMENT
param subnet_mask:
	Subnet mask, e.g. 255.0.0.0.
type subnet_mask:
	unicode (IP Address)
param broadcast_ip:
	Broadcast address for this subnet.
type broadcast_ip:
	unicode (IP Address)
param router_ip:
	Address of default gateway.
type router_ip:	unicode (IP Address)
param ip_range_low:
	Lowest IP address to assign to clients.
type ip_range_low:
	unicode (IP Address)
param ip_range_high:
	Highest IP address to assign to clients.
type ip_range_high:
	unicode (IP Address)

Nodegroup interfaces¶

Manage the collection of all the NodeGroupInterfaces in this MAAS.

A NodeGroupInterface is a network interface attached to a cluster controller, with its network properties.

GET /api/1.0/nodegroups/{uuid}/interfaces/ op=list

List of NodeGroupInterfaces of a NodeGroup.

POST /api/1.0/nodegroups/{uuid}/interfaces/ op=new

Create a new NodeGroupInterface for this NodeGroup.

param ip: Static IP of the interface.

type ip: unicode (IP Address)

param interface:

Name of the interface.

type interface: unicode

param management:

The service(s) MAAS should manage on this interface.

type management:

Vocabulary NODEGROUPINTERFACE_MANAGEMENT

param subnet_mask:

Subnet mask, e.g. 255.0.0.0.

type subnet_mask:

unicode (IP Address)

param broadcast_ip:

Broadcast address for this subnet.

type broadcast_ip:

unicode (IP Address)

param router_ip:

Address of default gateway.

type router_ip: unicode (IP Address)

param ip_range_low:

Lowest IP address to assign to clients.

type ip_range_low:

unicode (IP Address)

param ip_range_high:

Highest IP address to assign to clients.

type ip_range_high:

unicode (IP Address)

Nodegroups¶

Manage the collection of all the nodegroups in this MAAS.

GET /api/1.0/nodegroups/ op=describe_power_types

Query all the cluster controllers for power information.

return: a list of dicts that describe the power types in this format.

GET /api/1.0/nodegroups/ op=list

List nodegroups.

POST /api/1.0/nodegroups/ op=accept

Accept nodegroup enlistment(s).

param uuid: The UUID (or list of UUIDs) of the nodegroup(s) to accept.

type name: unicode (or list of unicodes)

This method is reserved to admin users.

POST /api/1.0/nodegroups/ op=import_boot_images

Import the boot images on all the accepted cluster controllers.

POST /api/1.0/nodegroups/ op=reject

Reject nodegroup enlistment(s).

param uuid: The UUID (or list of UUIDs) of the nodegroup(s) to reject.

type name: unicode (or list of unicodes)

This method is reserved to admin users.

Node¶

Manage an individual Node.

The Node is identified by its system_id.

DELETE /api/1.0/nodes/{system_id}/: Delete a specific Node.
GET /api/1.0/nodes/{system_id}/: Read a specific Node.

GET /api/1.0/nodes/{system_id}/ op=details

Obtain various system details.

For example, LLDP and lshw XML dumps.

Returns a {detail_type: xml, ...} map, where detail_type is something like “lldp” or “lshw”.

Note that this is returned as BSON and not JSON. This is for efficiency, but mainly because JSON can’t do binary content without applying additional encoding like base-64.

POST /api/1.0/nodes/{system_id}/ op=commission

Begin commissioning process for a node.

A node in the ‘ready’, ‘declared’ or ‘failed test’ state may initiate a commissioning cycle where it is checked out and tested in preparation for transitioning to the ‘ready’ state. If it is already in the ‘ready’ state this is considered a re-commissioning process which is useful if commissioning tests were changed after it previously commissioned.

POST /api/1.0/nodes/{system_id}/ op=release

Release a node. Opposite of NodesHandler.acquire.

POST /api/1.0/nodes/{system_id}/ op=start

Power up a node.

param user_data:

If present, this blob of user-data to be made available to the nodes through the metadata service.

type user_data: base64-encoded unicode

param distro_series:

If present, this parameter specifies the Ubuntu Release the node will use.

type distro_series:

unicode

Ideally we’d have MIME multipart and content-transfer-encoding etc. deal with the encapsulation of binary data, but couldn’t make it work with the framework in reasonable time so went for a dumb, manual encoding instead.

POST /api/1.0/nodes/{system_id}/ op=stop

Shut down a node.

PUT /api/1.0/nodes/{system_id}/

Update a specific Node.

param architecture:
param hostname:	The new hostname for this node.
type hostname:	unicode
	The new architecture for this node.
type architecture:
	unicode
param power_type:
	The new power type for this node. If you use the default value, power_parameters will be set to the empty string. Available to admin users. See the Power types section for a list of the available power types.
type power_type:
	unicode
param power_parameters_{param1}:
	The new value for the ‘param1’ power parameter. Note that this is dynamic as the available parameters depend on the selected value of the Node’s power_type. For instance, if the power_type is ‘ether_wake’, the only valid parameter is ‘power_address’ so one would want to pass ‘myaddress’ as the value of the ‘power_parameters_power_address’ parameter. Available to admin users. See the Power types section for a list of the available power parameters for each power type.
type power_parameters_{param1}:
	unicode
param power_parameters_skip_check:
	Whether or not the new power parameters for this node should be checked against the expected power parameters for the node’s power type (‘true’ or ‘false’). The default is ‘false’.
type power_parameters_skip_check:
	unicode
param zone:	Name of a valid physical zone in which to place this node
type zone:	unicode

Node MAC address¶

Manage a Node MAC address.

The MAC address object is identified by the system_id for the Node it is attached to, plus the MAC address itself.

DELETE /api/1.0/nodes/{system_id}/macs/{mac_address}/: Delete a specific MAC address for the specified Node.
GET /api/1.0/nodes/{system_id}/macs/{mac_address}/: Read a MAC address related to a Node.

Node MAC addresses¶

Manage MAC addresses for a given Node.

This is where you manage the MAC addresses linked to a Node, including associating a new MAC address with the Node.

The Node is identified by its system_id.

GET /api/1.0/nodes/{system_id}/macs/: Read all MAC addresses related to a Node.
POST /api/1.0/nodes/{system_id}/macs/: Create a MAC address for a specified Node.

Nodes¶

Manage the collection of all the nodes in the MAAS.

GET /api/1.0/nodes/ op=list

List Nodes visible to the user, optionally filtered by criteria.

param hostname: An optional list of hostnames. Only nodes with matching hostnames will be returned.

type hostname: iterable

param mac_address:

An optional list of MAC addresses. Only nodes with matching MAC addresses will be returned.

type mac_address:

iterable

param id: An optional list of system ids. Only nodes with matching system ids will be returned.

type id: iterable

param zone: An optional name for a physical zone. Only nodes in the zone will be returned.

type zone: unicode

param agent_name:

An optional agent name. Only nodes with matching agent names will be returned.

type agent_name:

unicode

GET /api/1.0/nodes/ op=list_allocated

Fetch Nodes that were allocated to the User/oauth token.

POST /api/1.0/nodes/ op=accept

Accept declared nodes into the MAAS.

Nodes can be enlisted in the MAAS anonymously or by non-admin users, as opposed to by an admin. These nodes are held in the Declared state; a MAAS admin must first verify the authenticity of these enlistments, and accept them.

Enlistments can be accepted en masse, by passing multiple nodes to this call. Accepting an already accepted node is not an error, but accepting one that is already allocated, broken, etc. is.

param nodes: system_ids of the nodes whose enlistment is to be accepted. (An empty list is acceptable).

return: The system_ids of any nodes that have their status changed by this call. Thus, nodes that were already accepted are excluded from the result.

POST /api/1.0/nodes/ op=accept_all

Accept all declared nodes into the MAAS.

Nodes can be enlisted in the MAAS anonymously or by non-admin users, as opposed to by an admin. These nodes are held in the Declared state; a MAAS admin must first verify the authenticity of these enlistments, and accept them.

return: Representations of any nodes that have their status changed by this call. Thus, nodes that were already accepted are excluded from the result.

POST /api/1.0/nodes/ op=acquire

Acquire an available node for deployment.

Constraints parameters can be used to acquire a node that possesses certain characteristics. All the constraints are optional and when multiple constraints are provided, they are combined using ‘AND’ semantics.

param name: Hostname of the returned node.

type name: unicode

param arch: Architecture of the returned node (e.g. ‘i386/generic’, ‘amd64’, ‘armhf/highbank’, etc.).

type arch: unicode

param cpu_count:

The minium number of CPUs the returned node must have.

type cpu_count: int

param mem: The minimum amount of memory (expressed in MB) the returned node must have.

type mem: float

param tags: List of tags the returned node must have.

type tags: list of unicodes

param connected_to:

List of routers’ MAC addresses the returned node must be connected to.

type connected_to:

unicode or list of unicodes

param networks: List of networks (defined in MAAS) to which the node must be attached. A network can be identified by the name assigned to it in MAAS; or by an ip: prefix followed by any IP address that falls within the network; or a vlan: prefix followed by a numeric VLAN tag, e.g. vlan:23 for VLAN number 23. Valid VLAN tags must be in the range of 1 to 4095 inclusive.

type networks: list of unicodes

param not_networks:

List of networks (defined in MAAS) to which the node must not be attached. The returned noded won’t be attached to any of the specified networks. A network can be identified by the name assigned to it in MAAS; or by an ip: prefix followed by any IP address that falls within the network; or a vlan: prefix followed by a numeric VLAN tag, e.g. vlan:23 for VLAN number 23. Valid VLAN tags must be in the range of 1 to 4095 inclusive.

type not_networks:

list of unicodes

param not_connected_to:

List of routers’ MAC Addresses the returned node must not be connected to.

type connected_to:

list of unicodes

param zone: An optional name for a physical zone the acquired node should be located in.

type zone: unicode

type not_in_zone:

Optional list of physical zones from which the node should not be acquired.

type not_in_zone:

List of unicodes.

param agent_name:

An optional agent name to attach to the acquired node.

type agent_name:

unicode

POST /api/1.0/nodes/ op=check_commissioning

Check all commissioning nodes to see if they are taking too long.

Anything that has been commissioning for longer than settings.COMMISSIONING_TIMEOUT is moved into the FAILED_TESTS status.

POST /api/1.0/nodes/ op=new

Create a new Node.

When a node has been added to MAAS by an admin MAAS user, it is ready for allocation to services running on the MAAS. The minimum data required is: architecture=<arch string> (e.g. “i386/generic”) mac_addresses=<value> (e.g. “aa:bb:cc:dd:ee:ff”)

param architecture:

A string containing the architecture type of the node.

param mac_addresses:

One or more MAC addresses for the node.

param hostname: A hostname. If not given, one will be generated.

param power_type:

A power management type, if applicable (e.g. “virsh”, “ipmi”).

POST /api/1.0/nodes/ op=release

Release multiple nodes.

This places the nodes back into the pool, ready to be reallocated.

param nodes: system_ids of the nodes which are to be released. (An empty list is acceptable).

return: The system_ids of any nodes that have their status changed by this call. Thus, nodes that were already released are excluded from the result.

POST /api/1.0/nodes/ op=set_zone

Assign multiple nodes to a physical zone at once.

param zone: Zone name. If omitted, the zone is “none” and the nodes will be taken out of their physical zones.

param nodes: system_ids of the nodes whose zones are to be set. (An empty list is acceptable).

SSH Key¶

Manage an SSH key.

SSH keys can be retrieved or deleted.

DELETE /api/1.0/account/prefs/sshkeys/{keyid}/: DELETE an SSH key.
GET /api/1.0/account/prefs/sshkeys/{keyid}/: GET an SSH key.

POST /api/1.0/account/prefs/sshkeys/{keyid}/ op=delete

DELETE an SSH key.

SSH Keys¶

Manage the collection of all the SSH keys in this MAAS.

GET /api/1.0/account/prefs/sshkeys/ op=list

List all keys belonging to the requesting user.

POST /api/1.0/account/prefs/sshkeys/ op=new

Add a new SSH key to the requesting user’s account.

The request payload should contain the public SSH key data in form data whose name is “key”.

Tag¶

Manage a Tag.

Tags are properties that can be associated with a Node and serve as criteria for selecting and allocating nodes.

A Tag is identified by its name.

DELETE /api/1.0/tags/{name}/: Delete a specific Tag.
GET /api/1.0/tags/{name}/: Read a specific Tag

GET /api/1.0/tags/{name}/ op=nodes

Get the list of nodes that have this tag.

POST /api/1.0/tags/{name}/ op=rebuild

Manually trigger a rebuild the tag <=> node mapping.

This is considered a maintenance operation, which should normally not be necessary. Adding nodes or updating a tag’s definition should automatically trigger the appropriate changes.

POST /api/1.0/tags/{name}/ op=update_nodes

Add or remove nodes being associated with this tag.

param add: system_ids of nodes to add to this tag.

param remove: system_ids of nodes to remove from this tag.

param definition:

(optional) If supplied, the definition will be validated against the current definition of the tag. If the value does not match, then the update will be dropped (assuming this was just a case of a worker being out-of-date)

param nodegroup:

A uuid of a nodegroup being processed. This value is optional. If not supplied, the requester must be a superuser. If supplied, then the requester must be the worker associated with that nodegroup, and only nodes that are part of that nodegroup can be updated.

PUT /api/1.0/tags/{name}/

Update a specific Tag.

param definition:
param name:	The name of the Tag to be created. This should be a short name, and will be used in the URL of the tag.
param comment:	A long form description of what the tag is meant for. It is meant as a human readable description of the tag.
	An XPATH query that will be evaluated against the hardware_details stored for all nodes (output of lshw -xml).

Tags¶

Manage the collection of all the Tags in this MAAS.

GET /api/1.0/tags/ op=list

List Tags.

Get a listing of all tags that are currently defined.

POST /api/1.0/tags/ op=new

Create a new Tag.

param name: The name of the Tag to be created. This should be a short name, and will be used in the URL of the tag.

param comment: A long form description of what the tag is meant for. It is meant as a human readable description of the tag.

param definition:

An XPATH query that will be evaluated against the hardware_details stored for all nodes (output of lshw -xml).

param kernel_opts:

Can be None. If set, nodes associated with this tag will add this string to their kernel options when booting. The value overrides the global ‘kernel_opts’ setting. If more than one tag is associated with a node, the one with the lowest alphabetical name will be picked (eg 01-my-tag will be taken over 99-tag-name).

Users¶

Manage the user accounts of this MAAS.

GET /api/1.0/users/

List users.

POST /api/1.0/users/

Create a MAAS user account.

This is not safe: the password is sent in plaintext. Avoid it for production, unless you are confident that you can prevent eavesdroppers from observing the request.

param is_superuser:
param username:	Identifier-style username for the new user.
type username:	unicode
param email:	Email address for the new user.
type email:	unicode
param password:	Password for the new user.
type password:	unicode
	Whether the new user is to be an administrator.
type is_superuser:
	bool (‘0’ for False, ‘1’ for True)

Zone¶

Manage a physical zone.

Any node is in a physical zone, or “zone” for short. The meaning of a physical zone is up to you: it could identify e.g. a server rack, a network, or a data centre. Users can then allocate nodes from specific physical zones, to suit their redundancy or performance requirements.

This functionality is only available to administrators. Other users can view physical zones, but not modify them.

DELETE /api/1.0/zones/{name}/: DELETE request. Delete zone.
GET /api/1.0/zones/{name}/: GET request. Return zone.
PUT /api/1.0/zones/{name}/: PUT request. Update zone.

Zones¶

Manage physical zones.

GET /api/1.0/zones/

List zones.

Get a listing of all the physical zones.

POST /api/1.0/zones/

Create a new physical zone.

param description:
param name:	Identifier-style name for the new zone.
type name:	unicode
	Free-form description of the new zone.
type description:
	unicode

Power types¶

This is the list of the supported power types and their associated power parameters. Note that the list of usable power types for a particular cluster might be a subset of this list if the cluster in question is from an older version of MAAS.

ether_wake (Wake-on-LAN)¶

Power parameters:

mac_address (MAC Address).

virsh (Virsh (virtual systems))¶

Power parameters:

power_address (Power address).
power_id (Power ID).
power_pass (Power password (optional)).

fence_cdu (Sentry Switch CDU)¶

Power parameters:

power_address (Power address).
power_id (Power ID).
power_user (Power user).
power_pass (Power password).

ipmi (IPMI)¶

Power parameters:

power_driver (Power driver). Choices: ‘LAN’ (LAN [IPMI 1.5]), ‘LAN_2_0’ (LAN_2_0 [IPMI 2.0]) Default: ‘LAN_2_0’.
power_address (IP address).
power_user (Power user).
power_pass (Power password).
mac_address (MAC address - the IP is looked up with ARP and is used if IP address is empty. This is better when the BMC uses DHCP.).

moonshot (iLO4 Moonshot Chassis)¶

Power parameters:

power_address (Power address).
power_user (Power user).
power_pass (Power password).
power_hwaddress (Power hardware address).

sm15k (SeaMicro 15000)¶

Power parameters:

system_id (System ID).
power_address (Power address).
power_user (Power user).
power_pass (Power password).
power_control (Power control type). Choices: ‘ipmi’ (IPMI), ‘restapi’ (REST API v0.9), ‘restapi2’ (REST API v2.0) Default: ‘ipmi’.

amt (Intel AMT)¶

Power parameters:

mac_address (MAC Address).
power_pass (Power password).
power_address (An IP address to use instead of the node’s primary NIC’s IP (i.e. the IP of the MAC above, looked up with ARP).).

dli (Digital Loggers, Inc. PDU)¶

Power parameters:

system_id (Outlet ID).
power_address (Power address).
power_user (Power user).
power_pass (Power password).

ucsm (Cisco UCS Manager)¶

Power parameters:

uuid (Server UUID).
power_address (URL for XML API).
power_user (API user).
power_pass (API password).

return:	a json dict with three keys: ‘token_key’, ‘token_secret’ and ‘consumer_key’ (e.g. {token_key: ‘s65244576fgqs’, token_secret: ‘qsdfdhv34’, consumer_key: ‘68543fhj854fg’}).
rtype:	string (json)

param uuid:	The UUID of the cluster for which the images are being reported.
param images:	A list of dicts, each describing a boot image with these properties: os, architecture, subarchitecture, release, purpose, and optionally, label (which defaults to “release”). These should match the code that determines TFTP paths for these images.

param system_id:
	An optional list of system ids. Only the commissioning results related to the nodes with these system ids will be returned.
type system_id:	iterable
param name:	An optional list of names. Only the commissioning results with the specified names will be returned.
type name:	iterable

param filename:	The exact name of the file you want to get.
type filename:	string
return:	The file is returned in the response content.

param key:	The exact key of the file you want to get.
type key:	string
return:	The file is returned in the response content.

param prefix:	Optional prefix used to filter out the returned files.
type prefix:	string

param filename:	The file name to use in the storage.
type filename:	string
param file:	Actual file data with content type application/octet-stream

param name:	The name of the config item to be retrieved.
type name:	unicode

param name:	The name of the config item to be set.
type name:	unicode
param value:	The value of the config item to be set.
type value:	json object

param model:	The type of special hardware, ‘seamicro15k’ and ‘virsh’ is supported.
type model:	unicode

param mac:	The MAC of the seamicro15k chassis.
type mac:	unicode
param username:	The username for the chassis.
type username:	unicode
param password:	The password for the chassis.
type password:	unicode

param power_control:
	The power_control to use, either ipmi (default) or restapi.
type power_control:
	unicode

param power_pass:
	The password to use, when qemu+ssh is given as a connection string and ssh key authentication is not being used.
type power_pass:
	unicode

param bytes_downloaded:
param filename:	Arbitrary identifier for the file being downloaded.
type filename:	unicode
param size:	Optional size of the file, in bytes. Must be passed at least once, though it can still be passed on subsequent calls. If file size is not known, pass it at the end when reporting successful completion. Do not change the size once given.
	Number of bytes that have been successfully downloaded. Cannot exceed size, if known. This parameter must be omitted from the initial progress report before download starts, and must be included for all subsequent progress reports for that download.
type bytes_downloaded:
	int
param error:	Optional error string. A download that has submitted an error with its last progress report is considered to have failed.
type error:	unicode

param uuid:	The UUID (or list of UUIDs) of the nodegroup(s) to accept.
type name:	unicode (or list of unicodes)

param user_data:
	If present, this blob of user-data to be made available to the nodes through the metadata service.
type user_data:	base64-encoded unicode
param distro_series:
	If present, this parameter specifies the Ubuntu Release the node will use.
type distro_series:
	unicode

param mac_address:
param hostname:	An optional list of hostnames. Only nodes with matching hostnames will be returned.
type hostname:	iterable
	An optional list of MAC addresses. Only nodes with matching MAC addresses will be returned.
type mac_address:
	iterable
param id:	An optional list of system ids. Only nodes with matching system ids will be returned.
type id:	iterable
param zone:	An optional name for a physical zone. Only nodes in the zone will be returned.
type zone:	unicode
param agent_name:
	An optional agent name. Only nodes with matching agent names will be returned.
type agent_name:
	unicode

param nodes:	system_ids of the nodes whose enlistment is to be accepted. (An empty list is acceptable).
return:	The system_ids of any nodes that have their status changed by this call. Thus, nodes that were already accepted are excluded from the result.

param cpu_count:
param name:	Hostname of the returned node.
type name:	unicode
param arch:	Architecture of the returned node (e.g. ‘i386/generic’, ‘amd64’, ‘armhf/highbank’, etc.).
type arch:	unicode
	The minium number of CPUs the returned node must have.
type cpu_count:	int
param mem:	The minimum amount of memory (expressed in MB) the returned node must have.
type mem:	float
param tags:	List of tags the returned node must have.
type tags:	list of unicodes
param connected_to:
	List of routers’ MAC addresses the returned node must be connected to.
type connected_to:
	unicode or list of unicodes
param networks:	List of networks (defined in MAAS) to which the node must be attached. A network can be identified by the name assigned to it in MAAS; or by an ip: prefix followed by any IP address that falls within the network; or a vlan: prefix followed by a numeric VLAN tag, e.g. vlan:23 for VLAN number 23. Valid VLAN tags must be in the range of 1 to 4095 inclusive.
type networks:	list of unicodes
param not_networks:
	List of networks (defined in MAAS) to which the node must not be attached. The returned noded won’t be attached to any of the specified networks. A network can be identified by the name assigned to it in MAAS; or by an ip: prefix followed by any IP address that falls within the network; or a vlan: prefix followed by a numeric VLAN tag, e.g. vlan:23 for VLAN number 23. Valid VLAN tags must be in the range of 1 to 4095 inclusive.
type not_networks:
	list of unicodes
param not_connected_to:
	List of routers’ MAC Addresses the returned node must not be connected to.
type connected_to:
	list of unicodes
param zone:	An optional name for a physical zone the acquired node should be located in.
type zone:	unicode
type not_in_zone:
	Optional list of physical zones from which the node should not be acquired.
type not_in_zone:
	List of unicodes.
param agent_name:
	An optional agent name to attach to the acquired node.
type agent_name:
	unicode

param architecture:
	A string containing the architecture type of the node.
param mac_addresses:
	One or more MAC addresses for the node.
param hostname:	A hostname. If not given, one will be generated.
param power_type:
	A power management type, if applicable (e.g. “virsh”, “ipmi”).

Navigation

MAAS API¶

API versions¶

HTTP methods and parameter-passing¶

Operations¶

Logged-in user¶

Boot image¶

Boot images¶

Boot source¶

Boot source selection¶

Boot source selections¶

Boot sources¶

Commissioning results¶

Commissioning script¶

Commissioning scripts¶

File¶

Files¶

MAAS server¶

Network¶

Networks¶

Nodegroup¶

Nodegroup interface¶

Nodegroup interfaces¶

Nodegroups¶

Node¶

Node MAC address¶

Node MAC addresses¶

Nodes¶

SSH Key¶

SSH Keys¶

Tag¶

Tags¶

Users¶

Zone¶

Zones¶

Power types¶

ether_wake (Wake-on-LAN)¶

virsh (Virsh (virtual systems))¶

fence_cdu (Sentry Switch CDU)¶

ipmi (IPMI)¶

moonshot (iLO4 Moonshot Chassis)¶

sm15k (SeaMicro 15000)¶

amt (Intel AMT)¶

dli (Digital Loggers, Inc. PDU)¶

ucsm (Cisco UCS Manager)¶

MAAS

Related Topics

This Page

Quick search

Navigation

param nodes:	system_ids of the nodes which are to be released. (An empty list is acceptable).
return:	The system_ids of any nodes that have their status changed by this call. Thus, nodes that were already released are excluded from the result.

param zone:	Zone name. If omitted, the zone is “none” and the nodes will be taken out of their physical zones.
param nodes:	system_ids of the nodes whose zones are to be set. (An empty list is acceptable).

param definition:
param add:	system_ids of nodes to add to this tag.
param remove:	system_ids of nodes to remove from this tag.
	(optional) If supplied, the definition will be validated against the current definition of the tag. If the value does not match, then the update will be dropped (assuming this was just a case of a worker being out-of-date)
param nodegroup:
	A uuid of a nodegroup being processed. This value is optional. If not supplied, the requester must be a superuser. If supplied, then the requester must be the worker associated with that nodegroup, and only nodes that are part of that nodegroup can be updated.