Single-node enrollment

With single-node enrollment, you define the credentials and enrollment settings for a node and then Chef 360 Platform uses those settings to connect to and enroll the node with a node cohort.

Single-node enrollment fully enrolls nodes.

Role requirements

To enroll nodes, use a profile with the node-manager role.

Connection requirements

Nodes must be accessible with SSH or WinRM.
Nodes must have a public DNS name or public IP address.
A node’s IP address can’t be 127.0.0.1 (localhost).
A node’s CIDR address must not overlap with the Chef 360 Platform services’ CIDR range. The default CIDR ranges for Chef 360 Platform services are 10.244.0.0/16 and 10.96.0.0/12.
The node’s ports for RabbitMQ and the nginx API gateway must be open to Chef 360 Platform. Additionally, Chef 360 Platform must allow inbound connections to these ports from the node.
For nodes running Windows Server 2012 or 2016, download and manually install curl. After installation, ensure the curl executable is added to the system’s PATH environment variable.

SSH connection requirements

Port 22 must be open.
The user must have sudo privileges.
The user must authenticate using an ed25519 or RSA (2048-bit) key without a passphrase.

WinRM connection requirements

Ports 5985 (HTTP) and 5986 (HTTPS) must be open.

Configure WinRM by running the following commands:

winrm quickconfig   # Select 'Yes' when prompted
winrm set winrm/config/service/Auth '@{Basic="true"}'
winrm set winrm/config/service '@{AllowUnencrypted="true"}'
netsh advfirewall firewall add rule name="WinRM-HTTP" dir=in localport=5985 protocol=TCP action=allow
netsh advfirewall firewall add rule name="WinRM-HTTPS" dir=in localport=5986 protocol=TCP action=allow

Enroll nodes

Enroll Linux nodes

You can enroll Linux nodes using a YAML or JSON file and using an RSA key or password to authenticate with the node. To enroll a Linux node, follow these steps:

Create a JSON, YAML or TOML file that defines the node connection settings.

To authenticate using an RSA key, use the following payload:

JSON
YAML
TOML

{
    "cohortId": "<COHORT_ID>",
    "url": "<NODE_DNS_OR_PUBLIC_IP>",
    "sshCredentials": {
        "username": "<SSH_USER_NAME>",
        "key": "<SSH_KEY>",
        "port": <SSH_PORT>
    }
}

Format SSH keys in a JSON payload as a single-line string. To add a multiline key, replace new lines with the newline character \n.

Use the following command to replace new lines in a PEM file:

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <PEM_FILENAME>

cohortId: <COHORT_ID>
url: <NODE_DNS_OR_PUBLIC_IP>
sshCredentials:
  username: <SSH_USER_NAME>
  key: <SSH_KEY>
  port: <SSH_PORT>

cohortId = "<COHORT_ID>"
url = "<NODE_DNS_OR_PUBLIC_IP>"

[sshCredentials]
port = <SSH_PORT>
username = "<SSH_USER_NAME>"
key = "<SSH_KEY>"

To authenticate with a password, use the following payload:

JSON
YAML
TOML

{
    "cohortId": "<COHORT_ID>",
    "url": "<NODE_DNS_OR_PUBLIC_IP>",
    "sshCredentials": {
        "username": "<SSH_USER_NAME>",
        "password": "<SSH_PASSWORD>",
        "port": <SSH_PORT>
    }
}

cohortId: <COHORT_ID>
url: <NODE_DNS_OR_PUBLIC_IP>
sshCredentials:
  username: <SSH_USER_NAME>
  password: <SSH_PASSWORD>
  port: <SSH_PORT>

cohortId = "<COHORT_ID>"
url = "<NODE_DNS_OR_PUBLIC_IP>"

[sshCredentials]
port = <SSH_PORT>
username = "<SSH_USER_NAME>"
password = "<SSH_PASSWORD>"

Replace the following:

<COHORT_ID> with the ID of the cohort that the node will be enrolled with.
<NODE_DNS_OR_PUBLIC_IP> with a public domain name or IP address.
<SSH_USERNAME> with the SSH username to authenticate with the node.
<SSH_KEY> if using an RSA key, with the key used to authenticate with the node.
<SSH_PASSWORD> if using an SSH password, with the password used to authenticate with the node.
<SSH_PORT> with the SSH port. Default is 22.

Enroll the node.

To enroll with a JSON file, use the enrollment enroll-node command:

chef-node-management-cli enrollment enroll-node --body-file <JSON_WINDOWS_SETTINGS_FILE> --profile <NODE_MANAGER_PROFILE_NAME>

