Prerequisites Explore the Starter Kit Contents Set Up Your Chef Repository Use Policyfile.rb to Get Cookbooks from a Remote Source (Alternate) Use Berkshelf to Get Cookbooks from a Remote Source (Optional) Configure knife to Work with a Custom Domain

Configure the Chef Server Using the Starter Kit

Important

AWS OpsWorks for Chef Automate reached end of life on May 5, 2024 and has been disabled for both new and existing customers. We recommend that existing customers migrate to Chef SaaS or an alternative solution. If you have questions, you can reach out to the AWS Support Team on AWS re:Post or through AWS Premium Support.

While Chef server creation is still in progress, open its Properties page in the AWS OpsWorks for Chef Automate console. The first time that you work with a new Chef server, the Properties page prompts you to download two required items. Download these items before your Chef server is online; the download buttons are not available after a new server is online.

AWS OpsWorks for Chef Automate new server properties page

Sign-in credentials for the Chef server. You will use these credentials to sign in to the Chef Automate dashboard, where you work with Chef Automate premium features, such as workflow and compliance scans. AWS OpsWorks does not save these credentials; this is the last time that they are available for viewing and downloading. If necessary, you can change the password that is provided with these credentials after you sign in.
Starter Kit. The Starter Kit contains a README file with examples, a knife.rb configuration file, and a private key for the primary, or pivotal, user. A new key pair is generated—and the old key is reset—each time you download the Starter Kit.

In addition to the credentials that work only with the new server, the Starter Kit .zip file includes a simple example of a Chef repository that works with any AWS OpsWorks for Chef Automate server. In the Chef repository, you store cookbooks, roles, configuration files, and other artifacts for managing your nodes with Chef. We recommend that you store this repository in a version control system, such as Git, and treat it as source code. For information and examples that show how to set up a Chef repository that is tracked in Git, see About the chef-repo in the Chef documentation.

Prerequisites

While server creation is still in progress, download the sign-in credentials for the Chef server, and save them in a secure but convenient location.
Download the Starter Kit, and unzip the Starter Kit .zip file into your workspace directory. Do not share the Starter Kit private key. If other users will be managing the Chef server, add them as administrators in the Chef Automate dashboard later.
Download and install Chef Workstation (formerly known as the Chef Development Kit, or Chef DK) on the computer you will use to manage your Chef server and nodes. The knife utility is part of Chef Workstation. For instructions, see Install Chef Workstation on the Chef website.

Explore the Starter Kit Contents

The Starter Kit has the following contents.

cookbooks/ - A directory for cookbooks that you create. The cookbooks/ folder contains the opsworks-webserver cookbook, a wrapper cookbook that depends on the nginx cookbook from the Chef Supermarket website. Policyfile.rb defaults to Chef supermarket as a secondary source if cookbook dependencies are not available in the cookbooks/ directory.
Policyfile.rb - A Ruby-based policy file that defines the cookbooks, dependencies, and attributes that become the policy for your nodes.
userdata.sh and userdata.ps1 - You can use user data files to associate nodes automatically after launching your Chef Automate server. userdata.sh is for bootstrapping Linux-based nodes, and userdata.ps1 is for Windows-based nodes.
Berksfile - You can use this file if you prefer to use Berkshelf and berks commands to upload cookbooks and their dependencies. In this walkthrough, we use Policyfile.rb and Chef commands to upload cookbooks, dependencies, and attributes.
README.md, a Markdown-based file that describes how to use the Starter Kit to set up your Chef Automate server for the first time.
.chef is a hidden directory that contains a knife configuration file (knife.rb) and a secret authentication key file (.pem).
- .chef/knife.rb - A knife configuration file (knife.rb). The knife.rb file is configured so that Chef's knife tool operations run against the AWS OpsWorks for Chef Automate server.
- .chef/ca_certs/opsworks-cm-ca-2020-root.pem - A certification authority (CA)-signed SSL private key that is provided by AWS OpsWorks. This key allows the server to identify itself to the Chef Infra client agent on nodes that your server manages.

Set Up Your Chef Repository

A Chef repository contains several directories. Each directory in the Starter Kit contains a README file that describes the directory's purpose, and how to use it for managing your systems with Chef. There are two ways to get cookbooks installed on your Chef server: running knife commands, or running a Chef command to upload a policy file (Policyfile.rb) to your server that downloads and installs specified cookbooks. This walkthrough uses Chef commands and Policyfile.rb to install cookbooks on your server.

