Skip to content
This repository has been archived by the owner on Jun 4, 2021. It is now read-only.

Getting started

Jump to bottom
ticktockhouse edited this page Jul 30, 2018 · 37 revisions

This page explains the most important commands for getting started. We assume that you have a Razor server up and running. If not, go to Installation).

Note: When you run Razor commands, you might get this warning: "MultiJson is using the default adapter (ok_json). We recommend loading a different JSON library to improve performance."

This situation is completely harmless. However, if you are using Ruby 1.8.7, you can install a separate JSON library (such as gem install json_pure) to make the warning go away.

Installing the Command Line Client

The command line client is a small utility that makes interacting with the Razor server's REST API more convenient. Because the server and the client only communicate over HTTP, there is no need to run the client on the same machine as the server; in fact, running the client locally is generally preferable.

The client requires that a version of Ruby compatible with Ruby 1.9.3 is installed. Unlike the Razor server, the client doesn't have to run under jRuby. Using a Ruby interpreter with a faster startup time, like MRI Ruby, is usually more convenient.

The client is distributed as a gem and can be installed with this command:

gem install razor-client

You can point the client at the Razor server in two ways, both of which list all the nodes on the server http://razor:8150/api. You can specify the server's API URL with the --url option:

razor --url http://razor:8150/api nodes

Or you can set the RAZOR_API environment variable:

RAZOR_API=http://razor:8150/api razor nodes

Creating Basic Objects

To use Razor, you need to create repos, brokers, tags, and policies on the server.

Create Repo

Start by loading at least one repo into the server:

razor create-repo --name=centos-6.4 --iso-url http://some.where/centos.iso --task centos

All the objects you use with Razor are identified by a name, which has to be unique (i.e., there can only be one repo called 'sles-11') The repo contains the actual bits that are used when installing a node; the installation instructions are contained in tasks. Razor comes with a few predefined tasks to get you started. They can be found in the tasks/ directory in the razor-server repo, and can all be used by simply mentioning their name in a policy. This is described below, and includes the vmware_esxi installer; the one exception to this is the Windows installer, which requires additional preparation.

Create Broker

Besides repos and tasks, you'll also need a broker; brokers are responsible for handing a node off to a config management system, usually Puppet. The following sets up a simple noop broker that does nothing:

razor create-broker --name=noop --broker-type=noop

In order to pass configuration to the broker you need to supply the configuration option, which can be done through the --configuration command line option. You must pass a JSON object, containing the key/value pairs to be passed through to the broker type.

Create Tag

Tags are used to label nodes that meet certain criteria. Tags can be referenced from policies. The following command will apply the tag "small" to all nodes with 2 or fewer processors:

razor create-tag --name small --rule '["<=", ["num", ["fact", "processorcount"]], 2]'

Create Policy

After a broker is set up, you can create a policy. Policies tie all the other bits and pieces in Razor together, and are ultimately applied to a host. Since a command line to create a policy would be quite a mouthful, store the policy in a JSON file, something like policy.json:

{
  "name": "centos-for-small",
  "repo": "centos-6.4",
  "task": "centos",
  "broker": "noop",
  "enabled": true,
  "hostname": "host${id}.example.com",
  "root_password": "secret",
  "max_count": 20,
  "tags": ["small"]
}

Then, create the policy on the server:

razor create-policy --json policy.json

With this example policy, the first 20 nodes that have no more than two processors that boot will get the centos-for-small policy applied to them.

Investigating What's on Your Server

Running razor nodes will produce a list of all the nodes that the Razor server knows about. The list looks something like this:

+--------+----------------------+------------+---------+
| name   | dhcp_mac             | tags       | policy  |
+--------+----------------------+------------+---------+
| node42 | 01-52-54-00-0d-97-f0 | (none)     | ...     |
|            ... more nodes ...                        |
+--------+----------------------+------------+---------+

Query an entry by including its name, e.g. `razor nodes node42`

The name of the node is generated by the server and follows the pattern nodeNNN where NNN is an integer. You can use the name with the razor nodes command to get more information about the node, like this: razor nodes node42.

             id: "http://razor:8150/api/collections/nodes/node42"
           name: "node42"
           spec: "http://api.puppetlabs.com/razor/v1/collections/nodes/member"
        hw_info:
                  mac: ["01-52-54-00-0d-97-f0"]
                 uuid: "ea7c46f8-615f-234f-c1a4-20f0d3edac3d"

       dhcp_mac: "01-52-54-00-0d-97-f0"
         policy: ...
            log:
                 log => http://razor:8150/api/collections/nodes/node42/log
          facts:
                             architecture: "x86_64"
                     blockdevice_vda_size: 4294967296
                   blockdevice_vda_vendor: "0x1af4"
...

It is possible to navigate further into related objects, for example, razor nodes node42 log displays the log of that node:

+---------------------------+--------+-------------+----------+-------------+----------+---------+--------+
| timestamp                 | event  | task        | template | repo        | severity | policy  | action |
+---------------------------+--------+-------------+----------+-------------+----------+---------+--------+
| 2013-11-21T16:49:11+01:00 | boot   | microkernel | boot     | microkernel | info     |         |        |
| 2013-11-21T16:49:45+01:00 | bind   |             |          |             | info     | centos6 |        |
| 2013-11-21T16:49:45+01:00 |        |             |          |             | info     | centos6 | reboot |
| 2013-11-21T16:50:16+01:00 | unbind |             |          |             | info     | centos6 |        |
+---------------------------+--------+-------------+----------+-------------+----------+---------+--------+

Browsing Other Objects

For any of the collections that Razor supports, you can use razor <collection> to get a list of a specific collection, and razor <collection name> to get the details of an object in that collection. Running razor -h will list all the collections the server knows about.

For example, razor tags lists all tags, and razor tags test shows the details of the tag with name test.

Clone this wiki locally