Skip to main content

Enroll nodes

When you enroll a node into a node cohort, Chef 360 Platform installs the Chef skills and skill settings that are defined for all nodes in that cohort. These skills allow Chef 360 Platform to manage the node, execute Chef Courier jobs, and report back to Chef 360 Platform.

Chef 360 Platform installs the following skills in the default skill assembly:

  • Chef Infra Client interpreter skill: Executes Chef Infra Client runs.
  • Courier Runner skill: Interprets and executes Chef Courier jobs.
  • Gohai skill: Reports node attribute data to Chef 360 Platform.
  • Inspec interpreter skill: Executes Chef InSpec audits.
  • Node Management agent: Manages and installs other skills on the node.
  • Restart interpreter skill: Restarts nodes.
  • Shell interpreter skill: Executes shell scripts.

For more information, see the Chef 360 skills documentation.

Node enrollment methods

This document demonstrates two different methods of node enrollment:

  • cookbook-based enrollment
  • single-node enrollment

For more information, see the node enrollment documentation.

Note

Chef 360 Platform doesn’t support node re-enrollment.

Role requirements

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

Before you begin

Single-node enrollment

Single-node enrollment allows you to enroll nodes directly from the server side. With this method, you specify the connection and configuration details for each node and upload them to Chef 360 Platform. Chef 360 Platform then connects to each node, installs Chef Habitat, Chef Node Management, and any skills or agents associated with the node’s cohort.

Enroll Linux nodes

Before you begin, you will need the following node connection details:

  • the public DNS or IP address
  • the RSA key or password
  • the username
  • the SSH port number

To enroll a Linux node, follow these steps:

  1. Get the ID of the cohort that you want to add the node to using the find-all-cohorts command:

    chef-node-management-cli management cohort find-all-cohorts --profile <PROFILE_NAME>

    Replace <PROFILE_NAME> with the name of a profile that has the node-manager role.

    This returns a list of cohorts and their IDs.

  2. Create a JSON file that defines the node connection settings. You can authenticate with a password or RSA key.

    Use the following JSON to authenticate with an RSA key:

    {
    "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 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> with the SSH key used to authenticate with the node.
    • <SSH_PORT> with the SSH port. Default is 22.

    Note

    Format SSH keys 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>

    Use the following JSON to authenticate with a password:

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

    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_PASSWORD> with the SSH password used to authenticate with the node.
    • <SSH_PORT> with the SSH port. Default is 22.

  3. Enroll the node using the enrollment enroll-node command:

    chef-node-management-cli enrollment enroll-node --body-file <JSON_SETTINGS_FILE> --profile <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

Before you begin, you will need the following node connection details:

  • the public DNS or IP address
  • the username and password

To enroll a Windows node, follow these steps:

  1. Get the ID of the cohort that you want to add the node to using the find-all-cohorts command:

    chef-node-management-cli management cohort find-all-cohorts --profile <PROFILE_NAME>

    Replace <PROFILE_NAME> with the name of a profile that has the node-manager role.

    This returns a list of cohorts and their IDs.

  2. Create a JSON file that defines the node connection settings:

    {
    "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.

  3. Enroll the node using the enrollment enroll-node command:

    chef-node-management-cli enrollment enroll-node --body-file <JSON_SETTINGS_FILE> --profile <PROFILE_NAME>

    The response is similar to the following:

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

Cookbook-based enrollment

Cookbook-based enrollment allows you to enroll nodes from the client side. In this method, you upload a cookbook with the enrollment settings to the Chef Infra Server, and then use Chef Infra Client to enroll the node with Chef 360 Platform.

Enroll nodes with a cookbook

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

Before you begin, you will need the following node and Chef 360 Platform details:

  • Your Chef 360 Platform FQDN.
  • Your Chef 360 Platform API port number.
  • An access key and secret key for secure communication with Chef 360 Platform.
  • The Habitat Builder URL, either your private URL or https://bldr.habitat.sh.
  • If you’ve enabled TLS on Chef 360 Platform, get the root CA certificate for the machine where Chef 360 Platform Server is installed. Contact your account team for information on how to access this certificate.

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

  1. Get the ID of the cohort that you want to add the node to using the find-all-cohorts command:

    chef-node-management-cli management cohort find-all-cohorts --profile <PROFILE_NAME>

    Replace <PROFILE_NAME> with the name of a profile that has the node-manager role.

    This returns a list of cohorts and their IDs.

  2. Download the chef360-node-enroll cookbook.

  3. 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.

  4. 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.8'

  5. On a computer registered with the Chef 360 Server, generate an access key and secret key:

    chef-platform-auth-cli user-account self create-token \
  --body '{"expiration": "<EXPIRATION_DATE>", "name": "<TOKEN_NAME>"}' \
  --profile <PROFILE_NAME>

    Replace:

    • <EXPIRATION_DATE> with a date and time in ISO 8601 format (for example, 2027-12-31T11:42:23-05:00).
    • <TOKEN_NAME> with a meaningful token name for easy identification.
    • <PROFILE_NAME> with a profile that has the node-manager role assigned to it.

    The response includes an access key and secret key and is similar to the following:

    {
  "item": {
    "accessKey": "6QIUKP4WIXD4RVAF0BQ3",
    "expiration": "2027-12-31T11:42:23-05:00",
    "id": "bcba5b7a-fb0b-4a62-b442-7ba7bda5e05a",
    "name": "CI-CD Token",
    "role": {
      "id": "5fcb0235-1e56-4ece-8857-404a5d39a290",
      "name": "tenant-admin"
    },
    "secretKey": "x6aCg1NckQoLsQnere26fmGgD0RiWOrf4RNXBhlg"
  }
}

  6. 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>'
  root_ca <CHEF_360_ROOT_CA>
  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 ID. 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
    • <CHEF_360_ROOT_CA> if TLS is enabled, with the root CA public key.
    • <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.

  7. 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>

  8. 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 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.

Verify that the skills are installed

  • To verify that the skills are installed, use the find-one-node command:

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

    The response returns details about the node including a list of installed skills.

More information

Next step

Thank you for your feedback!

×