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.

Field	Definition
Name	A user-chosen name for the machine. It must be unique, although it can be updated at any point via the API. It is a good idea for the field to be the same as the FQDN of the machine in DNS, although nothing enforces that convention.
Uuid	A randomly-chosen v4 UUID that uniquely identifies the machine. It cannot be changed, and it what everything else in DRP will use to refer to a machine.
Address	The IPv4 address that third-party systems should expect to be able to use to access the machine. DRP does not manage this field. This does not have to be the same as an existing lease or reservation.
BootEnv	The boot environment the machine should PXE boot to the next time it reboots. When you change the bootenv field on a machine or change the bootenv that a machine wants to use, all relavent templates on the provisioner side are rerendered to reflect the updates. This field is read-only if the Workflow field is set.
Params	A map containing parameter names and their associated values. Params set directly on a machine override params from any other source when templates using those params are rendered.
Profiles	An ordered list of profile names that the template render process will use to look up values for params. At render time, profiles on a machine are looked at in the order that they appear in this list, and the first one that is found wins (assuming the param in question is not provided directly on the machine).
OS	The operating system that the machine is running. It is only set by DRP when the machine is moved into a bootenv that has -install in the name.
Secret	A random string used when generating auth tokens for this machine. Changing this field will invalidate any existing auth tokens for this machine.
Runnable	A flag that indicates whether the machine agent is allowed to create and execute jobs against this machine.
Locked	A flag that indicates whether user-initiated changes to a machine will be accepted. When true, any changes that do not include change that sets this flag to false will be rejected. Changes from non-user sources will still be accepted. This includes changes made while running tasks on a machine.
Workflow	The name of the workflow that the machine is going through. If the Workflow field is not empty, the Stage andBootEnv fields are read-only.
Tasks	The list of tasks that the machine should run or that have run. You can add and remove tasks from this list as long as they have not already run, they are not the current running task, or they are beyond the next stage transition present in the tasks list.
CurrentTask	The index in tasks of the current running task. A CurrentTask of -1 indicates that none of the tasks in the current tasks list have run, and a current task that is equal to the length of the tasks list indicates that all of the tasks have run. The machine agent always creates jobs based on the current task. If the Workflow field is non-empty, setting this field to -1 will instead set this field to the most recent stage in the tasks list that did not initiate a bootenv change.
CurrentJob	The UUID of the job that is currently running.
Stage	The current stage the machine is in. Changing the stage of a machine has the following effects: If the new stage has a new bootenv, the machine's Runnable flag will be set to false and the bootenv on the machine will change. If the machine's Workflow field is empty, the machine's tasks list will be replaced by the task list from the new Stage, and CurrentTask will be set back to -1. The Stage field is read-only when the Workflow field is non-empty.
Context	The name of the context that tasks for the machine should execute in. When this field is the empty string (""), then the agent running on the machine itself is the one that should be running tasks. The Context field on a machine can be set either via a machine PATCH or PUT, or as a side effect of processing an entry in the tasks list in the format of 'context:<new-context>'. When the tasks list on a machine is replaced as a side effect of a workflow or stage change, the Context field of the machine will be reset to the value of the BaseContext meta field on the machine, or to the empty ("") string if that meta field is not present on the machine.
WorkflowComplete	A flag on the machine to indicate if all the tasks are complete. If the task list has been fully executed, this flag will set to true. If the on-complete-delete parameter is set to true, the machine will be deleted when this field becomes true. Machines can alter their delete operation by setting the following parameter, on-delete-workflow. Setting a workflow into this parameter will cause the machine to run that workflow when it is deleted. Using this parameter, will set the on-complete-delete parameter to cause the machine to be deleted once this workflow completes. The on-delete-workflow and on-complete-delete parameters can work together to generate a usage that will finished the current workflow (assuming it is different than the on-delete-workflow) then run the on-delete-workflow workflow to completion, and then actually remove the machine.
JobState	The state the current job is in.
JobExitState	The final disposition of the current job.
JobResultErrors	A copy of the current job's ResultErrors field, created when the job finishes or fails.

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.