# Chef

> The Chef configuration manager connects Cloud Management Platform (CMP) to a Chef server so that cookbooks and roles are applied to the servers CMP builds

---

Site [llms.txt](/llms.txt)

---

Users select cookbooks and roles on the order form as applications, and CMP installs the Chef agent on the new server and applies those cookbooks and roles through Chef. The **Chef** tile appears in the Add dialog only where a Chef configuration manager already exists, so this page covers deployments that already run Chef.

## What the integration does

- Installs cookbooks and roles on servers as CMP applications.
- Installs the Chef agent on each new server.
- Discovers and synchronizes Chef nodes.

## Prerequisites

CMP runs `knife` on the appliance to bootstrap agents, so Chef Workstation must be installed there with `knife` on the path. Follow the [Chef Workstation install guide](https://docs.chef.io/workstation/latest/install/).

CMP needs to reach the Chef server on its API port and log in to each server it bootstraps.

Tell [CloudBolt Support](/docs/cmp/support/) if you plan to use Chef on Windows.

## Connect to a Chef server

Create one configuration manager per Chef organization.

### Create the configuration manager

1. Go to **Admin** > **Configuration Managers**, then select **Add**.
1. Select the **Chef** tile.
1. Complete the form:

    | Field | Description |
    | --- | --- |
    | **Name** | Required. Label for the configuration. |
    | **Protocol**, **Hostname**, and **Port** | The Chef server's address, typically HTTPS on port 443. For hosted Chef, the hostname is `api.chef.io`. |
    | **Organization name** | The Chef organization that this manager serves. |
    | **CB client name** | The client name in Chef for the CMP appliance. Enter a placeholder and update it once you have the key files in place. |
    | **Knife bootstrap additional args** | Optional arguments added to every `knife bootstrap` call. Django template syntax works here. |
    | **Delete node if exists** | Select to remove a Chef node with the same name before bootstrapping to prevent a rebuilt server collision. |
    | **Environments** | The environments this manager serves. Set this now or later from the configuration manager or the environment. |

1. Select **Create**.

If your Chef server uses a self-signed certificate, add `--node-ssl-verify-mode none` to **Knife bootstrap additional args**.

### Add the key files

Each configuration manager reads its Chef credentials from its own directory on the appliance. For each Chef organization, on the appliance:

1. Create the directory `/var/opt/cloudbolt/connectors/chef/<ID>`, where `<ID>` is the configuration manager's numeric ID from the URL of its detail page.
1. From the Chef server, obtain the validator key, the client key for CMP, and the `knife.rb` configuration file, then copy all three into that directory. The client key file must be named for the client, as in `<client name>.pem`.
1. Edit `knife.rb` so that its `client_key` and `validation_key` lines point to the same directory.
1. In CMP, edit the configuration manager and set **CB client name** to the client name from the key filename.

To import cookbooks from the community site, also set `syntax_check_cache_path` in `knife.rb`.

## How CMP bootstraps a new server

CMP calls `knife bootstrap` for the new server, naming the node after the server's hostname and pointing knife at the `knife.rb` for that configuration manager. Ensure CMP has credentials for the server it is bootstrapping: an SSH key for cases such as Linux on AWS, or a password and username. Credentials can come from the template on the resource handler page, from a parameter set globally or at the group or environment level, or from the order form. See [Authentication requirements](/docs/cmp/use/orchestration/remote-scripts/authentication-requirements/).

On Linux, CMP connects over SSH as the credentialed user and adds sudo when that user is not root.

A server carrying a `chef_environment` parameter value is bootstrapped into that Chef environment. Bootstrapping has an hour to complete before CMP marks it as failed.

### Windows servers

On Windows, CMP connects over WinRM on port 5986, so WinRM must be enabled in the image or template. See [Windows servers using WinRM](/docs/cmp/use/orchestration/remote-scripts/os-specific-requirements/#windows-servers-using-winrm) for configuration and troubleshooting.

To use port 5985 instead, put this in **Knife bootstrap additional args**:

```text
{% if server.is_windows %}
-p 5985
{% endif %}
```

## Install cookbooks and roles

Associate the configuration manager with your environments, then create Chef cookbook and role objects in CMP. From then on, an order in one of those environments offers those cookbooks and roles as applications on the order form. CMP installs the agent on the new server, calls Chef to apply the chosen configuration, and the job's progress records both actions.

Applications can be installed and uninstalled at any point afterward, from the server list or a server's detail page.

Requesters do not need to know Chef or that Chef is involved.

## Related

- [Remote scripts](/docs/cmp/use/orchestration/remote-scripts/): How CMP authenticates to servers, including WinRM setup.