To enroll a YAML file, use the enrollment enroll-node command with the --body-format yaml argument:

chef-node-management-cli enrollment enroll-node --body-file <YAML_WINDOWS_SETTINGS_FILE> --body-format yaml --profile <NODE_MANAGER_PROFILE_NAME>

The response is similar to the following:

{
    "item": {
        "id": "36c570b1-798a-4530-ada5-2661dfeb3fac",
        "nodeId": "e4b1b524-4e77-4448-b1a9-01b80288c898"
    }
}

Enroll Windows nodes

You can enroll Windows nodes using a JSON, YAML, or TOML file. To enroll a Windows node, follow these steps:

Create a JSON, YAML, or TOML file that defines the node connection settings:

JSON
YAML
TOML

{
    "cohortId": "<COHORT_ID>",
    "url": "<NODE_DNS_OR_PUBLIC_IP>",
    "winRMCredentials": {
        "username": "<WINDOWS_USERNAME>",
        "password": "<WINDOWS_PASSWORD>"
    }
}

cohortId: <COHORT_ID>
url: <NODE_DNS_OR_PUBLIC_IP>
winRMCredentials:
  username: <WINDOWS_USERNAME>
  password: <WINDOWS_PASSWORD>

cohortId = "<COHORT_ID>"
url = "<NODE_DNS_OR_PUBLIC_IP>"

[winRMCredentials]
username = "<WINDOWS_USERNAME>"
password = "<WINDOWS_PASSWORD>"

Replace the following:

<COHORT_ID> with the ID of the cohort that the node will be enrolled with.
<NODE_DNS_OR_PUBLIC_IP> with the node’s public domain name or IP address.
<WINDOWS_USERNAME> with the Windows username to authenticate with the node.
<WINDOWS_PASSWORD> with the Windows password used to authenticate with the node.

Enroll the node using the enrollment enroll-node command.

To enroll with a JSON file:

chef-node-management-cli enrollment enroll-node --body-file <WINDOWS_SETTINGS_FILE> --profile <NODE_MANAGER_PROFILE_NAME>

To enroll with a YAML or TOML file, use the the --body-format argument. For example:

chef-node-management-cli enrollment enroll-node --body-file <WINDOWS_SETTINGS_FILE> --body-format <FILE_FORMAT> --profile <NODE_MANAGER_PROFILE_NAME>

Replace the following:

<WINDOWS_SETTINGS_FILE> with the connection settings file path.
<FILE_FORMAT> with the file format, either toml or yaml. Default value is json.

The response is similar to the following:

{
    "item": {
        "id": "36c570b1-798a-4530-ada5-2661dfeb3fac",
        "nodeId": "e4b1b524-4e77-4448-b1a9-01b80288c898"
    }
}

Get node enrollment status

Nodes have the following enrollment levels:

admitted: A node’s credentials and IP address are provided for enrollment and a node ID is assigned.
enrolled: The node is successfully enrolled with Chef 360 Platform.

Get the enrollment status of a single node

You can check if a node is enrolled by getting its current enrollment status or by getting the status of each step in the node’s enrollment process.

To get the enrollment level of a node, use the node ID and the management node find-one-node subcommand:

chef-node-management-cli management node find-one-node --nodeId <NODE_ID> --profile <NODE_MANAGER_PROFILE_NAME>

An enrolled node has an enrollment level of enrolled, otherwise it has a status of admitted. For example:

"enrollmentLevel": "enrolled"

To get the status of each step in the node’s enrollment process, use the get-status subcommand:

chef-node-management-cli status get-status --nodeId <NODE_ID> --profile <NODE_MANAGER_PROFILE_NAME>

An enrolled node has "status": "Success" at each step.

Get the enrollment status using the enrollment ID

You can get the node enrollment status and node IDs using an enrollment ID and the status get-enrollmentId-status subcommand:

chef-node-management-cli status get-enrollmentId-status --enrollmentId <ENROLLMENT_ID> --profile <NODE_MANAGER_PROFILE_NAME>

The response is similar to:

{
  "item":{
    "id":"ebff692a-ca22-4841-afc9-b334b9e2256a",
    "items":[
      {
        "nodeId":"4a85f9bc-db17-4cc9-a253-f6e1fb57f000",
        "status":"Enrollment"
      },
      {
        "nodeId":"bc7976cb-70b3-41bb-b82f-c7209a8e3364",
        "status":"Enrollment"
      }
    ]
  }
}