Machine¶
The Machine is the central model in Digital Rebar Provision. It represents a bare-metal or virtual system managed by DRP, identified by a unique immutable UUID assigned at creation time. The machine's primary purpose is to map an incoming IP address to a BootEnv that provides rendered templates for booting and configuring the system.
Machines operate in two execution modes. In Workflow mode, DRP drives the machine through a provisioning pipeline: a Workflow sets the Stage and Tasks list, and the machine agent requests Job objects to execute each task in sequence. In WorkOrder mode, the machine has completed initial provisioning and accepts WorkOrder objects for post-provisioning operations such as configuration changes, maintenance actions, and CI/CD tasks. The WorkOrderMode field controls which mode is active.
Each machine maintains an ordered list of Profile references that form a parameter inheritance chain. When resolving a parameter value, DRP searches the machine's own embedded parameters first, then each profile in list order, and finally the global profile. This layered approach allows shared configuration through profiles while permitting per-machine overrides.
The HardwareAddrs field holds MAC addresses used for PXE boot identification, and the Address field tracks the IPv4 address for provisioning (automatically updated by DHCP when hardware addresses are present). The Arch field specifies the system architecture (amd64, arm64, and others) and determines which boot environment artifacts are served. The Fingerprint field contains DMI-based identification data (system serial number hashes, chassis serial number hashes, memory module identifiers, and cloud instance IDs) used to match and re-identify machines across reboots.
Machines can belong to a Pool Object for lifecycle management, where they transition through states such as Joining, Free, InUse, and Leaving. The Pool and PoolStatus fields track this membership. The Locked field prevents unauthorized modifications, and the Secret field controls token revocation for machine authentication.
A machine is defined by having the Meta field machine-role set to machine or self. For backwards compatibility, a machine without a machine-role metadata entry is considered a machine. Related machine-like models include Cluster and Resource Broker, which share the same underlying structure but serve different roles.
Metadata¶
| Field | Description | Value |
|---|---|---|
BaseContext: [context] |
Lets DRP know what the base context is for the machine when going back to a known context. | |
machine-role: [role] |
Set by DRP and should not be edited. It lets DRP know what the type of machine this object is. | self, machine, cluster, or resource-broker |
pipeline |
the name of the executed pipeline and set by DRP during pipeline execution to allow operators to trace jobs across a pipeline run. | |
pipeline-uuid |
A unique ID for each executed pipeline and set by DRP during pipeline execution to allow operators to trace jobs across a pipeline run. |
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. |
| 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. read only: 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 swagger:strfmt byte |
| 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 swagger:strfmt byte |
| 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. |
| 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. 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. |
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.
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.
Job Monitoring¶
To get Websocket events for jobs for a specific machine, the machine_jobs.*.<uuid> register can be used.
Purge all Jobs for a Machine¶
To purge all Jobs for a Machine, make use of the drpcli jobs purge command:
Explanation of command:
| Flag | Explanation |
|---|---|
--machine UUID |
replace UUID with the UUID of the machine you'd like to purge jobs from |
--jobs-to-keep 0 |
do not retain any recent jobs from the purge |
--complete-after 0s |
includes jobs that are marked as completed and are older than 0s |
--fail-after 0s |
includes jobs that are marked as failed and are older than 0s |
Effectively, this command removes all completed/failed jobs for a given machine by its UUID.
Adjust the time flags (0s) to preserve recent jobs if necessary.