Create a directory on your local computer for storing cookbooks, such as chef-repo. After you add cookbooks, roles, and other files to this repository, we recommend that you upload or store it in a secure, versioned system, such as CodeCommit, Git, or Amazon S3.
In the chef-repo directory, create the following directories:
- cookbooks/ - Stores cookbooks.
- roles/ - Stores roles in .rb or .json formats.
- environments/ - Stores environments in .rb or .json formats.

Use Policyfile.rb to Get Cookbooks from a Remote Source

In this section, edit Policyfile.rb to specify cookbooks, then run a Chef command to upload the file to your server and install cookbooks.

View Policyfile.rb in your Starter Kit. By default, Policyfile.rb includes the opsworks-webserver wrapper cookbook , which depends on the nginx cookbook available on the Chef Supermarket website. The nginx cookbook installs and configures a web server on managed nodes. The required chef-client cookbook, which installs the Chef Infra client agent on managed nodes, is also specified.

Policyfile.rb also points to the optional Chef Audit cookbook, which you can use to set up compliance scans on nodes. For more information about setting up compliance scans and getting compliance results for managed nodes, see Compliance Scans in AWS OpsWorks for Chef Automate. If you do not want to configure compliance scans and auditing right now, delete 'audit' from the run_list section, and do not specify the audit cookbook attributes at the end of the file.


# Policyfile.rb - Describe how you want Chef to build your system.
#                 
# For more information about the Policyfile feature, visit                                             
# https://docs.chef.io/policyfile.html                                                                 

# A name that describes what the system you're building with Chef does.                                
name 'opsworks-demo-webserver'

# The cookbooks directory is the preferred source for external cookbooks                               
default_source :chef_repo, "cookbooks/" do |s|                                                         
  s.preferred_for "nginx", "windows", "chef-client", "yum-epel", "seven_zip",  
                  "build-essential", "mingw", "ohai", "audit", "logrotate", "cron"                     
end
# Alternative source 
default_source :supermarket                                                                            

# run_list: chef-client runs these recipes in the order specified.                                 
run_list  'chef-client',
          'opsworks-webserver',
          'audit'
# add 'ssh-hardening' to your runlist to fix compliance issues detected by the ssh-baseline profile    

# Specify a custom source for a single cookbook:                                                       
cookbook 'opsworks-webserver', path: 'cookbooks/opsworks-webserver'                               

# Policyfile defined attributes

# Define audit cookbook attributes
default["opsworks-demo"]["audit"]["reporter"] = "chef-server-automate"
default["opsworks-demo"]["audit"]["profiles"] = [
  {
    "name": "DevSec SSH Baseline",
    "compliance": "admin/ssh-baseline"
  }
]

The following is an example of Policyfile.rb without the audit cookbook and attributes, if you want to configure only the nginx web server for now.


# Policyfile.rb - Describe how you want Chef to build your system.
#
# For more information on the Policyfile feature, visit
# https://docs.chef.io/policyfile.html

# A name that describes what the system you're building with Chef does.
name 'opsworks-demo-webserver'

# Where to find external cookbooks:
default_source :supermarket

# run_list: chef-client will run these recipes in the order specified.
run_list  'chef-client',
          'opsworks-webserver'

# Specify a custom source for a single cookbook:
cookbook 'opsworks-webserver', path: 'cookbooks/opsworks-webserver'

If you make changes to Policyfile.rb, be sure to save the file.

Download and install the cookbooks defined in Policyfile.rb.
```
chef install
```
All cookbooks are versioned in the cookbook's metadata.rb file. Each time you change a cookbook, you must raise the version of the cookbook that is in its metadata.rb.
If you have chosen to configure compliance scans, and kept the audit cookbook information in the policy file, push the policy opsworks-demo to your server.
```
chef push opsworks-demo
```
If you completed step 3, verify the installation of your policy. Run the following command.
```
chef show-policy
```
The results should resemble the following:
```
opsworks-demo-webserver 
======================= 
* opsworks-demo:  ec0fe46314
```
You are now ready to add or bootstrap nodes to your Chef Automate server. You can automate the association of nodes by following steps in Add nodes automatically in AWS OpsWorks for Chef Automate, or add nodes one at a time by following steps in Add nodes individually.

