github.com/daniellockard/packer@v0.7.6-0.20141210173435-5a9390934716/website/source/docs/provisioners/chef-client.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Chef-Client Provisioner"
     4  description: |-
     5    The Chef Client Packer provisioner installs and configures software on machines built by Packer using chef-client. Packer configures a Chef client to talk to a remote Chef Server to provision the machine.
     6  ---
     7  
     8  # Chef Client Provisioner
     9  
    10  Type: `chef-client`
    11  
    12  The Chef Client Packer provisioner installs and configures software on machines built
    13  by Packer using [chef-client](http://docs.opscode.com/chef_client.html).
    14  Packer configures a Chef client to talk to a remote Chef Server to
    15  provision the machine.
    16  
    17  The provisioner will even install Chef onto your machine if it isn't already
    18  installed, using the official Chef installers provided by Opscode.
    19  
    20  ## Basic Example
    21  
    22  The example below is fully functional. It will install Chef onto the
    23  remote machine and run Chef client.
    24  
    25  ```javascript
    26  {
    27    "type": "chef-client",
    28    "server_url": "https://mychefserver.com/"
    29  }
    30  ```
    31  
    32  Note: to properly clean up the Chef node and client the machine on which
    33  packer is running must have knife on the path and configured globally,
    34  i.e, ~/.chef/knife.rb must be present and configured for the target chef server
    35  
    36  ## Configuration Reference
    37  
    38  The reference of available configuration options is listed below. No
    39  configuration is actually required.
    40  
    41  * `chef_environment` (string) - The name of the chef_environment sent to the
    42    Chef server. By default this is empty and will not use an environment.
    43  
    44  * `config_template` (string) - Path to a template that will be used for
    45    the Chef configuration file. By default Packer only sets configuration
    46    it needs to match the settings set in the provisioner configuration. If
    47    you need to set configurations that the Packer provisioner doesn't support,
    48    then you should use a custom configuration template. See the dedicated
    49    "Chef Configuration" section below for more details.
    50  
    51  * `execute_command` (string) - The command used to execute Chef. This has
    52    various [configuration template variables](/docs/templates/configuration-templates.html)
    53    available. See below for more information.
    54  
    55  * `install_command` (string) - The command used to install Chef. This has
    56    various [configuration template variables](/docs/templates/configuration-templates.html)
    57    available. See below for more information.
    58  
    59  * `json` (object) - An arbitrary mapping of JSON that will be available as
    60    node attributes while running Chef.
    61  
    62  * `node_name` (string) - The name of the node to register with the Chef
    63    Server. This is optional and by default is packer-{{uuid}}.
    64  
    65  * `prevent_sudo` (boolean) - By default, the configured commands that are
    66    executed to install and run Chef are executed with `sudo`. If this is true,
    67    then the sudo will be omitted.
    68  
    69  * `run_list` (array of strings) - The [run list](http://docs.opscode.com/essentials_node_object_run_lists.html)
    70    for Chef. By default this is empty, and will use the run list sent
    71    down by the Chef Server.
    72  
    73  * `server_url` (string) - The URL to the Chef server. This is required.
    74  
    75  * `skip_clean_client` (boolean) - If true, Packer won't remove the client
    76    from the Chef server after it is done running. By default, this is false.
    77  
    78  * `skip_clean_node` (boolean) - If true, Packer won't remove the node
    79    from the Chef server after it is done running. By default, this is false.
    80  
    81  * `skip_install` (boolean) - If true, Chef will not automatically be installed
    82    on the machine using the Opscode omnibus installers.
    83  
    84  * `staging_directory` (string) - This is the directory where all the configuration
    85    of Chef by Packer will be placed. By default this is "/tmp/packer-chef-client".
    86    This directory doesn't need to exist but must have proper permissions so that
    87    the SSH user that Packer uses is able to create directories and write into
    88    this folder. If the permissions are not correct, use a shell provisioner
    89    prior to this to configure it properly.
    90  
    91  * `validation_client_name` (string) - Name of the validation client. If
    92    not set, this won't be set in the configuration and the default that Chef
    93    uses will be used.
    94  
    95  * `validation_key_path` (string) - Path to the validation key for communicating
    96    with the Chef Server. This will be uploaded to the remote machine. If this
    97    is NOT set, then it is your responsibility via other means (shell provisioner,
    98    etc.) to get a validation key to where Chef expects it.
    99  
   100  ## Chef Configuration
   101  
   102  By default, Packer uses a simple Chef configuration file in order to set
   103  the options specified for the provisioner. But Chef is a complex tool that
   104  supports many configuration options. Packer allows you to specify a custom
   105  configuration template if you'd like to set custom configurations.
   106  
   107  The default value for the configuration template is:
   108  
   109  ```liquid
   110  log_level        :info
   111  log_location     STDOUT
   112  chef_server_url  "{{.ServerUrl}}"
   113  validation_client_name "chef-validator"
   114  {{if ne .ValidationKeyPath ""}}
   115  validation_key "{{.ValidationKeyPath}}"
   116  {{end}}
   117  node_name "{{.NodeName}}"
   118  ```
   119  
   120  This template is a [configuration template](/docs/templates/configuration-templates.html)
   121  and has a set of variables available to use:
   122  
   123  * `NodeName` - The node name set in the configuration.
   124  * `ServerUrl` - The URL of the Chef Server set in the configuration.
   125  * `ValidationKeyPath` - Path to the validation key, if it is set.
   126  
   127  ## Execute Command
   128  
   129  By default, Packer uses the following command (broken across multiple lines
   130  for readability) to execute Chef:
   131  
   132  ```liquid
   133  {{if .Sudo}}sudo {{end}}chef-client \
   134    --no-color \
   135    -c {{.ConfigPath}} \
   136    -j {{.JsonPath}}
   137  ```
   138  
   139  This command can be customized using the `execute_command` configuration.
   140  As you can see from the default value above, the value of this configuration
   141  can contain various template variables, defined below:
   142  
   143  * `ConfigPath` - The path to the Chef configuration file.
   144    file.
   145  * `JsonPath` - The path to the JSON attributes file for the node.
   146  * `Sudo` - A boolean of whether to `sudo` the command or not, depending on
   147    the value of the `prevent_sudo` configuration.
   148  
   149  ## Install Command
   150  
   151  By default, Packer uses the following command (broken across multiple lines
   152  for readability) to install Chef. This command can be customized if you want
   153  to install Chef in another way.
   154  
   155  ```text
   156  curl -L https://www.opscode.com/chef/install.sh | \
   157    {{if .Sudo}}sudo{{end}} bash
   158  ```
   159  
   160  This command can be customized using the `install_command` configuration.