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.
• If you’ve enabled TLS, provide a root CA public key.

Enroll nodes

The chef360-node-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 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. If you’ve enabled TLS, get the root CA certificate on the machine where Chef 360 Platform Server is installed:

   kubectl get secret --namespace <NAMESPACE> common-generated-certs -o jsonpath="{.data['ca\.crt']}" | base64 -d
   

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_SAAS_PUBLIC_KEY>
     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.
   • <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. This should be stored using an encrypted Chef data bag or secrets manager.
   • <SECRET_KEY> with a secret key for secure communication with Chef 360 Platform. This should be stored using an encrypted Chef data bag or 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
   • <CHEF_360_SAAS_PUBLIC_KEY> if TLS is enabled, with the root CA public key. For example, node['enroll']['root_ca'].
   • <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 policy, create Policyfile.lock.json file and push the policy to the 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 policy. 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.