Enroll nodes with a Chef Infra cookbook

With cookbook-based node enrollment, you upload cookbooks with enrollment settings to Chef Infra Server and Chef Infra Client enrolls the node with Chef 360 Platform.

Cookbook-based enrollment can fully or partially enroll nodes.

Requirements

Nodes enrolled with Chef 360 Platform using a Chef Infra cookbook have the following requirements:

Nodes must have Chef Infra Client installed.
Nodes have a public DNS or public IP address.
Nodes can’t have localhost (127.0.0.1) as an IP address.
Nodes can’t have a CIDR address in the same range as the Chef 360 Platform services. The default CIDR range for Chef 360 Platform services is 10.244.0.0/16 or 10.96.0.0/12.
You must have sudo privileges on the node.

Role requirements

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

Enroll nodes

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:

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.
Download the chef360-node-enroll cookbook.
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.
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'
```

On a computer registered with Chef 360 Platform 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 looks like 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"
  }
}

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.
For Chef 360 SaaS, use 443.
<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.

For Chef 360 SaaS, use the following public key.

Chef 360 SaaS public key

For Chef 360 SaaS, replace <CHEF_360_ROOT_CA> with the following public key. This key expires on March 18, 2029.

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

Push the wrapper cookbook or policy to Chef Infra Server.
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>
```
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>
```
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. The access key and secret key are included with the wrapper cookbook and passed to all nodes that run the cookbook so they can authenticate with Chef 360 Platform.