API reference

The default bootstrap iPXE file

A GET request to /api/microkernel/bootstrap returns the iPXE script that you should put on your TFTP server (usually called bootstrap.ipxe) The script gathers information about the node (the hw_info) that it sends to the server and that the server uses to identify the node and determine how exactly the node should boot.

The URL accepts the parameter nic_max, which you should set to the maximum number of network interfaces that respond to DHCP on any given node. It defaults to 4.

The URL also accepts an http_port parameter, which tells Razor which port its internal HTTP communications should use, and the /svc URLs must be available through that port. The default install will use 8150 for this.

Nodes

Register a node (`register-node`)

Register a node with Razor before it is discovered, and potentially provisioned. In environments in which some nodes have been provisioned outside of Razor’s purview, this command offers a way to tell Razor that a node is valuable and not eligible for automatic reprovisioning with Razor. Such nodes are only reprovisioned if they are marked available with the reinstall-node command.

The register-node command allows you to perform the same registration that would happen when a new node checks in, but ahead of time. The register-node command uses the installed value to indicate that a node has already been installed, which signals to Razor that the node should be ignored, and Razor should act as if it had successfully installed that node.

In order for this command to be effective, hw_info must contain enough information that the node can successfully be identified based on the hardware information sent from iPXE when the node boots; this usually includes the MAC addresses of all network interfaces of the node.

register-nodes accepts the following parameters:

hw_info: Required, provides the hardware information for the node. This is used to match the node on first boot with the record in the database. The hw_info can contain all or a subset of the following entries:
- netN: The MAC addresses of each network interface, for example net0 or net2: The order of the MAC addresses is not significant.
- serial: The DMI serial number of the node.
- asset: The DMI asset tag of the node.
- uuid: DMI UUID of the node.
installed: A boolean flag indicating whether this node should be considered installed and therefore not eligible for reprovisioning by Razor

API example

Registering a machine before booting it with installed set to true will protect it from accidental reinstallation by Razor:

{
  "hw_info": {
    "net0":   "78:31:c1:be:c8:00",
    "net1":   "72:00:01:f2:13:f0",
    "net2":   "72:00:01:f2:13:f1"
  },
  "installed": true
}

Set node hardware info (`set-node-hw-info`)

When a node’s hardware changes, such as a network card being replaced, the Razor server needs to be informed so it can correctly match the new hardware to the existing node definition.

The set-node-hw-info command lets you replace the existing hardware data with new data, prior to booting the modified node on the network. For example, update node172 with new hardware information as follows:

  {
      "node": "node172",
      "hw_info": {
        "net0":   "78:31:c1:be:c8:00",
        "net1":   "72:00:01:f2:13:f0",
        "net2":   "72:00:01:f2:13:f1"
      }
  }

The format of the hw_info is the same as for the register-node command, where you can find more details about it.

Delete node (`delete-node`)

To remove a single node, provide its name:

{
  "name": "node17"
}

Note: If the deleted node boots again at some point, Razor automatically recreates it.

Reinstall node (`reinstall-node`)

To remove a node’s association with any policy and clear its installed flag, provide its name:

{
  "name": "node17"
}

Once the node reboots, it boots back into the microkernel, goes through discovery and tag matching, and can bind to another policy for reinstallation. This command does not change the node’s metadata or facts.

Intelligent Platform Management Interface

IPMI commands are node commands based on the Intelligent Platform Management Interface.

Note: You must install the ipmitool on the Razor server before using IPMI commands. To install the tool, run yum install ipmitool -y.

Set node IPMI credentials (`set-node-ipmi-credentials`)

Razor can store IPMI credentials on a per-node basis. These credentials include a hostname (or IP address), username, and password to use when contacting the BMC/LOM/IPMI LAN or LANplus service to check or update power state and other node data. After IPMI credentials have been set up for a node, you can use the reboot-node and set-node-desired-power-state commands.

These three data items can only be set or reset together, in a single operation. When you omit a parameter, Razor sets it to NULL (representing no value, or the NULL username/password as defined by IPMI).

The structure of a request is:

{
  "name": "node17",
  "ipmi_hostname": "bmc17.example.com",
  "ipmi_username": null,
  "ipmi_password": "sekretskwirrl"
}

This command only works with remote IPMI targets, not locally; therefore, you must provide an IPMI hostname.

Reboot node (`reboot-node`)

If you’ve associated IPMI credentials with a node, Razor can use IPMI to trigger a hard power cycle. Just provide the name of the node:

