Create a node

POST api/nodes

Creates a new node in an existing node group.

Request syntax

post api/nodes '{"node_group_id": <integer>, "instance_number": <integer>, "store_number": <integer>, "properties": {"<my_property_name>": ["<value1>", "<value2>", "<value3>"], "<my_property_name>": "<value1>"}}'

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required	Default value
`node_group_id`	Integer	The ID of the node group to associate the node to.	Yes	N/A
`instance_number`	Integer	The node instance number.	Yes	N/A
`store_number`	Integer	The store number to associate the node with.	Yes	N/A
`node_name`	String	The name for the node.	No	`null`
`serialno`	String	The serial number of the physical host of the node. The value is saved in lowercase.	No	`null`
`parent_node`	String	The hostname of the parent node. If specified, the node is created as a virtual node.	No	`null`
`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": "1.2.3.4"}`). A property must exist in the node group's node properties for its value to be added to the node. When specifying an IP address property with a netmask property, the IP address property must be specified first in the request. See Example 2.	No	N/A
`puppet_masterless`	Boolean	Indicates if the node is a masterless puppet node.	No	`false`
`puppet_environment`	String	The puppet environment for the node.	No	`null`

Response syntax

{
    "exporter_job": integer,
    "id": integer,
    "installation_token": {
        "uuid": "d3cceEXAMPLE",
        "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": {
        "property1": "value1",
        "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 201 response is returned. The following data is returned in JSON format.

Field	Type	Description
`exporter_job`	Integer	The ID of the job that exports the new node's configuration.
`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 was specified.
`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. The hostname is generated in the form `<customer_code><store_number>red<instance_number>`.
`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
`422`	`Validation Failed: instance_number is missing, store_number is missing`	One or more required parameters are missing from the request. The message lists each missing parameter.
`422`	`Validation Failed: store_number Hostname already taken, check other nodes with same instance and node number.`	A node with the same store number and instance number already exists.

Examples

Example 1: Create a new node

This example creates a new node in node group ID 2235 and specifies a value of 1.2.3.4 for the lan1 dynamic property on the node. The dynamic property must exist at the node group level for the value to be added to the node. The node will have hostname in the form of <customer_code><store_number>red<instance_number>.

ruby api.rb <customer_code> post api/nodes '{"node_group_id": 2235, "instance_number": 0, "store_number": 2235, "properties": {"my_lan1": "1.2.3.4"}}'

Response

{
  "exporter_job": 1544847,
  "id": 120002,
  "installation_token": {
    "uuid": "2ad2580a-1475-4567-a6f2-EXAMPLE",
    "state": "active",
    "expires_at": null
  },
  "node_name": null,
  "node_group_id": 2235,
  "store_number": 2235,
  "instance_number": 0,
  "hostname": "sit2235red0",
  "serialno": null,
  "virtual": false,
  "type_of_server": null,
  "hierarchy_field_id": null,
  "status": "unknown",
  "keepalive_timestamp": 1726510079,
  "last_online": "unknown",
  "created_at": "2024-09-16T18:12:08.790Z",
  "updated_at": "2024-09-16T18:12:08.790Z",
  "virtual_nodes": [
  ],
  "puppet_environment": null,
  "puppet_masterless": null,
  "properties": {
    "my_lan1": "1.2.3.4"
  },
  "service_checks": {
    "docker_versions": [
    ]
  },
  "available_docker_images": null
}

Example 2: Create a new node and specify IP address and netmask properties

When creating a new node while specifying an IP address and netmask property in the request, the order that these properties are specified is important. If you want to specify a netmask value, you must specify the IP address property first and then the netmask property as in the following example.

If you specify a netmask property before an IP address property, the netmask property is ignored and a netmask value of /32 is used. It's important to verify in the response the API sends that the values you intended to set are used.

ruby api.rb <customer_code> post api/nodes '{"node_group_id": 2235, "instance_number": 0, "store_number": 2235, "properties": {"my_ipmi_ip":"172.20.40.183","my_ipmi_netmask":"24"}}'