Razor API reference

View configuration (config)

The config endpoint displays details about your Razor configuration.

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 the purview of Razor, this command offers a way to tell Razor that a node is valuable and not eligible for automatic reprovisioning. Such nodes are reprovisioned only 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 to ignore the node and 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 is considered installed and therefore not eligible for reprovisioning by Razor

API example

Registering a machine before booting it with installed set to true protects 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.

Delete node (delete-node)

To remove a single node, provide its name:

{
  "name": "node17"
}

Reinstall node (reinstall-node)

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

{
  "name": "node17"
}

After 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.

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 must 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 works only 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 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.

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 clear 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
}

or

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

You can submit multiple updates or removals 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 is not 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",
}

or

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

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.

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.

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

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

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

After creating a no_content repository, you can log into your Razor server and fill the repository directory with the content, for example by loopback-mounting the install media and copying it into the directory. The repository directory is specified by the repo_store_root class parameter of the pe_razor class. By default, the directory is in /opt/puppetlabs/server/data/razor_server/repo.

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 deletes a repository from the internal Razor database.

The command accepts a single repository name:

{
  "name": "fedora16"
}

This command deletes the repository from the internal Razor 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 repository directory.

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

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

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.

{
  "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 ..."
  }
}

Create tag (create-tag)

{
  "name": "small",
  "rule": ["=", ["fact", "processorcount"], "2"]
}

Delete tag (delete-tag)

{
  "name": "small",
  "force": true
}

Update tag (update-tag-rule)

{
  "name": "small",
  "rule": ["<=", ["fact", "processorcount"], "2"],
  "force": true
}

This changes the rule of the given tag to the new rule. Razor then reevaluates the tag against all nodes and updates each node's tag attribute to reflect whether the tag now matches or not.

If the tag is used by any policies, the update is performed only if you set the optional force parameter to true. Otherwise, the command returns status code 400.

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"]
}

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. To install Windows on non-English systems, specify the win_language using the culture code for the appropriate Microsoft language pack). For example, --node-metadata win_language=es-ES.

Move policy (move-policy)

This command lets you change the order in which Razor considers your policies for matching against nodes.

{
  "name": "a policy",
  "before"|"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.

{
  "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.

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

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

Add tags to policy (add-policy-tag)

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

{
  "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",
}

Update a policy's specified repository (update-policy-repo)

Ensures that a policy uses the repository this command specifies. If necessary, update-policy-repo sets the repository, for example if a policy has already been created and you want to add a repository to it.

{
  "node": "node1",
  "policy": "my_policy",
  "repo": "fedora21"
}

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.

If a node is currently provisioning against the policy when you run this command, provisioning can fail.

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

Update a policy's specified broker (update-policy-broker)

Ensures that a policy uses the broker this command specifies. If necessary, update-policy-broker sets the broker, for example if a policy has already been created and you want to add a broker to it.

If a node is currently provisioning against the policy when you run this command, provisioning can fail.

{
  "node": "node1",
  "policy": "my_policy",
  "broker": "legacy-puppet"
}

Update a policy's node metadata (update-policy-node-metadata)

Ensures that a policy uses the node metadata this command specifies. If necessary, update-policy-node-metadata sets the node metadata, for example if a policy has already been created and you want to add node metadata to it.

{
  "node": "node1",
  "policy": "my_policy",
  "key": "my_key"
  "value": "my_value"
}

Delete policy (delete-policy)

{
  "name": "my-policy"
}

Create broker (create-broker)

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

The broker-type must correspond to a broker that is present in a valid broker directory. Broker directories are specified in the broker_path class parameter of the pe_razor class. By default, the broker path for custom brokers is /etc/puppetlabs/razor-server/brokers:brokers.

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 master.
• version — The agent version to install; this defaults to current and must be used only in exceptional circumstances.
• ntpdate_server — URL for an NTP server, such as us.pool.ntp.org, used to synchronize the date and time before installing the agent.

Update broker configuration (update-broker-configuration)

To set or clear a specified key value for a broker, use update-broker-configuration.

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

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

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

Delete broker (delete-broker)

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

{
  "name": "small",
}

Hooks can be useful for:

• Notifying an external system about the stage of a node’s installation.
• Querying external systems for information that modifies how a node gets installed.
• Calculating complex values for use in a node’s installation configuration.

Create hook (create-hook)

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

The hook_type must correspond to a hook with the specified name in a valid hook directory. Hook directories are specified in the hook_path class parameter of the pe_razor class. By default, the hook directory for custom hooks is /etc/puppetlabs/razor-server/hooks:hooks.

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

Update hook configuration (update-hook-configuration)

To set or clear a specified key value for a hook, use update-hook-configuration.

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

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

Delete hook (delete-hook)

{
  "name": "my-hook"
}