Skip to main content

Enroll nodes

Node enrollment brings nodes under management by Chef 360 Platform.

This document demonstrates two different methods of node enrollment:

  • cookbook-based enrollment
  • single-node enrollment

For more information on node enrollment, see the node enrollment documentation.

Prerequisites

Requirements

Review the node requirements before enrolling nodes.

Single-node enrollment

Single-node enrollment enrolls nodes from the server side. With this method, you define connection and configuration details and push them up to Chef 360 Platform, which connects to each node and installs Chef Habitat, Chef Node Management, and any skills or agents assigned to a node cohort.

Enroll Linux nodes

You can enroll Linux nodes using a YAML or JSON file.

JSON file enrollment

  1. Create a file name enroll-linux.json with the following payload:

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

    Replace the following:

    • <COHORT_ID> with the cohort ID returned by chef-node-management-cli when you created the node cohort
    • <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> with the SSH key used to authenticate with the node
    • <SSH_PORT> with the SSH port. Default is 22.

    Note

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

    You can use the following command to replace new lines in a PEM file:

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

  2. Enroll the node:

    chef-node-management-cli enrollment enroll-node --body-file enroll-linux.json

    The response is similar to the following:

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

YAML file enrollment

  1. Create a file name enroll-linux.yaml with the following payload:

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

    Replace the following:

    • <COHORT_ID> with the cohortId by chef-node-management-cli when you created the node cohort
    • <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> with the SSH key used to authenticate with the node
    • <SSH_PORT> with the SSH port. Default is 22.

  2. Enroll the node:

    chef-node-management-cli enrollment enroll-node --body-file enroll-linux.yaml

    The response is similar to the following:

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

Enroll Windows nodes

JSON file enrollment

  1. Create a JSON file with WinRM credentials:

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

    Replace the following:

    • <COHORT_ID> with the cohortId returned by chef-node-management-cli when you created the node cohort
    • <NODE_DNS_OR_PUBLIC_IP> with a 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
    • <PORT_NUMBER> with the WinRM port number. Default is 5985-5986.

  2. Enroll the node:

    chef-node-management-cli enrollment enroll-node --body-file enroll-windows.json

    The response is similar to the following:

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

YAML file enrollment

  1. Create a YAML file with WinRM credentials:

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

    Replace the following:

    • <COHORT_ID> with the cohortId returned by chef-node-management-cli when you created the node cohort
    • <NODE_DNS_OR_PUBLIC_IP> with a 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
    • <PORT_NUMBER> with the WinRM port number. Default is 5985-5986.

  2. Enroll the node:

    chef-node-management-cli enrollment enroll-node --body-file <FILENAME.yaml>

    The response is similar to the following:

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

Cookbook-based enrollment

With cookbook-based enrollment, you enroll nodes from the client side by uploading a cookbook with enrollment settings to Chef Infra Server and then Chef Infra Client enrolls the node with Chef 360 Platform.

Enroll nodes

The chef-cookbook-enroll cookbook uses the node_management_enroll custom resource and a wrapper cookbook to define enrollment settings.

To configure the cookbooks and define enrollment settings, follow these steps:

  1. Download the chef360-node-enroll cookbook.

  2. Upload the chef360-node-enroll cookbook, which includes the node_management_enroll resource, to your Chef Infra Server:

    knife cookbook upload chef360-node-enroll --cookbook-path <COOKBOOK_DIR_PATH>

    Replace COOKBOOK_DIR_PATH with the path to your cookbook directory.

  3. Create a wrapper cookbook and add the chef360-node-enroll cookbook as a dependency:

    chef generate cookbook <COOKBOOK_NAME>

    In the metadata.rb file of your wrapper cookbook, add the following dependency to include the chef-cookbook-enroll cookbook:

    depends 'chef360-node-enroll', '~> 1.0.0'

  4. Define the node_management_enroll resource in your wrapper cookbook’s recipe:

    node_management_enroll 'Enroll Node' do
  chef_platform_url '<CHEF_360_FQDN>'
  enroll_type '<ENROLLMENT_TYPE>'
  api_port '<API_PORT>'
  access_key '<ACCESS_KEY>'
  secret_key '<SECRET_KEY>'
  cohort_id '<COHORT_ID>'
  hab_builder_url '<HABITAT_BUILDER_URL>'
  working_dir_path '<VALID_DIR_PATH>'
  upgrade_skills <UPGRADE_SKILLS>
end

    Replace:

    • <CHEF_360_FQDN> with the fully qualified domain name (FQDN) for your Chef 360 Platform deployment.
    • <ENROLLMENT_TYPE> with either full or partial depending on the form of enrollment. Use full unless you must partial. See the node enrollment documentation for details on the difference between these types.
    • <API_PORT> with the API port configured in Chef 360 Platform. The default value is 31000.
    • <ACCESS_KEY> with an access key for secure communication with Chef 360 Platform. Store securely using an encrypted Chef data bag or a secrets manager.
    • <SECRET_KEY> with a secret key for secure communication with Chef 360 Platform. Store securely using an encrypted Chef data bag or a secrets manager.
    • <COHORT_ID> with a valid cohort UUID. The cohort defines all skills and settings installed on the node.
    • <HABITAT_BUILDER_URL> with the URL of the Chef Habitat Builder used by your organization. Default value: https://bldr.habitat.sh
    • <VALID_DIR_PATH> with a temporary working directory where all required builds are downloaded. Specify a valid path based on the OS. Default value: /tmp.
    • <UPGRADE_SKILLS> with true or false. If true, Chef 360 Platform checks for the latest skill versions and installs them if found. Default value: false.

  5. Push the wrapper cookbook or policy to the Chef Infra Server.

    1. If you’re using a role, upload the wrapper cookbook to the Chef Infra Server:

      knife cookbook upload <WRAPPER_COOKBOOK_NAME> --cookbook-path <WRAPPER_COOKBOOK_DIR_PATH>

    2. If you’re using a Policyfile, create Policyfile.lock.json file and push the Policyfile to Chef Infra Server:

      chef install
chef push <POLICY_GROUP> <POLICYFILE>

  6. Include the wrapper cookbook in your node’s run-list by adding it to a role or Policyfile. See the run-list and role documentation for more information.

    The next time Chef Infra Client runs, it executes the node_management_enroll resource and the node is enrolled with Chef 360 Platform.

Check the node enrollment status

You can get the node enrollment level of a node using the node ID and the management node find-one-node subcommand:

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

Once a node is successfully enrolled, the enrollment level is set to enrolled, otherwise it remains at admitted.

"enrollmentLevel": "enrolled"

You can also check the enrollment status for the individual steps:

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

Each step should have a success status.

"status": "Success"

Verify that the skills are installed

  • Verify that the skills are installed:

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

    The response includes a list of the installed skills.

More information

Next step

Thank you for your feedback!

×