(Alternate) Use Berkshelf to Get Cookbooks from a Remote Source

Berkshelf is a tool for managing cookbooks and their dependencies. If you prefer to use Berkshelf instead of Policyfile.rb to install cookbooks into local storage, use the procedure in this section instead of the preceding section. You can specify which cookbooks and versions to use with your Chef server and upload them. The Starter Kit contains a file named Berksfile that you can use to list your cookbooks.

To get started, add the chef-client cookbook to the included Berksfile. The chef-client cookbook configures the Chef Infra client agent software on each node that you connect to your Chef Automate server. To learn more about this cookbook, see Chef Client Cookbook in the Chef Supermarket.
Using a text editor, append another cookbook to your Berksfile that installs a web server application; for example, the apache2 cookbook, which installs the Apache web server. Your Berksfile should resemble the following.
```
source 'https://supermarket.chef.io'
cookbook 'chef-client'
cookbook 'apache2'
```
Download and install the cookbooks on your local computer.
```
berks install
```
Upload the cookbook to the Chef server.

On Linux, run the following.
```
SSL_CERT_FILE='.chef/ca_certs/opsworks-cm-ca-2020-root.pem' berks upload
```
On Windows, run the following Chef Workstation command in a PowerShell session. Before you run the command, be sure to set the execution policy in PowerShell to RemoteSigned. Add chef shell-init to make Chef Workstation utility commands available to PowerShell.
```
$env:SSL_CERT_FILE="ca_certs\opsworks-cm-ca-2020-root.pem"
chef shell-init berks upload
Remove-Item Env:\SSL_CERT_FILE
```
Verify the installation of the cookbook by showing a list of cookbooks that are currently available on the Chef Automate server. You can do this by running the following knife command.

You are ready to add nodes to manage with the AWS OpsWorks for Chef Automate server.
```
knife cookbook list
```

(Optional) Configure `knife` to Work with a Custom Domain

If your Chef Automate server uses a custom domain, you might need to add the PEM certificate of the root CA that signed your server's certificate chain, or your server PEM certificate if the certificate is self-signed. ca_certs is a subdirectory in chef/ that contains certificate authorities (CAs) that are trusted by the Chef knife utility.

You can skip this section if you aren't using a custom domain, or if your custom certificate is signed by a root CA that is trusted by your operating system. Otherwise, configure knife to trust your Chef Automate server SSL certificate, as described in the following steps.

Run the following command.


knife ssl check

If the results are similar to the following, skip the rest of this procedure, and go on to Add Nodes for the Chef Server to Manage.


Connecting to host my-chef-automate-server.my-corp.com:443
          Successfully verified certificates from 'my-chef-automate-server.my-corp.com'

If you get an error message similar to the following, go on to the next step.


Connecting to host my-chef-automate-server.my-corp.com:443
          ERROR: The SSL certificate of my-chef-automate-server.my-corp.com could not be verified.
          ...

Run knife ssl fetch to trust the certificates of your AWS OpsWorks for Chef Automate server. Alternatively, you can manually copy the root CA PEM-formatted certificate of your server to the directory that is the value of trusted_certs_dir in the output of knife ssl check. By default, this directory is in .chef/ca_certs/ in the Starter Kit. Your output should resemble the following:


WARNING: Certificates from my-chef-automate-server.my-corp.com will be fetched and placed in your trusted_cert
          directory (/Users/username/starterkit/.chef/../.chef/ca_certs).
       
          Knife has no means to verify these are the correct certificates. You should
          verify the authenticity of these certificates after downloading.
       
          Adding certificate for my-chef-automate-server in /Users/users/starterkit/.chef/../.chef/ca_certs/servv-aqtswxu20swzkjgz.crt
          Adding certificate for MyCorp_Root_CA in /Users/users/starterkit/.chef/../.chef/ca_certs/MyCorp_Root_CA.crt

Run knife ssl check again. Your output should resemble the following:


Connecting to host my-chef-automate-server.my-corp.com:443
          Successfully verified certificates from 'my-chef-automate-server.my-corp.com'

You are ready to use knife with your Chef Automate server.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Create a Chef Automate Server

Add nodes to manage