github.com/marksheahan/packer@v0.10.2-0.20160613200515-1acb2d6645a0/website/source/docs/templates/provisioners.html.md (about)

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