{
  "name": "node1",
}

The IPMI communication spec includes some generous internal rate limits to prevent it from overwhelming the network or host server. If an execution slot isn’t available on the target node, your reboot-node command goes into a background queue, and runs as soon as a slot is available.

This background queue is cumulative and persistent: there are no limits on how many commands you can queue up, how frequently a node can be rebooted, or how long a command can stay in the queue. If you restart your Razor server before the queued commands are executed, they’ll remain in the queue and run after the server restarts.

The reboot node command is not integrated with IPMI power state monitoring, so you can’t see power transitions in the record or when polling the node object.

Set a node’s desired power state (`set-node-desired-power-state`)

By default, Razor checks your nodes’ power states every few minutes in the background. If it detects a node in a non-desired state, Razor issues an IPMI command directing the node to its desired state.

To set the desired state for a node:

{
  "name": "node1234",
  "to":   "on"|"off"|null
}

The name parameter identifies the node to change the setting on. The to parameter contains the desired power state to set. Valid values

are on, off, or null (the JSON NULL/nil value), which reflect “power on”, “power off”, and “do not enforce power state” respectively.

Node metadata

Modify node metadata (`modify-node-metadata`)

Node metadata is a collection of key/value pairs, much like a node’s facts. The difference is that the facts represent what the node tells Razor about itself, while its metadata represents what you tell Razor about the node.

The modify-node-metadata command lets you add/update or remove individual metadata keys, or fully clear out a node’s metadata:

{
  "node": "node1",
  "update": {                         # Add or update these keys
      "key1": "value1",
      "key2": "value2",
        ...
  }
  "remove": [ "key3", "key4", ... ],  # Remove these keys
  "no_replace": true                  # Do not replace keys on
                                        # update. Only add new keys
}

{
  "node": "node1",
  "clear": true                       # Clear all metadata
}

As above, you can submit multiple updates and/or removes in a single command. However, clear only works on its own.

Update node metadata (`update-node-metadata`)

The update-node-metadata command offers a simplified way to update a single metadata key. the body for the command must be:

{
    "node"      : "mode1",
    "key"       : "my_key",
    "value"     : "my_val",
    "no_replace": true
}

The no_replace parameter is optional. If it is true, the metadata entry will not be modified if it already exists.

Remove node metadata (`remove-node-metadata`)

The remove-node-metadata command offers a simplified way to remove either a single metadata entry or all metadata entries on a node:

{
  "node" : "node1",
  "key"  : "my_key",
}

{
  "node" : "node1",
  "all"  : true,     # Removes all keys
}

Repositories

Create new repository (`create-repo`)

The create-repo command creates a new repository. The repository can contain the content to install a node, or it can point to an existing online repository.

You can create three types of repositories:

Those that reference content available on another server, for example, on a mirror you maintain (url).
Those where Razor unpacks ISOs for you and serves their contents (iso_url).
Those where Razor creates a stub directory that you can manually fill with content (no_content).

The task parameter is mandatory in all three variants of this command, and indicates the default task that should be used when installing machines using this repository. The task parameter can be overridden at the policy level. If you’re not using a task, reference the stock task noop.

To have Razor unpack an ISO for you and serve its content:

{
  "name": "fedora19",
  "iso_url": "file:///tmp/Fedora-19-x86_64-DVD.iso"
  "task": "puppet"
}

Tip: Supplying the iso_url property when you create a repository ensures that you can delete it from the server with the delete-repo command.

To create a repository that points to an existing resource without loading anything onto the Razor server:

{
  "name": "fedora19",
  "url": "http://mirrors.n-ix.net/fedora/linux/releases/19/Fedora/x86_64/os/"
  "task": "noop"
}

To create an empty directory in the repo_store_root which you can manually fill later:

{
  "name": "win2012r2",
  "no_content": true
  "task": "noop"
}

After a no_content repository is created, you can log into your Razor server and fill the directory $repo_store_root/$repo_name with the actual content for the repository, for example by loopback mounting the install media and copying it into the repository’s directory.

Using no_content is usually required for Windows install media, because the library that Razor uses to unpack ISO images can’t handle Windows ISO images.

Delete a repository (`delete-repo`)

The delete-repo command accepts a single repository name:

{
  "name": "fedora16"
}

This command deletes the repository from Razor’s internal database. If you supplied the iso_url property when you created the repository, the folder is also deleted from the server. If you didn’t supply the iso_url property, content remains in the repo_store_root/<REPONAME> directory.

