github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/templates/provisioners.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Templates: Provisioners"
     4  description: |-
     5    Within the template, the provisioners section contains an array of all the provisioners that Packer should use to install and configure software within running machines prior to turning them into machine images.
     6  ---
     7  
     8  # Templates: Provisioners
     9  
    10  Within the template, the provisioners section contains an array of all the
    11  provisioners that Packer should use to install and configure software within
    12  running machines prior to turning them into machine images.
    13  
    14  Provisioners are _optional_. If no provisioners are defined within a template,
    15  then no software other than the defaults will be installed within the
    16  resulting machine images. This is not typical, however, since much of the
    17  value of Packer is to produce multiple identical images
    18  of pre-configured software.
    19  
    20  This documentation page will cover how to configure a provisioner in a template.
    21  The specific configuration options available for each provisioner, however,
    22  must be referenced from the documentation for that specific provisioner.
    23  
    24  Within a template, a section of provisioner definitions looks like this:
    25  
    26  ```javascript
    27  {
    28    "provisioners": [
    29      // ... one or more provisioner definitions here
    30    ]
    31  }
    32  ```
    33  
    34  For each of the definitions, Packer will run the provisioner for each
    35  of the configured builds. The provisioners will be run in the order
    36  they are defined within the template.
    37  
    38  ## Provisioner Definition
    39  
    40  A provisioner definition is a JSON object that must contain at least
    41  the `type` key. This key specifies the name of the provisioner to use.
    42  Additional keys within the object are used to configure the provisioner,
    43  with the exception of a handful of special keys, covered later.
    44  
    45  As an example, the "shell" provisioner requires a key such as `script`
    46  which specifies a path to a shell script to execute within the machines
    47  being created.
    48  
    49  An example provisioner definition is shown below, configuring the shell
    50  provisioner to run a local script within the machines:
    51  
    52  ```javascript
    53  {
    54    "type": "shell",
    55    "script": "script.sh"
    56  }
    57  ```
    58  
    59  ## Run on Specific Builds
    60  
    61  You can use the `only` or `except` configurations to run a provisioner
    62  only with specific builds. These two configurations do what you expect:
    63  `only` will only run the provisioner on the specified builds and
    64  `except` will run the provisioner on anything other than the specified
    65  builds.
    66  
    67  An example of `only` being used is shown below, but the usage of `except`
    68  is effectively the same:
    69  
    70  ```javascript
    71  {
    72    "type": "shell",
    73    "script": "script.sh",
    74    "only": ["virtualbox-iso"]
    75  }
    76  ```
    77  
    78  The values within `only` or `except` are _build names_, not builder
    79  types. If you recall, build names by default are just their builder type,
    80  but if you specify a custom `name` parameter, then you should use that
    81  as the value instead of the type.
    82  
    83  ## Build-Specific Overrides
    84  
    85  While the goal of Packer is to produce identical machine images, it
    86  sometimes requires periods of time where the machines are different before
    87  they eventually converge to be identical. In these cases, different configurations
    88  for provisioners may be necessary depending on the build. This can be done
    89  using build-specific overrides.
    90  
    91  An example of where this might be necessary is when building both an EC2 AMI
    92  and a VMware machine. The source EC2 AMI may setup a user with administrative
    93  privileges by default, whereas the VMware machine doesn't have these privileges.
    94  In this case, the shell script may need to be executed differently. Of course,
    95  the goal is that hopefully the shell script converges these two images to be
    96  identical. However, they may initially need to be run differently.
    97  
    98  This example is shown below:
    99  
   100  ```javascript
   101  {
   102    "type": "shell",
   103    "script": "script.sh",
   104  
   105    "override": {
   106      "vmware-iso": {
   107        "execute_command": "echo 'password' | sudo -S bash {{.Path}}"
   108      }
   109    }
   110  }
   111  ```
   112  
   113  As you can see, the `override` key is used. The value of this key is another
   114  JSON object where the key is the name of a [builder definition](/docs/templates/builders.html).
   115  The value of this is in turn another JSON object. This JSON object simply
   116  contains the provisioner configuration as normal. This configuration is merged
   117  into the default provisioner configuration.
   118  
   119  ## Pausing Before Running
   120  
   121  With certain provisioners it is sometimes desirable to pause for some period
   122  of time before running it. Specifically, in cases where a provisioner reboots
   123  the machine, you may want to wait for some period of time before starting
   124  the next provisioner.
   125  
   126  Every provisioner definition in a Packer template can take a special
   127  configuration `pause_before` that is the amount of time to pause before
   128  running that provisioner. By default, there is no pause. An example
   129  is shown below:
   130  
   131  ```javascript
   132  {
   133    "type": "shell",
   134    "script": "script.sh",
   135    "pause_before": "10s"
   136  }
   137  ```
   138  
   139  For the above provisioner, Packer will wait 10 seconds before uploading
   140  and executing the shell script.