Update a node

PUT api/nodes/hostname

Updates the details of an existing node.

When updating an IP address value, you must specify both the IP address and netmask value. If no netmask value is specified, a default value of /32 is used even if an existing netmask value exists.

Request syntax

put api/nodes/<hostname> '{"<parameter>": <value>, "properties": {"my_<property_name>": "<value>"}}'

Request parameters

The request accepts the following data in JSON format. All parameters are optional. Include only the parameters you want to change.

Parameter	Type	Description	Required	Default value
`node_name`	String	The name of the node.	No	N/A
`node_group_id`	Integer	The ID of the node group to move the node to.	No	N/A
`store_number`	Integer	The store number to associate the node with. This corresponds to the `Node Number` value in SC//Reliant™ Platform Manager.	No	N/A
`instance_number`	Integer	The node instance number.	No	N/A
`serialno`	String	The serial number of the physical host of the node. The value is saved in lowercase.	No	N/A
`properties`	Object	A hash of dynamic properties to set on the node, keyed by property template name with the `my_` prefix (for example, `{"my_lan1_ip": "1.2.3.6"}`). A property must exist in the node group's node properties for its value to be saved.	No	N/A
`puppet_masterless`	Boolean	Whether or not to run Puppet in `masterless` mode.	No	`false`
`puppet_environment`	String	The branch that is used for Puppet agent runs. If no value is specified, the default value of `Production` is used.	No	`null`

Response syntax

{
    "exporter_job": integer,
    "id": integer,
    "installation_token": {
        "uuid": "string",
        "state": "string",
        "expires_at": "timestamp"
    },
    "node_name": "string",
    "node_group_id": integer,
    "store_number": integer,
    "instance_number": integer,
    "hostname": "string",
    "serialno": "string",
    "virtual": boolean,
    "type_of_server": "string",
    "hierarchy_field_id": "string",
    "status": "string",
    "keepalive_timestamp": integer,
    "last_online": "string",
    "created_at": timestamp,
    "updated_at": timestamp,
    "virtual_nodes": [
    ],
    "puppet_masterless": boolean,
    "puppet_environment": "string",
    "properties": {
        "my_property1": "value1",
        "my_property2": {
            "nested_property1": "nested_value1"
        }
    },
    "service_checks": {
        "docker_versions": [
        ]
    },
    "available_docker_images": {
        "images": [
            {
            "ID": "string",
            "Tag": "string",
            "Size": "string",
            "Digest": "string",
            "CreatedAt": "string",
            "Containers": "string",
            "Repository": "string",
            "SharedSize": "string",
            "UniqueSize": "string",
            "VirtualSize": "string",
            "CreatedSince": "string"
            }
        ],
        "last_checked": timestamp
    }
}

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

The API returns HTTP 200 even when a property value isn't saved, for example when the property doesn't exist in the node group's node properties. Check the properties and updated_at values in the response to confirm the change was made.

Field	Type	Description
`exporter_job`	Integer	The ID of the job that exports the node's updated configuration. Returned only when the update changes the node.
`id`	Integer	The ID of the node.
`installation_token`	Object	The details about the installation token.
`node_name`	String	The name of the node. Returns `null` if no name is set.
`node_group_id`	Integer	The ID of the node group the node belongs to.
`store_number`	Integer	The store number associated with the node. This corresponds to the `Node Number` value in SC//Reliant Platform Manager.
`instance_number`	Integer	The instance number associated with the node.
`hostname`	String	The hostname of the node.
`serialno`	String	The serial number of the physical host of the node, in lowercase.
`virtual`	Boolean	Whether or not the node is a virtual node.
`type_of_server`	String	The server type of the node. If no type is associated, this returns a `null` value.
`hierarchy_field_id`	Integer	The ID associated with the level of hierarchy field.
`status`	String	The current status of the node.
`keepalive_timestamp`	Integer	The UNIX epoch timestamp of the last keepalive transmission.
`last_online`	String	The timestamp of the last time the node was confirmed online, or `unknown` if the node has not checked in.
`created_at`	Timestamp	The timestamp indicating when the node was created in SC//Reliant Platform Manager.
`updated_at`	Timestamp	The timestamp indicating when the node was last updated in SC//Reliant Platform Manager.
`virtual_nodes`	String array	The details of the virtual nodes associated with the node.
`puppet_environment`	String	The branch that is used for Puppet agent runs. If no value is specified, the default value of `Production` is used.
`puppet_masterless`	Boolean	Whether or not Puppet is run in `masterless` mode.
`properties`	String array	The system and dynamic properties associated with the node.
`service_checks`	String array	The details of the last service checks run on the node.
`available_docker_images`	String array	The Docker images available on the node. This is similar to running a `docker images` command on the node.

Errors

The following are common errors returned by this API.

Code	Message	Cause
`404`	`Not found`	No node exists with the specified hostname.
`404`	`NodeGroup not found!`	The `node_group_id` value doesn't match an existing node group.
`422`	`Validation Failed: node_group_id Invalid node group! Trying to assign a Virtual group to a Regular node`	The specified node group is a virtual node group, and the node is a regular node.

Examples

Example 1: Update a system property on a node

This example updates the serialno system property value on node sit0000red1.

ruby api.rb <customer_code> put api/nodes/sit0000red1 '{"serialno": "s147EXAMPLE"}'

Response

{
    "exporter_job": 1544778,
    "id": 119996,
    "installation_token": {
        "uuid": "fb30d03e-4cd5-422a-8714-EXAMPLE",
        "state": "active",
        "expires_at": null
    },
    "node_name": "sit0000red1",
    "node_group_id": 0000,
    "store_number": 0000,
    "instance_number": 1,
    "hostname": "sit0000red1",
    "serialno": "s147EXAMPLE",
    "virtual": false,
    "type_of_server": null,
    "hierarchy_field_id": null,
    "status": "unknown",
    "keepalive_timestamp": 1726501979,
    "last_online": "unknown",
    "created_at": "2024-09-16T15:39:48.192Z",
    "updated_at": "2024-09-16T15:53:32.529Z",
    "virtual_nodes": [],
    "puppet_environment": null,
    "puppet_masterless": null,
    "service_checks": {
        "docker_versions": []
    },
    "available_docker_images": null
}

Example 2: Update a dynamic property on a node

This example updates the Lan 1 Ip dynamic property for node sit0000red1. When specifying an IP address you must also specify the netmask value as well, even if you aren't updating the existing netmask value. If no netmask value is specified, a default value of /32 is used.

Also note that when specifying a dynamic property value, you must add the my_ prefix, for example, the Lan 1 Ip property must be specified as my_lan1_ip when updating.

ruby api.rb <customer_code> put api/nodes/sit0000red1 '{"properties": {"my_lan1_ip": "1.2.3.6/32"}}'