Update a repository’s specified task (`update-repo-task`)

Ensures that a specified repository uses the task this command specifies, setting the task if necessary. If a node is currently provisioning against the repo when you run this command, provisioning might fail.

{
  "repo": "my_repo",
  "task": "other_task"
}

Tasks

Create task (`create-task`)

The create-task command creates a task in the Razor database. This command is an alternative to manually placing task files in the task_path. If you anticipate needing to make changes to tasks, we recommend the disk-backed task approach.

The body of the POST request for this command has the following form:

{
  "name": "redhat6",
  "os": "Red Hat Enterprise Linux",
  "boot_seq": {
    "1": "boot_install",
    "default": "boot_local"
  },
  "templates": {
    "boot_install": " ... ERB template for an ipxe boot file ...",
    "installer": " ... another ERB template ..."
  }
}

The possible properties in the request are:

name: The name of the task; must be unique.
os: The name of the OS; mandatory.
description: Human-readable description.
boot_seq: A hash mapping the boot counter or ‘default’ to an ERB template.
templates: A hash mapping template names to the actual ERB template text.

Policies

Policies govern how nodes are provisioned depending on how they are tagged. Razor maintains an ordered table of policies. When a node boots, Razor traverses this table to find the first eligible policy for that node. A policy might be ineligible for binding to a node if the node does not contain all of the tags on the policy, if the policy is disabled, or if the policy has reached its maximum for the number of allowed nodes.

When you list the policies collection, the list is in the order in which Razor checks policies against nodes.

Create policy (`create-policy`)

{
  "name": "a policy",
  "repo": "some_repo",
  "task": "redhat6",
  "broker": "puppet",
  "hostname": "host${id}.example.com",
  "root_password": "secret",
  "max_count": 20,
  "before"|"after": "other policy",
  "node_metadata": { "key1": "value1", "key2": "value2" },
  "tags": ["existing_tag", "another_tag"]
}

Note: Because the policy contains many fields, you might want to put it in a JSON file. If you do, then your create-policy command would include the file name, like this: razor create-policy --json <name of policy file>.json.

Tags, repos, tasks, and brokers are referenced by name. The tags are optional. A policy with no tags can be applied to a node. The task is also optional. If it is omitted, the repo’s task is used. The repo and broker entries are required.

The hostname parameter defines a simple pattern for the hostnames of nodes bound to your policy. The “${id}” references each node’s DB id.

The max_count parameter sets an upper limit on how many nodes can be bound to your policy at a time. You can specify a positive integer, or make it unlimited by setting it to nil.

Razor considers each policy sequentially, based on its order in a table. By default, new policies go at the end of the table. To override the default order, include a before or after argument referencing an existing policy by name.

The node_metadata parameter lets your policy apply metadata to a node when it binds. This does not overwrite existing metadata; it only adds keys that are missing.

Move policy (`move-policy`)

This command lets you change the order in which razor considers your policies for matching against nodes. To move an existing policy into a different place in the order, use the move-policy command with a body like:

{
  "name": "a policy",
  "before"|"after": "other policy"
}

This changes the policy table so that a policy appears before or after other policy.

Enable/disable policy (`enable-policy`/`disable-policy`)

To keep a policy from being matched against any nodes, disable it with the disable-policy command. To enable a disabled policy, use the enable-policy command. Both commands use a body like:

{
  "name": "a policy"
}

Modify the max_count for a policy (`modify-policy-max-count`)

The command modify-policy-max-count lets you set the maximum number of nodes that can be bound to a specific policy. The body of the request should be of the form:

{
  "name": "a policy"
  "max_count": new-count
}

new-count can be an integer, which must be greater than the number of nodes that are currently bound to the policy. Alternatively, the no_max_count argument makes the policy unbounded:

{
  "name": "a policy"
  "no_max_count": true
}

Add tags to policy (`add-policy-tag`)

To add tags to a policy, supply the name of a policy and of the tag:

{
  "name": "a-policy-name",
  "tag" : "a-tag-name",
}

To create the tag in addition to adding it to the policy, supply the rule argument:

{
  "name": "a-policy-name",
  "tag" : "a-new-tag-name",
  "rule": "new-match-expression"
}

Remove tags from policy (`remove-policy-tag`)

To remove tags from a policy, supply the name of a policy and the name of the tag.

