Skip to content

Update Workstation setup doc #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IanMadd wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update Workstation setup doc #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 87 additions & 91 deletions content/set_up.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,166 +9,162 @@ draft = false
weight = 10
+++

This guide walks you through the four parts to set up Chef Workstation on your computer.
This guide walks you through setting up Chef Workstation on your computer:

- [Set up your chef-repo](#set-up-your-chef-repo) for storing your cookbooks
- [Set up Chef Credentials](#set-up-chef-credentials)
- [Verify Client-to-Server Communication](#verify-client-to-server-communication)
- [Configure your Chef credentials](#configure-your-user-credentials)

## Prerequisites

- [Chef Workstation installed]({{< relref "install.md" >}})
- A running instance of Chef Infra Server.
- the `CLIENT.PEM` file supplied by your Chef administrator.
- The `CLIENT.PEM` file supplied by your Chef administrator.

## Set up your Chef repo
## About the chef-repo

If you're setting up Chef for the very first time **in your organization**, then you will need a Chef Infra repository for saving your cookbooks and other work.

The chef-repo is a directory on your workstation that stores everything
you need to define your infrastructure with Chef Infra:
If you're setting up Chef for the very first time in your organization, you need a chef-repo. The chef-repo is a directory on your workstation that stores everything you need to define your infrastructure with Chef Infra:

- Cookbooks (including recipes, attributes, custom resources, libraries, and templates)
- Data bags
- Policyfiles

The chef-repo directory should be synchronized with a version control
system, such as git. All of the data in the chef-repo should be treated
like source code.
Treat the chef-repo like source code and synchronize it with a version control system, such as Git.

Use the `chef` and `knife` commands to upload data from the chef-repo to Chef Infra Server. Chef Infra Client then uses that data to manage registered nodes, applying the correct cookbooks, Policyfiles, and settings.

You'll use the `chef` and `knife` commands to upload data to the Chef
Infra Server from the chef-repo directory. Once uploaded, Chef Infra
Client uses that data to manage the nodes registered with the Chef Infra
Server and to ensure that it applies the right cookbooks, policyfiles,
and settings to the right nodes in the right order.
### Set up your chef-repo

Use the [chef generate repo]({{< relref "ctl_chef.md#chef-generate-repo" >}}) command to create your Chef Infra repository. For example, to create a repository called `chef-repo`:
To set up your chef-repo, use the [chef generate repo]({{< relref "ctl_chef.md#chef-generate-repo" >}}) command. For example, to create a repository called `chef-repo`:

```bash
chef generate repo chef-repo
```

## Set up Chef credentials
## About Chef credentials

The first time you run Chef Workstation, it creates a `.chef` directory in your home directory to store your credentials and configuration.

For more information about configuring credentials, including creating credentials for multiple Chef Infra Server instances or organizations, see the [Set up knife documentation](/tools/knife/set_up/).

The first time you run Chef Workstation, it creates a `.chef` directory in your user directory. The `.chef` directory is where you store your Chef Workstation configuration and client keys.
### Credentials for administrators and users

If you're setting up Chef Workstation **as a Chef Infra Server administrator**, manage users with the [Chef Infra Server CLI](https://docs.chef.io/server/ctl_chef_server/#user-management). When you create a new user, Chef Infra Server generates a user-specific RSA client key that you must share securely with that user.

@IanMadd IanMadd Apr 16, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This mentions Infra Server, but DSM is the new platform, so we should add a link to the proper DSM page.

I'm not sure which that is. Maybe one of these:


If you're setting up Chef Workstation **as a Chef user**, you need a client private key that your server administrator creates for you on Chef Infra Server. The client private key is an RSA private key in `.pem` format.
If you're setting up Chef Workstation **as a Chef user**, you need a client private key created by your server administrator. The client private key is an RSA private key in `.pem` format.

### Configure your user credentials

Your `.chef` directory contains a `credentials` file used by Knife to communicate with Chef Infra Server.
To configure knife to communicate with Chef Infra Server, you need the following from your Chef administrator:

#### Prerequisites
- `chef_server_url`: the full URL to your Chef Infra Server including the organization.
- `client_name`: the username that you'll use to authenticate with Chef Infra Server.
- Your private key PEM file that you'll use to authenticate with Chef Infra Server (for example, `username.pem`).

To configure Knife to communicate with Chef Infra Server, you need the following values:
To configure your user credentials, follow these steps:

- `chef_server_url`: the full URL to your Chef Infra Server including the organization
- `node_name`: the client name your server administrator created for you
1. Set up your client private key.

Your Chef administrator provides this information.
Your Chef administrator provides you with a `client.pem` file (or similar). This file is an RSA private key that authenticates all communication between Chef Workstation and Chef Infra Server.

Use the `chef_server_url` and `node_name` values from this file when running `knife configure`.
Copy this file to the `~/.chef/` directory (on macOS or Linux) or `C:\Users\<USERNAME>\.chef\` directory (on Windows). Use one of the following commands:

#### Configure Knife automatically
- On macOS and Linux:

To configure Knife to connect to Chef Infra Server:
```bash
cp ~/Downloads/<USERNAME>.pem ~/.chef/
```

```sh
knife configure
```
- On Windows:

This command prompts you for your Chef Infra Server credentials and creates the necessary configuration files.
```powershell
Copy-Item -Path C:\Users\<USERNAME>\Downloads\<USERNAME>.pem -Destination C:\Users\<USERNAME>\.chef\
```

#### Configure Knife manually
1. Configure knife to connect to Chef Infra Server.

To manually configure Knife to connect to Chef Infra Server:
You can use the interactive `knife configure` command or manually create a credentials file.

1. Create the `~/.chef/credentials` file:
- To have knife prompt you for your Chef Infra Server credentials and generate a credentials file, run:

```sh
mkdir -p ~/.chef
touch ~/.chef/credentials
```
```sh
knife configure
```

1. Add your Chef Infra Server credentials to the `~/.chef/credentials` file:
- To manually create a credentials file, follow these steps:

```toml
[default]
chef_server_url = "https://chef-server.example.com/organizations/org-name"
client_name = "username"
client_key = "~/.chef/certificate_file.pem"
```
1. Create the `credentials` file:

Replace the following:
On macOS or Linux, run:

- `https://chef-server.example.com/organizations/org-name`: Your Chef Infra Server URL and organization name
- `username`: Your Chef Infra Server username
- `~/.chef/certificate_file.pem`: Path to your client certificate file
```sh
mkdir -p ~/.chef
touch ~/.chef/credentials
```

### Set up your client private key
On Windows (PowerShell), run:

All communication between Chef Workstation and Chef Infra Server is authenticated using an RSA public/private key pair. This pair is generated on Chef Infra Server and the private key must be copied to your local Chef Workstation installation for communication to function.
```powershell
New-Item -ItemType Directory -Path "$HOME/.chef" -Force
New-Item -ItemType File -Path "$HOME/.chef/credentials" -Force
```

Your Chef administrator will provide you with your `client.pem` file. Copy this file to the `~/.chef` directory.
1. Add your Chef Infra Server credentials to the `credentials` file:

On macOS and Linux systems, this looks something like:
```toml
[default]
chef_server_url = "<CHEF_SERVER_URL>"
client_name = "<USERNAME>"
client_key = "<CLIENT_CERT>"
```

```bash
cp ~/Downloads/USERNAME.pem ~/.chef/
```
Replace the following:

On Windows systems this, looks something like this:
- <CHEF_SERVER_URL> with your Chef Infra Server URL and organization name. For example, `https://chef-server.example.com/organizations/org-name`.
- `<USERNAME>` with your Chef Infra Server username.
- <CLIENT_CERT> with the path to your client certificate file. For example, `~/.chef/certificate_file.pem` or `C:/Users/<USERNAME>/.chef/<USERNAME>.pem`

```powershell
Copy-Item -Path C:\Users\MY_NAME\Downloads\USERNAME.pem -Destination C:\Users\MY_NAME\.chef\
```
For more information about configuring credentials, including creating credentials for multiple Chef Infra Server instances or organizations, see the [Set up knife documentation](/tools/knife/set_up/).

## Verify client-to-server communication
1. Verify that Chef Workstation can connect to Chef Infra Server:

To verify that Chef Workstation can connect to Chef Infra Server:
```bash
knife client list
```

Run the following command on the command line:

```bash
knife client list
```

Which returns a list of clients similar to:

```bash
chef_machine
registered_node
```
The command returns a list of Chef Infra Client nodes similar to:

### Fetch self-signed certificates
```bash
chef_machine
registered_node
```

If your Chef Infra Server deployment is configured to use a self-signed certificate, download the Chef Infra Server TLS/SSL certificate and save it locally in `.chef/trusted_certs`:
1. Optional: Fetch the Chef Infra Server SSL certificates.

1. Fetch the Chef Infra Server SSL certificates:
If your Chef Infra Server deployment is configured to use a self-signed certificate, download the Chef Infra Server TLS/SSL certificate and save it locally in `.chef/trusted_certs`:

```sh
knife ssl fetch
```
```sh
knife ssl fetch
```

1. Verify the certificates:
Verify the certificates:

```sh
knife ssl check
```
```sh
knife ssl check
```

Chef Infra verifies the security of all requests made to Chef Infra Server from tools like knife and Chef Infra Client. The certificate generated during the installation of Chef Infra Server is self-signed, meaning no certificate authority (CA) has signed it. You must download this certificate to every machine from which knife or Chef Infra Client will make requests to Chef Infra Server.
Chef Infra verifies the security of all requests made to Chef Infra Server from tools like knife and Chef Infra Client. The certificate generated during the installation of Chef Infra Server is self-signed, meaning no certificate authority (CA) has signed it. You must download this certificate to every machine from which knife or Chef Infra Client will make requests to Chef Infra Server.

For more information about how knife and Chef Infra Client use SSL certificates generated by Chef Infra Server, see [Chef Infra Client's SSL certificates documentation](https://docs.chef.io/client/latest/security/chef_client_security/#ssl-certificates).
For more information about how knife and Chef Infra Client use SSL certificates generated by Chef Infra Server, see [Chef Infra Client's SSL certificates documentation](https://docs.chef.io/client/latest/security/chef_client_security/#ssl-certificates).

## Next step

- [Add a Chef license](license)
- [Get started with Chef cookbook development using Chef Workstation](get_started)

## More information

- [Knife setup documentation](/tools/knife/knife_setup/)
- [Knife `config.rb` documentation](/tools/knife/config_rb)
- [Set up knife documentation](/tools/knife/set_up/)
- [knife `config.rb` settings documentation](/tools/knife/config_rb)
- [`knife ssl fetch` documentation](/tools/knife/knife_ssl_fetch/)
- [`knife ssl check` documentation](/tools/knife/knife_ssl_check/)
- [LearnChef tutorials](https://www.chef.io/training/tutorials)
Loading