github.com/aclaygray/packer@v1.3.2/website/source/docs/provisioners/chef-client.html.md (about) 1 --- 2 description: | 3 The chef-client Packer provisioner installs and configures software on 4 machines built by Packer using chef-client. Packer configures a Chef client to 5 talk to a remote Chef Server to provision the machine. 6 layout: docs 7 page_title: 'Chef Client - Provisioners' 8 sidebar_current: 'docs-provisioners-chef-client' 9 --- 10 11 # Chef Client Provisioner 12 13 Type: `chef-client` 14 15 The Chef Client Packer provisioner installs and configures software on machines 16 built by Packer using [chef-client](https://docs.chef.io/chef_client.html). 17 Packer configures a Chef client to talk to a remote Chef Server to provision the 18 machine. 19 20 The provisioner will even install Chef onto your machine if it isn't already 21 installed, using the official Chef installers provided by Chef. 22 23 ## Basic Example 24 25 The example below is fully functional. It will install Chef onto the remote 26 machine and run Chef client. 27 28 ``` json 29 { 30 "type": "chef-client", 31 "server_url": "https://mychefserver.com/" 32 } 33 ``` 34 35 Note: to properly clean up the Chef node and client the machine on which packer 36 is running must have knife on the path and configured globally, i.e, 37 `~/.chef/knife.rb` must be present and configured for the target chef server 38 39 ## Configuration Reference 40 41 The reference of available configuration options is listed below. No 42 configuration is actually required. 43 44 - `chef_environment` (string) - The name of the chef\_environment sent to the 45 Chef server. By default this is empty and will not use an environment. 46 47 - `config_template` (string) - Path to a template that will be used for the 48 Chef configuration file. By default Packer only sets configuration it needs 49 to match the settings set in the provisioner configuration. If you need to 50 set configurations that the Packer provisioner doesn't support, then you 51 should use a custom configuration template. See the dedicated "Chef 52 Configuration" section below for more details. 53 54 - `encrypted_data_bag_secret_path` (string) - The path to the file containing 55 the secret for encrypted data bags. By default, this is empty, so no 56 secret will be available. 57 58 - `execute_command` (string) - The command used to execute Chef. This has 59 various [configuration template 60 variables](/docs/templates/engine.html) available. See 61 below for more information. 62 63 - `guest_os_type` (string) - The target guest OS type, either "unix" or 64 "windows". Setting this to "windows" will cause the provisioner to use 65 Windows friendly paths and commands. By default, this is "unix". 66 67 - `install_command` (string) - The command used to install Chef. This has 68 various [configuration template 69 variables](/docs/templates/engine.html) available. See 70 below for more information. 71 72 - `json` (object) - An arbitrary mapping of JSON that will be available as 73 node attributes while running Chef. 74 75 - `knife_command` (string) - The command used to run Knife during node clean-up. This has 76 various [configuration template 77 variables](/docs/templates/engine.html) available. See 78 below for more information. 79 80 - `node_name` (string) - The name of the node to register with the 81 Chef Server. This is optional and by default is packer-{{uuid}}. 82 83 * `policy_group` (string) - The name of a policy group that exists on the 84 Chef server. `policy_name` must also be specified. 85 86 * `policy_name` (string) - The name of a policy, as identified by the name 87 setting in a `Policyfile.rb` file. `policy_group` must also be specified. 88 89 - `prevent_sudo` (boolean) - By default, the configured commands that are 90 executed to install and run Chef are executed with `sudo`. If this is true, 91 then the sudo will be omitted. This has no effect when guest\_os\_type is 92 windows. 93 94 - `run_list` (array of strings) - The [run 95 list](http://docs.chef.io/essentials_node_object_run_lists.html) for Chef. 96 By default this is empty, and will use the run list sent down by the 97 Chef Server. 98 99 - `server_url` (string) - The URL to the Chef server. This is required. 100 101 - `skip_clean_client` (boolean) - If true, Packer won't remove the client from 102 the Chef server after it is done running. By default, this is false. 103 104 - `skip_clean_node` (boolean) - If true, Packer won't remove the node from the 105 Chef server after it is done running. By default, this is false. 106 107 - `skip_clean_staging_directory` (boolean) - If true, Packer won't remove the Chef staging 108 directory from the machine after it is done running. By default, this is false. 109 110 - `skip_install` (boolean) - If true, Chef will not automatically be installed 111 on the machine using the Chef omnibus installers. 112 113 - `ssl_verify_mode` (string) - Set to "verify\_none" to skip validation of 114 SSL certificates. If not set, this defaults to "verify\_peer" which validates 115 all SSL certifications. 116 117 - `trusted_certs_dir` (string) - This is a directory that contains additional 118 SSL certificates to trust. Any certificates in this directory will be added to 119 whatever CA bundle ruby is using. Use this to add self-signed certs for your 120 Chef Server or local HTTP file servers. 121 122 - `staging_directory` (string) - This is the directory where all the 123 configuration of Chef by Packer will be placed. By default this is 124 "/tmp/packer-chef-client" when guest\_os\_type unix and 125 "$env:TEMP/packer-chef-client" when windows. This directory doesn't need to 126 exist but must have proper permissions so that the user that Packer uses is 127 able to create directories and write into this folder. By default the 128 provisioner will create and chmod 0777 this directory. 129 130 - `client_key` (string) - Path to client key. If not set, this defaults to a 131 file named client.pem in `staging_directory`. 132 133 - `validation_client_name` (string) - Name of the validation client. If not 134 set, this won't be set in the configuration and the default that Chef uses 135 will be used. 136 137 - `validation_key_path` (string) - Path to the validation key for 138 communicating with the Chef Server. This will be uploaded to the 139 remote machine. If this is NOT set, then it is your responsibility via other 140 means (shell provisioner, etc.) to get a validation key to where Chef 141 expects it. 142 143 ## Chef Configuration 144 145 By default, Packer uses a simple Chef configuration file in order to set the 146 options specified for the provisioner. But Chef is a complex tool that supports 147 many configuration options. Packer allows you to specify a custom configuration 148 template if you'd like to set custom configurations. 149 150 The default value for the configuration template is: 151 152 ``` liquid 153 log_level :info 154 log_location STDOUT 155 chef_server_url "{{.ServerUrl}}" 156 client_key "{{.ClientKey}}" 157 {{if ne .EncryptedDataBagSecretPath ""}} 158 encrypted_data_bag_secret "{{.EncryptedDataBagSecretPath}}" 159 {{end}} 160 {{if ne .ValidationClientName ""}} 161 validation_client_name "{{.ValidationClientName}}" 162 {{else}} 163 validation_client_name "chef-validator" 164 {{end}} 165 {{if ne .ValidationKeyPath ""}} 166 validation_key "{{.ValidationKeyPath}}" 167 {{end}} 168 node_name "{{.NodeName}}" 169 {{if ne .ChefEnvironment ""}} 170 environment "{{.ChefEnvironment}}" 171 {{end}} 172 {{if ne .PolicyGroup ""}} 173 policy_group "{{.PolicyGroup}}" 174 {{end}} 175 {{if ne .PolicyName ""}} 176 policy_name "{{.PolicyName}}" 177 {{end}} 178 {{if ne .SslVerifyMode ""}} 179 ssl_verify_mode :{{.SslVerifyMode}} 180 {{end}} 181 {{if ne .TrustedCertsDir ""}} 182 trusted_certs_dir :{{.TrustedCertsDir}} 183 {{end}} 184 ``` 185 186 This template is a [configuration 187 template](/docs/templates/engine.html) and has a set of 188 variables available to use: 189 190 - `ChefEnvironment` - The Chef environment name. 191 - `EncryptedDataBagSecretPath` - The path to the secret key file to decrypt 192 encrypted data bags. 193 - `NodeName` - The node name set in the configuration. 194 - `ServerUrl` - The URL of the Chef Server set in the configuration. 195 - `SslVerifyMode` - Whether Chef SSL verify mode is on or off. 196 - `TrustedCertsDir` - Path to dir with trusted certificates. 197 - `ValidationClientName` - The name of the client used for validation. 198 - `ValidationKeyPath` - Path to the validation key, if it is set. 199 200 ## Execute Command 201 202 By default, Packer uses the following command (broken across multiple lines for 203 readability) to execute Chef: 204 205 ``` liquid 206 {{if .Sudo}}sudo {{end}}chef-client \ 207 --no-color \ 208 -c {{.ConfigPath}} \ 209 -j {{.JsonPath}} 210 ``` 211 212 When guest\_os\_type is set to "windows", Packer uses the following command to 213 execute Chef. The full path to Chef is required because the PATH environment 214 variable changes don't immediately propagate to running processes. 215 216 ``` liquid 217 c:/opscode/chef/bin/chef-client.bat \ 218 --no-color \ 219 -c {{.ConfigPath}} \ 220 -j {{.JsonPath}} 221 ``` 222 223 This command can be customized using the `execute_command` configuration. As you 224 can see from the default value above, the value of this configuration can 225 contain various template variables, defined below: 226 227 - `ConfigPath` - The path to the Chef configuration file. 228 - `JsonPath` - The path to the JSON attributes file for the node. 229 - `Sudo` - A boolean of whether to `sudo` the command or not, depending on the 230 value of the `prevent_sudo` configuration. 231 232 ## Install Command 233 234 By default, Packer uses the following command (broken across multiple lines for 235 readability) to install Chef. This command can be customized if you want to 236 install Chef in another way. 237 238 ``` text 239 curl -L https://omnitruck.chef.io/chef/install.sh | \ 240 {{if .Sudo}}sudo{{end}} bash 241 ``` 242 243 When guest\_os\_type is set to "windows", Packer uses the following command to 244 install the latest version of Chef: 245 246 ``` text 247 powershell.exe -Command "(New-Object System.Net.WebClient).DownloadFile('http://chef.io/chef/install.msi', 'C:\\Windows\\Temp\\chef.msi');Start-Process 'msiexec' -ArgumentList '/qb /i C:\\Windows\\Temp\\chef.msi' -NoNewWindow -Wait" 248 ``` 249 250 This command can be customized using the `install_command` configuration. 251 252 ## Knife Command 253 254 By default, Packer uses the following command (broken across multiple lines for 255 readability) to execute Chef: 256 257 ``` liquid 258 {{if .Sudo}}sudo {{end}}knife \ 259 {{.Args}} \ 260 {{.Flags}} 261 ``` 262 263 When guest\_os\_type is set to "windows", Packer uses the following command to 264 execute Chef. The full path to Chef is required because the PATH environment 265 variable changes don't immediately propagate to running processes. 266 267 ``` liquid 268 c:/opscode/chef/bin/knife.bat \ 269 {{.Args}} \ 270 {{.Flags}} 271 ``` 272 273 This command can be customized using the `knife_command` configuration. As you 274 can see from the default value above, the value of this configuration can 275 contain various template variables, defined below: 276 277 - `Args` - The command arguments that are getting passed to the Knife command. 278 - `Flags` - The command flags that are getting passed to the Knife command.. 279 - `Sudo` - A boolean of whether to `sudo` the command or not, depending on the 280 value of the `prevent_sudo` configuration. 281 282 ## Folder Permissions 283 284 !> The `chef-client` provisioner will chmod the directory with your Chef keys 285 to 777. This is to ensure that Packer can upload and make use of that directory. 286 However, once the machine is created, you usually don't want to keep these 287 directories with those permissions. To change the permissions on the 288 directories, append a shell provisioner after Chef to modify them. 289 290 ## Examples 291 292 ### Chef Client Local Mode - Simple 293 294 The following example shows how to run the `chef-client` provisioner in local 295 mode. 296 297 **Packer variables** 298 299 Set the necessary Packer variables using environment variables or provide a [var 300 file](/docs/templates/user-variables.html). 301 302 ``` json 303 "variables": { 304 "chef_dir": "/tmp/packer-chef-client" 305 } 306 ``` 307 308 **Setup the** `chef-client` **provisioner** 309 310 Make sure we have the correct directories and permissions for the `chef-client` 311 provisioner. You will need to bootstrap the Chef run by providing the necessary 312 cookbooks using Berkshelf or some other means. 313 314 ``` json 315 "provisioners": [ 316 ... 317 { "type": "shell", "inline": [ "mkdir -p {{user `chef_dir`}}" ] }, 318 { "type": "file", "source": "./roles", "destination": "{{user `chef_dir`}}" }, 319 { "type": "file", "source": "./cookbooks", "destination": "{{user `chef_dir`}}" }, 320 { "type": "file", "source": "./data_bags", "destination": "{{user `chef_dir`}}" }, 321 { "type": "file", "source": "./environments", "destination": "{{user `chef_dir`}}" }, 322 { "type": "file", "source": "./scripts/install_chef.sh", "destination": "{{user `chef_dir`}}/install_chef.sh" }, 323 { 324 "type": "chef-client", 325 "install_command": "sudo bash {{user `chef_dir`}}/install_chef.sh", 326 "server_url": "http://localhost:8889", 327 "config_template": "./config/client.rb.template", 328 "run_list": [ "role[testing]" ], 329 "skip_clean_node": true, 330 "skip_clean_client": true 331 } 332 ... 333 ] 334 ``` 335 336 And ./config/client.rb.template referenced by the above configuration: 337 338 ```ruby 339 log_level :info 340 log_location STDOUT 341 local_mode true 342 chef_zero.enabled true 343 ssl_verify_mode "verify_peer" 344 role_path "{{user `chef_dir`}}/roles" 345 data_bag_path "{{user `chef_dir`}}/data_bags" 346 environment_path "{{user `chef_dir`}}/environments" 347 cookbook_path [ "{{user `chef_dir`}}/cookbooks" ] 348 ``` 349 350 ### Chef Client Local Mode - Passing variables 351 352 The following example shows how to run the `chef-client` provisioner in local 353 mode, while passing a `run_list` using a variable. 354 355 **Local environment variables** 356 357 # Machine's Chef directory 358 export PACKER_CHEF_DIR=/var/chef-packer 359 # Comma separated run_list 360 export PACKER_CHEF_RUN_LIST="recipe[apt],recipe[nginx]" 361 362 **Packer variables** 363 364 Set the necessary Packer variables using environment variables or provide a [var 365 file](/docs/templates/user-variables.html). 366 367 ``` json 368 "variables": { 369 "chef_dir": "{{env `PACKER_CHEF_DIR`}}", 370 "chef_run_list": "{{env `PACKER_CHEF_RUN_LIST`}}", 371 "chef_client_config_tpl": "{{env `PACKER_CHEF_CLIENT_CONFIG_TPL`}}", 372 "packer_chef_bootstrap_dir": "{{env `PACKER_CHEF_BOOTSTRAP_DIR`}}" , 373 "packer_uid": "{{env `PACKER_UID`}}", 374 "packer_gid": "{{env `PACKER_GID`}}" 375 } 376 ``` 377 378 **Setup the** `chef-client` **provisioner** 379 380 Make sure we have the correct directories and permissions for the `chef-client` 381 provisioner. You will need to bootstrap the Chef run by providing the necessary 382 cookbooks using Berkshelf or some other means. 383 384 ``` json 385 { 386 "type": "file", 387 "source": "{{user `packer_chef_bootstrap_dir`}}", 388 "destination": "/tmp/bootstrap" 389 }, 390 { 391 "type": "shell", 392 "inline": [ 393 "sudo mkdir -p {{user `chef_dir`}}", 394 "sudo mkdir -p /tmp/packer-chef-client", 395 "sudo chown {{user `packer_uid`}}.{{user `packer_gid`}} /tmp/packer-chef-client", 396 "sudo sh /tmp/bootstrap/bootstrap.sh" 397 ] 398 }, 399 { 400 "type": "chef-client", 401 "server_url": "http://localhost:8889", 402 "config_template": "{{user `chef_client_config_tpl`}}/client.rb.tpl", 403 "skip_clean_node": true, 404 "skip_clean_client": true, 405 "run_list": "{{user `chef_run_list`}}" 406 } 407 ```