Machine¶
The machine object defines a machine that is being provisioned. The machine is represented by a unique UUID. The UUID is immutable after machine creation. The machine's primary purpose is to map an incoming IP address to a bootenv. The bootenv object provides a set of rendered templates that will be used to boot the machine. The machine provides parameters to the templates. The machine provides configuration to the renderer in the form of parameters and fields. Also, each machine must have a bootenv to boot from. If a machine is created without a bootenv specified, DRP will use the value of the defaultBootEnv preference.
Machines are what DRP uses to model a system as it goes through the various stages of the provisioning process. As such, machine objects have many fields used for different tasks.
Fields¶
| Field | Definition |
|---|---|
| Address | The IPv4 address of the machine that should be used for PXE purposes. Note that this field does not directly tie into DHCP leases or reservations -- the provisioner relies solely on this address when determining what to render for a specific machine. Address is updated automatically by the DHCP system if HardwareAddrs is filled out. swagger:strfmt ipv4 |
| Arch | Arch is the machine architecture. It should be an arch that can be fed into $GOARCH. required: true |
| BootEnv | The boot environment that the machine should boot into. This must be the name of a boot environment present in the backend. If this field is not present or blank, the global default bootenv will be used instead. |
| Context | Contexts contains the name of the current execution context. An empty string indicates that an agent running on a Machine should be executing tasks, and any other value means that an agent running with its context set for this value should be executing tasks. |
| CurrentTask | The index into the Tasks list for the task that is currently running (if a task is running) or the next task that will run (if no task is currently running). If -1, then the first task will run next, and if it is equal to the length of the Tasks list then all the tasks have finished running. required: true |
| Description | Description is a string for providing a simple description |
| Fingerprint/CSNHash | DMI.System.Manufacturer + DMI.System.ProductName + DMI.Chassis[0].SerialNumber, SHA256 hashed Hash must not be zero-length to match. 25 points |
| Fingerprint/CloudInstanceID | Cloud-init file in /run/cloud-init/instance-data.json String from ID of '.v1.cloud_name' + '.v1.instance_id'. 500 point match |
| Fingerprint/MemoryIds | MemoryIds is an array of SHA256sums if the following fields in each entry of the DMI.Memory.Devices array concatenated together: * Manufacturer * PartNumber * SerialNumber Each hash must not be zero length Score is % matched. |
| Fingerprint/SSNHash | DMI.System.Manufacturer + DMI.System.ProductName + DMI.System.SerialNumber, SHA256 hashed Hash must not be zero-length to match. 25 points |
| Fingerprint/SystemUUID | DMI.System.UUID, not hashed. Must be non zero length and must be a non-zero UUID. 50 point match |
| HardwareAddrs | HardwareAddrs is a list of MAC addresses we expect that the system might boot from. This must be filled out to enable MAC address based booting from the various bootenvs, and must be updated if the MAC addresses for a system change for whatever reason. |
| JobExitState | The final disposition of the current job. Can be one of "reboot","poweroff","stop", or "complete" Other substates may be added as time goes on |
| JobResultErrors | ResultErrors is a list of error from the task. This is filled in by the task if it is written to do so. This tracks results without requiring job logs. |
| JobState | The state the current job is in. Must be one of "created", "failed", "finished", "incomplete" |
| Locked | Locked indicates that changes to the Machine by users are not allowed, except for unlocking the machine, which will always generate an Audit event. required: true |
| Meta | Meta contains the meta data of the object. The type of this field is a key / value map/dictionary. The key type is string. The value type is also string. The general content of the field is undefined and can be an arbritary store. There are some common known keys: color - The color the UX uses when displaying icon - The icon the UX uses when displaying * title - The UX uses this for additional display information. Often the source of the object. Specific Object types use additional meta data fields. These are described at: https://docs.rackn.io/stable/redirect/?ref=rs_object_metadata |
| Name | The name of the machine. This must be unique across all machines, and by convention it is the FQDN of the machine, although nothing enforces that. required: true swagger:strfmt hostname |
| OS | OS is the operating system that the node is running in. It is updated by Sledgehammer and by the various OS install tasks. |
| Params | Params holds the values of parameters on the object. The field is a key / value store of the parameters. The key is the name of a parameter. The key is of type string. The value is the value of the parameter. The type of the value is defined by the parameter object. If the key doesn't reference a parameter, the type of the object can be anything. The system will enforce the named parameter's value's type. Go calls the "anything" parameters as "interface {}". Hence, the type of this field is a map[string]interface{}. |
| Pool | Pool contains the pool the machine is in. Unset machines will join the default Pool |
| PoolStatus | PoolStatus contains the status of this machine in the Pool. Values are defined in Pool.PoolStatuses |
| Profiles | Profiles is an array of profiles to apply to this object in order when looking for a parameter during rendering. |
| Runnable | Runnable indicates that this is Runnable. |
| Secret | Secret for machine token revocation. Changing the secret will invalidate all existing tokens for this machine |
| Stage | The stage that this is currently in. |
| TaskErrorStacks | This list of previous task lists and current tasks to handle errors. Upon completing the list, the previous task list will be executed. This will be capped to a depth of 1. Error failures can not be handled. |
| TaskErrorStacks/CurrentJob | CurrentJob is the job that presents this task stack swagger:strfmt uuid |
| TaskErrorStacks/CurrentTask | CurrentTask is the index in the task list in a previous errored task. |
| TaskErrorStacks/TaskList | TaskList is the task list from a previous errored task. |
| Tasks | The current tasks that are being processed. |
| Uuid | The UUID of the machine. This is auto-created at Create time, and cannot change afterwards. required: true swagger:strfmt uuid |
| WorkOrderMode | WorkOrderMode indicates if the machine is action mode |
| Workflow | Workflow is the workflow that is currently responsible for processing machine tasks. required: true |
The Name field should contain the FQDN of the node.
The machine object contains an Error field that represents errors encountered while operating on the machine. In general, these are errors pertaining to rendering the bootenv.
Machine parameters are defined as a special profile on the machine. The profile stores a dictionary of string keys to arbitrary objects. These could be strings, booleans, numbers, arrays, or objects representing similarly defined dictionaries. The machine parameters are available to templates for expansion.
Machines maintain an ordered list of profiles that are searched in that order, with the global profile searched last.
Note
When updating the params part of the embedded profile in the machine object, using the PUT method will replace the params map with the map from the input object. The PATCH API method will merge the params map in the input with the existing params map in the current machine object. The POST method on the params subaction will replace the map with the input version.
A machine is defined by having the meta data field machine-role set to machine or self. For backwards compatability, a machine without a machine-role meta data entry is considered a machine.
Job Monitoring¶
To get Websocket events for jobs for a specific machine, the machine_jobs.*.<uuid> register can be used.