Chef Workstation Setup

My Workstation Configuration Journey

When I first started with Chef, I underestimated the importance of a properly configured workstation. My initial attempts involved a mix of manually installed components, mismatched versions, and incomplete configurations that led to frustrating errors. After rebuilding my environment several times, I learned that a well-configured workstation is the foundation for productive Chef automation.

Today, my Chef Workstation is a streamlined development environment where I can write cookbooks, test them locally with Test Kitchen, develop InSpec profiles, and deploy to my infrastructure with confidence. This article shares the setup process I've refined through experience.

What is Chef Workstation?

Chef Workstation is the all-in-one package containing everything you need for Chef development:

• Chef Infra Client - For testing cookbooks locally

• Chef InSpec - For writing and testing compliance profiles

• Test Kitchen - For automated cookbook testing

• Cookstyle - For linting and enforcing cookbook style

• knife - Command-line tool for interacting with Chef Server

• chef - Command-line tool for generating cookbooks and resources

This unified package eliminates the complexity of installing components separately and ensures version compatibility.

Prerequisites

Before installing Chef Workstation, ensure you have:

• Operating System: macOS, Windows, or Linux (I primarily use macOS for development)

• Administrator Access: Required for installation

• Git: For version control (essential for cookbook management)

• Text Editor: VS Code, Sublime Text, or vim (I use VS Code with Chef extensions)

• SSH Access: To target nodes for testing (if managing remote systems)

• Virtualization (Optional): VirtualBox or Docker for local testing with Test Kitchen

Installing Chef Workstation

macOS Installation (My Primary Platform)

I use Homebrew for package management, which makes Chef Workstation installation straightforward:

# Install Chef Workstation via Homebrew
brew install --cask chef-workstation

# Verify installation
chef --version
inspec --version
kitchen --version

Expected Output:

Chef Workstation version: 23.11.1064
Chef Infra Client version: 18.4.12
Chef InSpec version: 5.22.40
Test Kitchen version: 3.5.1
Cookstyle version: 7.32.5

Linux Installation (Ubuntu/Debian)

For my Linux test systems:

# Download the package
wget https://packages.chef.io/files/stable/chef-workstation/23.11.1064/ubuntu/22.04/chef-workstation_23.11.1064-1_amd64.deb

# Install
sudo dpkg -i chef-workstation_23.11.1064-1_amd64.deb

# Verify
chef --version

Windows Installation

For Windows workstations in my team:

# Download installer from https://downloads.chef.io/tools/workstation
# Run the MSI installer with administrative privileges

# Verify in PowerShell
chef --version

Configuring Your Development Environment

Setting Up Directory Structure

I organize my Chef work with a consistent directory structure:

# Create Chef workspace
mkdir -p ~/chef-repo/{cookbooks,data_bags,environments,roles}
cd ~/chef-repo

# Initialize Git repository
git init

My Directory Layout:

~/chef-repo/
├── cookbooks/          # Custom cookbooks
├── data_bags/          # Encrypted data bags for secrets
├── environments/       # Environment configurations (dev, staging, prod)
├── roles/              # Role definitions
├── .chef/              # Chef configuration and credentials
└── inspec-profiles/    # Custom InSpec profiles

Configuring Git

Essential for version control and collaboration:

