github.com/mmcquillan/packer@v1.1.1-0.20171009221028-c85cf0483a5d/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  -   `prevent_sudo` (boolean) - By default, the configured commands that are
    84      executed to install and run Chef are executed with `sudo`. If this is true,
    85      then the sudo will be omitted. This has no effect when guest\_os\_type is
    86      windows.
    87  
    88  -   `run_list` (array of strings) - The [run
    89      list](http://docs.chef.io/essentials_node_object_run_lists.html) for Chef.
    90      By default this is empty, and will use the run list sent down by the
    91      Chef Server.
    92  
    93  -   `server_url` (string) - The URL to the Chef server. This is required.
    94  
    95  -   `skip_clean_client` (boolean) - If true, Packer won't remove the client from
    96      the Chef server after it is done running. By default, this is false.
    97  
    98  -   `skip_clean_node` (boolean) - If true, Packer won't remove the node from the
    99      Chef server after it is done running. By default, this is false.
   100  
   101  -   `skip_install` (boolean) - If true, Chef will not automatically be installed
   102      on the machine using the Chef omnibus installers.
   103  
   104  -   `ssl_verify_mode` (string) - Set to "verify\_none" to skip validation of
   105      SSL certificates. If not set, this defaults to "verify\_peer" which validates
   106      all SSL certifications.
   107  
   108  -   `staging_directory` (string) - This is the directory where all the
   109      configuration of Chef by Packer will be placed. By default this is
   110      "/tmp/packer-chef-client" when guest\_os\_type unix and
   111      "$env:TEMP/packer-chef-client" when windows. This directory doesn't need to
   112      exist but must have proper permissions so that the user that Packer uses is
   113      able to create directories and write into this folder. By default the
   114      provisioner will create and chmod 0777 this directory.
   115  
   116  -   `client_key` (string) - Path to client key. If not set, this defaults to a
   117      file named client.pem in `staging_directory`.
   118  
   119  -   `validation_client_name` (string) - Name of the validation client. If not
   120      set, this won't be set in the configuration and the default that Chef uses
   121      will be used.
   122  
   123  -   `validation_key_path` (string) - Path to the validation key for
   124      communicating with the Chef Server. This will be uploaded to the
   125      remote machine. If this is NOT set, then it is your responsibility via other
   126      means (shell provisioner, etc.) to get a validation key to where Chef
   127      expects it.
   128  
   129  ## Chef Configuration
   130  
   131  By default, Packer uses a simple Chef configuration file in order to set the
   132  options specified for the provisioner. But Chef is a complex tool that supports
   133  many configuration options. Packer allows you to specify a custom configuration
   134  template if you'd like to set custom configurations.
   135  
   136  The default value for the configuration template is:
   137  
   138  ``` liquid
   139  log_level        :info
   140  log_location     STDOUT
   141  chef_server_url  "{{.ServerUrl}}"
   142  client_key       "{{.ClientKey}}"
   143  {{if ne .EncryptedDataBagSecretPath ""}}
   144  encrypted_data_bag_secret "{{.EncryptedDataBagSecretPath}}"
   145  {{end}}
   146  {{if ne .ValidationClientName ""}}
   147  validation_client_name "{{.ValidationClientName}}"
   148  {{else}}
   149  validation_client_name "chef-validator"
   150  {{end}}
   151  {{if ne .ValidationKeyPath ""}}
   152  validation_key "{{.ValidationKeyPath}}"
   153  {{end}}
   154  node_name "{{.NodeName}}"
   155  {{if ne .ChefEnvironment ""}}
   156  environment "{{.ChefEnvironment}}"
   157  {{end}}
   158  {{if ne .SslVerifyMode ""}}
   159  ssl_verify_mode :{{.SslVerifyMode}}
   160  {{end}}
   161  ```
   162  
   163  This template is a [configuration
   164  template](/docs/templates/engine.html) and has a set of
   165  variables available to use:
   166  
   167  -   `ChefEnvironment` - The Chef environment name.
   168  -   `EncryptedDataBagSecretPath` - The path to the secret key file to decrypt
   169      encrypted data bags.
   170  -   `NodeName` - The node name set in the configuration.
   171  -   `ServerUrl` - The URL of the Chef Server set in the configuration.
   172  -   `SslVerifyMode` - Whether Chef SSL verify mode is on or off.
   173  -   `ValidationClientName` - The name of the client used for validation.
   174  -   `ValidationKeyPath` - Path to the validation key, if it is set.
   175  
   176  ## Execute Command
   177  
   178  By default, Packer uses the following command (broken across multiple lines for
   179  readability) to execute Chef:
   180  
   181  ``` liquid
   182  {{if .Sudo}}sudo {{end}}chef-client \
   183    --no-color \
   184    -c {{.ConfigPath}} \
   185    -j {{.JsonPath}}
   186  ```
   187  
   188  When guest\_os\_type is set to "windows", Packer uses the following command to
   189  execute Chef. The full path to Chef is required because the PATH environment
   190  variable changes don't immediately propagate to running processes.
   191  
   192  ``` liquid
   193  c:/opscode/chef/bin/chef-client.bat \
   194    --no-color \
   195    -c {{.ConfigPath}} \
   196    -j {{.JsonPath}}
   197  ```
   198  
   199  This command can be customized using the `execute_command` configuration. As you
   200  can see from the default value above, the value of this configuration can
   201  contain various template variables, defined below:
   202  
   203  -   `ConfigPath` - The path to the Chef configuration file.
   204  -   `JsonPath` - The path to the JSON attributes file for the node.
   205  -   `Sudo` - A boolean of whether to `sudo` the command or not, depending on the
   206      value of the `prevent_sudo` configuration.
   207  
   208  ## Install Command
   209  
   210  By default, Packer uses the following command (broken across multiple lines for
   211  readability) to install Chef. This command can be customized if you want to
   212  install Chef in another way.
   213  
   214  ``` text
   215  curl -L https://www.chef.io/chef/install.sh | \
   216    {{if .Sudo}}sudo{{end}} bash
   217  ```
   218  
   219  When guest\_os\_type is set to "windows", Packer uses the following command to
   220  install the latest version of Chef:
   221  
   222  ``` text
   223  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"
   224  ```
   225  
   226  This command can be customized using the `install_command` configuration.
   227  
   228  ## Knife Command
   229  
   230  By default, Packer uses the following command (broken across multiple lines for
   231  readability) to execute Chef:
   232  
   233  ``` liquid
   234  {{if .Sudo}}sudo {{end}}knife \
   235    {{.Args}} \
   236    {{.Flags}}
   237  ```
   238  
   239  When guest\_os\_type is set to "windows", Packer uses the following command to
   240  execute Chef. The full path to Chef is required because the PATH environment
   241  variable changes don't immediately propagate to running processes.
   242  
   243  ``` liquid
   244  c:/opscode/chef/bin/knife.bat \
   245    {{.Args}} \
   246    {{.Flags}}
   247  ```
   248  
   249  This command can be customized using the `knife_command` configuration. As you
   250  can see from the default value above, the value of this configuration can
   251  contain various template variables, defined below:
   252  
   253  -   `Args` - The command arguments that are getting passed to the Knife command.
   254  -   `Flags` - The command flags that are getting passed to the Knife command..
   255  -   `Sudo` - A boolean of whether to `sudo` the command or not, depending on the
   256      value of the `prevent_sudo` configuration.
   257  
   258  ## Folder Permissions
   259  
   260  !> The `chef-client` provisioner will chmod the directory with your Chef keys
   261  to 777. This is to ensure that Packer can upload and make use of that directory.
   262  However, once the machine is created, you usually don't want to keep these
   263  directories with those permissions. To change the permissions on the
   264  directories, append a shell provisioner after Chef to modify them.
   265  
   266  ## Examples
   267  
   268  ### Chef Client Local Mode
   269  
   270  The following example shows how to run the `chef-client` provisioner in local
   271  mode, while passing a `run_list` using a variable.
   272  
   273  **Local environment variables**
   274  
   275      # Machines Chef directory
   276      export PACKER_CHEF_DIR=/var/chef-packer
   277      # Comma separated run_list
   278      export PACKER_CHEF_RUN_LIST="recipe[apt],recipe[nginx]"
   279  
   280  **Packer variables**
   281  
   282  Set the necessary Packer variables using environment variables or provide a [var
   283  file](/docs/templates/user-variables.html).
   284  
   285  ``` json
   286  "variables": {
   287    "chef_dir": "{{env `PACKER_CHEF_DIR`}}",
   288    "chef_run_list": "{{env `PACKER_CHEF_RUN_LIST`}}",
   289    "chef_client_config_tpl": "{{env `PACKER_CHEF_CLIENT_CONFIG_TPL`}}",
   290    "packer_chef_bootstrap_dir": "{{env `PACKER_CHEF_BOOTSTRAP_DIR`}}" ,
   291    "packer_uid": "{{env `PACKER_UID`}}",
   292    "packer_gid": "{{env `PACKER_GID`}}"
   293  }
   294  ```
   295  
   296  **Setup the** `chef-client` **provisioner**
   297  
   298  Make sure we have the correct directories and permissions for the `chef-client`
   299  provisioner. You will need to bootstrap the Chef run by providing the necessary
   300  cookbooks using Berkshelf or some other means.
   301  
   302  ``` json
   303  {
   304    "type": "file",
   305    "source": "{{user `packer_chef_bootstrap_dir`}}",
   306    "destination": "/tmp/bootstrap"
   307  },
   308  {
   309    "type": "shell",
   310    "inline": [
   311      "sudo mkdir -p {{user `chef_dir`}}",
   312      "sudo mkdir -p /tmp/packer-chef-client",
   313      "sudo chown {{user `packer_uid`}}.{{user `packer_gid`}} /tmp/packer-chef-client",
   314      "sudo sh /tmp/bootstrap/bootstrap.sh"
   315    ]
   316  },
   317  {
   318    "type": "chef-client",
   319    "server_url": "http://localhost:8889",
   320    "config_template": "{{user `chef_client_config_tpl`}}/client.rb.tpl",
   321    "skip_clean_node": true,
   322    "skip_clean_client": true,
   323    "run_list": "{{user `chef_run_list`}}"
   324  }
   325  ```