diff --git a/content/set_up.md b/content/set_up.md index 41f479b..0275c8a 100644 --- a/content/set_up.md +++ b/content/set_up.md @@ -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. -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\\.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/.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\\Downloads\.pem -Destination C:\Users\\.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 = "" + client_name = "" + client_key = "" + ``` -```bash -cp ~/Downloads/USERNAME.pem ~/.chef/ -``` + Replace the following: -On Windows systems this, looks something like this: + - with your Chef Infra Server URL and organization name. For example, `https://chef-server.example.com/organizations/org-name`. + - `` with your Chef Infra Server username. + - with the path to your client certificate file. For example, `~/.chef/certificate_file.pem` or `C:/Users//.chef/.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)