# Configure Git if not already done
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Create .gitignore for Chef
cat > .gitignore << 'EOF'
.chef/*.pem
.chef/encrypted_data_bag_secret
.kitchen/
.kitchen.local.yml
*.swp
*.bak
.DS_Store
EOF

Lesson Learned: Never commit private keys or secrets. I use encrypted data bags and manage credentials separately.

Installing Useful Tools and Extensions

VS Code Extensions

For my IDE, I use these extensions:

# Install VS Code (if not installed)
brew install --cask visual-studio-code

# Launch VS Code and install extensions:
# - Chef Extension Pack
# - Ruby Language Support
# - YAML Support

My VS Code Extensions:

• chef.chef - Chef syntax highlighting and snippets

• rebornix.ruby - Ruby language support

• redhat.vscode-yaml - YAML validation

• ms-vscode.test-kitchen - Test Kitchen integration

Additional Ruby Gems

Some useful gems I've added:

# Install helpful gems
chef gem install knife-ec2      # AWS integration
chef gem install knife-azure    # Azure integration
chef gem install berkshelf      # Cookbook dependency management

Connecting to Chef Server

Obtaining Credentials

To interact with Chef Server, you need two files:

1. User Private Key (username.pem)

2. Organization Validator Key (organization-validator.pem)

How I obtained mine:

# Download from Chef Server or receive from your Chef administrator
# Place in ~/.chef/ directory
mkdir -p ~/.chef
chmod 700 ~/.chef

Creating knife.rb Configuration

The knife.rb file configures how your workstation communicates with Chef Server:

# Create knife configuration
cat > ~/.chef/knife.rb << 'EOF'
current_dir = File.dirname(__FILE__)
log_level                :info
log_location             STDOUT
node_name                'your-username'
client_key               "#{current_dir}/your-username.pem"
chef_server_url          'https://chef-server.example.com/organizations/your-org'
cookbook_path            ["#{current_dir}/../cookbooks"]
knife[:editor]           'vim'
EOF

My Actual Configuration (sanitized):

current_dir = File.dirname(__FILE__)
log_level                :info
log_location             STDOUT
node_name                'htunn'
client_key               "#{current_dir}/htunn.pem"
chef_server_url          'https://chef.company.internal/organizations/infrastructure'
cookbook_path            ["#{current_dir}/../cookbooks"]
knife[:editor]           'vim'

# AWS knife plugin settings
knife[:aws_access_key_id]     = ENV['AWS_ACCESS_KEY_ID']
knife[:aws_secret_access_key] = ENV['AWS_SECRET_ACCESS_KEY']
knife[:region]                = 'us-west-2'

Testing Chef Server Connection

Verify your connection works:

# Test connection
knife client list

# You should see your organization's clients
# Example output:
# your-org-validator
# node1.example.com
# node2.example.com

Troubleshooting Connection Issues:

# Verify SSL certificates
knife ssl check

# If SSL issues, fetch certificates
knife ssl fetch

# Test with verbose output
knife client list -VV

Setting Up Test Kitchen

Test Kitchen enables local cookbook testing before production deployment - crucial for my workflow.

Creating a Test Kitchen Configuration

When you generate a cookbook, Test Kitchen configuration is created automatically:

# Generate a test cookbook
chef generate cookbook test_cookbook
cd test_cookbook

# View the generated .kitchen.yml
cat .kitchen.yml

My Customized .kitchen.yml:

---
driver:
  name: vagrant
  network:
    - ["private_network", {ip: "192.168.33.33"}]

provisioner:
  name: chef_zero
  product_name: chef
  install_strategy: always
  always_update_cookbooks: true

verifier:
  name: inspec

platforms:
  - name: ubuntu-22.04
    driver_config:
      box: bento/ubuntu-22.04
  - name: centos-8
    driver_config:
      box: bento/centos-8

suites:
  - name: default
    run_list:
      - recipe[test_cookbook::default]
    verifier:
      inspec_tests:
        - test/integration/default
    attributes:

Testing Your Setup

Run Test Kitchen to verify everything works:

# List test instances
kitchen list

# Create test instance
kitchen create

# Converge (apply cookbook)
kitchen converge

# Run tests
kitchen verify

# Destroy instance
kitchen destroy

# Or run everything at once
kitchen test

What I Learned: Test Kitchen was initially intimidating, but it's now indispensable. Testing locally catches issues before they reach production.

Configuring InSpec

InSpec is included with Chef Workstation, but let's configure it properly.

Creating InSpec Profile Directory

# Create InSpec profiles directory
mkdir -p ~/chef-repo/inspec-profiles
cd ~/chef-repo/inspec-profiles

# Generate a test profile
inspec init profile my-baseline

Testing InSpec Locally

# Run InSpec against localhost
inspec exec my-baseline

# Run against remote host via SSH
inspec exec my-baseline -t ssh://user@hostname -i ~/.ssh/id_rsa

# Run and generate HTML report
inspec exec my-baseline --reporter html:report.html

My InSpec Workflow:

1. Develop profiles in inspec-profiles/

2. Test locally with inspec exec

3. Commit to Git

4. Deploy via Chef Automate or run directly against nodes

Environment Variables and Shell Configuration

I add Chef Workstation to my shell for convenience:

For Zsh (macOS default)

# Add to ~/.zshrc
cat >> ~/.zshrc << 'EOF'

# Chef Workstation
eval "$(chef shell-init zsh)"

# Chef environment variables
export CHEF_REPO="$HOME/chef-repo"

# Helpful aliases
alias kc='kitchen converge'
alias kv='kitchen verify'
alias kt='kitchen test'
alias kd='kitchen destroy'
alias csu='chef cookbook site upload'

EOF

# Reload shell
source ~/.zshrc

For Bash (Linux)

# Add to ~/.bashrc
cat >> ~/.bashrc << 'EOF'

# Chef Workstation
eval "$(chef shell-init bash)"

# Chef environment variables
export CHEF_REPO="$HOME/chef-repo"

EOF

# Reload shell
source ~/.bashrc

Creating Your First Cookbook

Let's verify everything works by creating a simple cookbook:

# Generate cookbook
cd ~/chef-repo/cookbooks
chef generate cookbook webserver

# View structure
tree webserver

Generated Structure:

webserver/
├── CHANGELOG.md
├── LICENSE
├── Policyfile.rb
├── README.md
├── chefignore
├── kitchen.yml
├── metadata.rb
├── recipes/
│   └── default.rb
└── test/
    └── integration/
        └── default/
            └── default_test.rb

Writing a Simple Recipe

Edit recipes/default.rb:

#
# Cookbook:: webserver
# Recipe:: default
#

# Install nginx
package 'nginx' do
  action :install
end

# Ensure service is running
service 'nginx' do
  action [:enable, :start]
end

# Deploy custom index page
file '/var/www/html/index.html' do
  content '<h1>Hello from Chef!</h1>'
  mode '0644'
  owner 'www-data'
  group 'www-data'
end

Testing the Cookbook

# Test locally with Test Kitchen
cd ~/chef-repo/cookbooks/webserver

# Converge
kitchen converge

# Verify nginx is installed and running
kitchen login
curl localhost
exit

# Clean up
kitchen destroy

Validating Your Setup

Run these commands to ensure everything is configured correctly:

# Check Chef Workstation
chef --version

# Check InSpec
inspec version

# Check knife configuration
knife client list

# Check Test Kitchen
kitchen version

# Check Cookstyle
cookstyle --version

# Run Cookstyle on a cookbook
cd ~/chef-repo/cookbooks/webserver
cookstyle .

Best Practices from My Experience

Version Control Everything

# Always commit changes
git add .
git commit -m "Add webserver cookbook"
git push origin main

Use Berkshelf for Dependencies

# In Berksfile
source 'https://supermarket.chef.io'

metadata

cookbook 'nginx', '~> 10.0'
cookbook 'apt', '~> 7.0'

Keep Secrets Secure

# Never commit these files
echo ".chef/*.pem" >> .gitignore
echo ".chef/encrypted_data_bag_secret" >> .gitignore

Test Before Uploading

# Always test locally first
kitchen test

# Then upload to Chef Server
knife cookbook upload webserver

Common Setup Issues I've Encountered

Issue: SSL Certificate Errors

# Solution: Fetch SSL certificates
knife ssl fetch

Issue: Permission Denied for .pem Files

# Solution: Fix permissions
chmod 600 ~/.chef/*.pem

Issue: Test Kitchen Can't Find Driver

# Solution: Install required driver
chef gem install kitchen-vagrant
# or
chef gem install kitchen-docker

Issue: Cookstyle Fails with Ruby Version Error

# Solution: Use Chef's embedded Ruby
chef exec cookstyle .

Next Steps: Start Building

Your Chef Workstation is now configured and ready for automation development. You have:

✅ Chef Workstation installed and verified ✅ Connection to Chef Server configured ✅ Test Kitchen set up for local testing ✅ InSpec ready for compliance automation ✅ First cookbook created and tested ✅ Development workflow established

What's Next?

Now that your workstation is configured, you're ready to dive deep into Chef automation. Continue to Chef Infra Fundamentals to master cookbooks, recipes, resources, and the patterns that make Chef powerful.

The investment in a proper development environment pays dividends in productivity and reliability. Let's start building real automation!

---

Ready to master Chef cookbooks? Continue to Chef Infra Fundamentals