github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/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  * `client_key` (string) - Path to client key. If not set, this defaults to a file
    92    named client.pem in `staging_directory`.
    93  
    94  * `validation_client_name` (string) - Name of the validation client. If
    95    not set, this won't be set in the configuration and the default that Chef
    96    uses will be used.
    97  
    98  * `validation_key_path` (string) - Path to the validation key for communicating
    99    with the Chef Server. This will be uploaded to the remote machine. If this
   100    is NOT set, then it is your responsibility via other means (shell provisioner,
   101    etc.) to get a validation key to where Chef expects it.
   102  
   103  ## Chef Configuration
   104  
   105  By default, Packer uses a simple Chef configuration file in order to set
   106  the options specified for the provisioner. But Chef is a complex tool that
   107  supports many configuration options. Packer allows you to specify a custom
   108  configuration template if you'd like to set custom configurations.
   109  
   110  The default value for the configuration template is:
   111  
   112  ```liquid
   113  log_level        :info
   114  log_location     STDOUT
   115  chef_server_url  "{{.ServerUrl}}"
   116  validation_client_name "chef-validator"
   117  {{if ne .ValidationKeyPath ""}}
   118  validation_key "{{.ValidationKeyPath}}"
   119  {{end}}
   120  node_name "{{.NodeName}}"
   121  ```
   122  
   123  This template is a [configuration template](/docs/templates/configuration-templates.html)
   124  and has a set of variables available to use:
   125  
   126  * `NodeName` - The node name set in the configuration.
   127  * `ServerUrl` - The URL of the Chef Server set in the configuration.
   128  * `ValidationKeyPath` - Path to the validation key, if it is set.
   129  
   130  ## Execute Command
   131  
   132  By default, Packer uses the following command (broken across multiple lines
   133  for readability) to execute Chef:
   134  
   135  ```liquid
   136  {{if .Sudo}}sudo {{end}}chef-client \
   137    --no-color \
   138    -c {{.ConfigPath}} \
   139    -j {{.JsonPath}}
   140  ```
   141  
   142  This command can be customized using the `execute_command` configuration.
   143  As you can see from the default value above, the value of this configuration
   144  can contain various template variables, defined below:
   145  
   146  * `ConfigPath` - The path to the Chef configuration file.
   147    file.
   148  * `JsonPath` - The path to the JSON attributes file for the node.
   149  * `Sudo` - A boolean of whether to `sudo` the command or not, depending on
   150    the value of the `prevent_sudo` configuration.
   151  
   152  ## Install Command
   153  
   154  By default, Packer uses the following command (broken across multiple lines
   155  for readability) to install Chef. This command can be customized if you want
   156  to install Chef in another way.
   157  
   158  ```text
   159  curl -L https://www.opscode.com/chef/install.sh | \
   160    {{if .Sudo}}sudo{{end}} bash
   161  ```
   162  
   163  This command can be customized using the `install_command` configuration.
   164  
   165  ## Folder Permissions
   166  
   167  !> The `chef-client` provisioner will chmod the directory with your Chef
   168  keys to 777. This is to ensure that Packer can upload and make use of that
   169  directory. However, once the machine is created, you usually don't
   170  want to keep these directories with those permissions. To change the
   171  permissions on the directories, append a shell provisioner after Chef
   172  to modify them.