{
  "name": "a-policy-name",
  "tag" : "a-tag-name",
}

A policy with no tags can still be applied to any node.

Update a policy’s specified task (`update-policy-task`)

Ensures that a policy uses the task this command specifies. If necessary, update-policy-task sets the task, for example if a policy has already been created and you want to add a task to it. Note that if a node is currently provisioning against the policy when you run this command, provisioning can fail.

The following shows how to update a policy’s task to a task called “other_task”.

{
  "node": "node1",
  "policy": "my_policy",
  "task": "other_task"
}

Delete policy (`delete-policy`)

To delete a policy, supply the name of a single policy:

{
  "name": "my-policy"
}

Note that this does not affect the installed status of a node, and therefore can’t, by itself, make a node bind to another policy upon reboot.

Brokers

A broker is responsible for configuring a newly installed node for a specific configuration management system. For Puppet Enterprise, you will generally only use brokers with the type puppet-pe.

Create broker (`create-broker`)

To create a broker, post the following to the create-broker URL:

{
  "name": "puppet",
  "configuration": {
     "server": "puppet.example.org"
  },
  "broker-type": "puppet-pe"
}

The broker-type must correspond to a broker that is present on the broker_path set in config.yaml.

The permissible settings for the configuration hash depend on the broker type and are declared in the broker type’s configuration.yaml. For the puppet-pe broker type, these are:

server: The hostname of the Puppet Master
version: The agent version to install; this defaults to current and should only be used in exceptional circumstances
windows_download_url: The download URL for a Windows PE agent installer; defaults to a URL derived from the version config. This should only be used in exceptional circumstances

Update broker configuration (`update-broker-configuration`)

To set or clear a specified key value for a broker, use update-broker-configuration. This argument changes the key some_key to new_value:

{
  "broker": "mybroker",
  "key": "some_key",
  "value": "new_value"
}

This argument clears the value for some_key:

{
  "broker": "mybroker",
  "key": "some_key",
  "clear": true
}

The update-broker-configuration command can be useful to update the PE version of a puppet-pe broker. For example, if you created a puppet-pe broker for version 2015.2.0, you can update it with:

{
  "broker": "puppet-pe",
  "key": "version",
  "value": "2015.3.0"
}

Delete broker (`delete-broker`)

The delete-broker command only requires the name of the broker:

{
  "name": "small",
}

It is not possible to delete a broker as long as it is used by a policy.

Hooks

Create hook (`create-hook`)

To create a new hook, use the create-hook command with a body like this:

{
  "name": "myhook",
  "hook_type": "some_hook",
  "configuration": {"foo": 7, "bar": "rhubarb"}
}

The hook_type parameter refers to a directory with name some_hook.hook on the Razor server’s hook_path.

The optional configuration parameter lets you provide a starting configuration corresponding to that hook_type.

For more on hooks, see Hooks.

Update hook configuration (`update-hook-configuration`)

To set or clear a specified key value for a hook, use update-hook-configuration. This argument changes the key some_key to new_value:

{
  "hook": "myhook",
  "key": "some_key",
  "value": "new_value"
}

This argument clears the value for some_key:

{
  "hook": "myhook",
  "key": "some_key",
  "clear": true
}

Delete hook (`delete-hook`)

To delete a single hook, provide its name:

{
  "name": "my-hook"
}

↑ Back to top

API reference

The default bootstrap iPXE file

Nodes

Register a node (register-node)

Set node hardware info (set-node-hw-info)

Delete node (delete-node)

Reinstall node (reinstall-node)

Intelligent Platform Management Interface

Set node IPMI credentials (set-node-ipmi-credentials)

Reboot node (reboot-node)

Set a node’s desired power state (set-node-desired-power-state)

Node metadata

Modify node metadata (modify-node-metadata)

Update node metadata (update-node-metadata)

Remove node metadata (remove-node-metadata)

Repositories

Create new repository (create-repo)

Delete a repository (delete-repo)

Update a repository’s specified task (update-repo-task)

Tasks

Create task (create-task)

Tags

Create tag (create-tag)

Delete tag (delete-tag)

Update tag (update-tag-rule)

Policies

Create policy (create-policy)

Move policy (move-policy)

Enable/disable policy (enable-policy/disable-policy)

Modify the max_count for a policy (modify-policy-max-count)

Add tags to policy (add-policy-tag)

Remove tags from policy (remove-policy-tag)

Update a policy’s specified task (update-policy-task)

Delete policy (delete-policy)