github.com/mmcquillan/packer@v1.1.1-0.20171009221028-c85cf0483a5d/website/source/docs/provisioners/ansible-local.html.md (about)

     1  ---
     2  description: |
     3      The ansible-local Packer provisioner configures Ansible to run on the
     4      machine by Packer from local Playbook and Role files. Playbooks and Roles can
     5      be uploaded from your local machine to the remote machine.
     6  layout: docs
     7  page_title: 'Ansible Local - Provisioners'
     8  sidebar_current: 'docs-provisioners-ansible-local'
     9  ---
    10  
    11  # Ansible Local Provisioner
    12  
    13  Type: `ansible-local`
    14  
    15  The `ansible-local` Packer provisioner configures Ansible to run on the machine
    16  by Packer from local Playbook and Role files. Playbooks and Roles can be
    17  uploaded from your local machine to the remote machine. Ansible is run in [local
    18  mode](https://docs.ansible.com/ansible/playbooks_delegation.html#local-playbooks) via the
    19  `ansible-playbook` command.
    20  
    21  -> **Note:** Ansible will *not* be installed automatically by this
    22  provisioner. This provisioner expects that Ansible is already installed on the
    23  machine. It is common practice to use the [shell
    24  provisioner](/docs/provisioners/shell.html) before the Ansible provisioner to do
    25  this.
    26  
    27  ## Basic Example
    28  
    29  The example below is fully functional.
    30  
    31  ``` json
    32  {
    33    "type": "ansible-local",
    34    "playbook_file": "local.yml"
    35  }
    36  ```
    37  
    38  ## Configuration Reference
    39  
    40  The reference of available configuration options is listed below.
    41  
    42  Required:
    43  
    44  -   `playbook_file` (string) - The playbook file to be executed by ansible. This
    45      file must exist on your local system and will be uploaded to the
    46      remote machine.
    47  
    48  Optional:
    49  
    50  -   `command` (string) - The command to invoke ansible. Defaults
    51      to "ANSIBLE\_FORCE\_COLOR=1 PYTHONUNBUFFERED=1 ansible-playbook".
    52      Note, This disregards the value of `-color` when passed to `packer build`.
    53      To disable colors, set this to `PYTHONUNBUFFERED=1 ansible-playbook`.
    54  
    55  -   `extra_arguments` (array of strings) - An array of extra arguments to pass
    56      to the ansible command. By default, this is empty. These arguments *will*
    57      be passed through a shell and arguments should be quoted accordingly.
    58      Usage example:
    59  
    60  <!-- -->
    61      "extra_arguments": [ "--extra-vars \"Region={{user `Region`}} Stage={{user `Stage`}}\"" ]
    62  
    63  -   `inventory_groups` (string) - A comma-separated list of groups to which
    64      packer will assign the host `127.0.0.1`. A value of `my_group_1,my_group_2`
    65      will generate an Ansible inventory like:
    66  
    67  ``` text
    68  [my_group_1]
    69  127.0.0.1
    70  [my_group_2]
    71  127.0.0.1
    72  ```
    73  
    74  -   `inventory_file` (string) - The inventory file to be used by ansible. This
    75      file must exist on your local system and will be uploaded to the
    76      remote machine.
    77  
    78  When using an inventory file, it's also required to `--limit` the hosts to the
    79  specified host you're building. The `--limit` argument can be provided in the
    80  `extra_arguments` option.
    81  
    82  An example inventory file may look like:
    83  
    84  ``` text
    85  [chi-dbservers]
    86  db-01 ansible_connection=local
    87  db-02 ansible_connection=local
    88  
    89  [chi-appservers]
    90  app-01 ansible_connection=local
    91  app-02 ansible_connection=local
    92  
    93  [chi:children]
    94  chi-dbservers
    95  chi-appservers
    96  
    97  [dbservers:children]
    98  chi-dbservers
    99  
   100  [appservers:children]
   101  chi-appservers
   102  ```
   103  
   104  -   `playbook_dir` (string) - a path to the complete ansible directory structure
   105      on your local system to be copied to the remote machine as the
   106      `staging_directory` before all other files and directories.
   107  
   108  -   `playbook_paths` (array of strings) - An array of directories of playbook files on
   109      your local system. These will be uploaded to the remote machine under
   110      `staging_directory`/playbooks. By default, this is empty.
   111  
   112  -   `galaxy_file` (string) - A requirements file which provides a way to install
   113      roles with the [ansible-galaxy
   114      cli](http://docs.ansible.com/ansible/galaxy.html#the-ansible-galaxy-command-line-tool)
   115      on the remote machine. By default, this is empty.
   116  
   117  -   `galaxycommand` (string) - The command to invoke ansible-galaxy. 
   118      By default, this is ansible-galaxy.
   119  
   120  -   `group_vars` (string) - a path to the directory containing ansible group
   121      variables on your local system to be copied to the remote machine. By
   122      default, this is empty.
   123  
   124  -   `host_vars` (string) - a path to the directory containing ansible host
   125      variables on your local system to be copied to the remote machine. By
   126      default, this is empty.
   127  
   128  -   `role_paths` (array of strings) - An array of paths to role directories on
   129      your local system. These will be uploaded to the remote machine under
   130      `staging_directory`/roles. By default, this is empty.
   131  
   132  -   `staging_directory` (string) - The directory where all the configuration of
   133      Ansible by Packer will be placed. By default this is
   134      `/tmp/packer-provisioner-ansible-local/<uuid>`, where `<uuid>` is replaced
   135      with a unique ID so that this provisioner can be run more than once. If
   136      you'd like to know the location of the staging directory in advance, you
   137      should set this to a known location. This directory doesn't need to exist
   138      but must have proper permissions so that the SSH user that Packer uses is
   139      able to create directories and write into this folder. If the permissions
   140      are not correct, use a shell provisioner prior to this to configure it
   141      properly.
   142  
   143  ## Default Extra Variables
   144  
   145  In addition to being able to specify extra arguments using the
   146  `extra_arguments` configuration, the provisioner automatically defines certain
   147  commonly useful Ansible variables:
   148  
   149  -   `packer_build_name` is set to the name of the build that Packer is running.
   150      This is most useful when Packer is making multiple builds and you want to
   151      distinguish them slightly when using a common playbook.
   152  
   153  -   `packer_builder_type` is the type of the builder that was used to create the
   154      machine that the script is running on. This is useful if you want to run
   155      only certain parts of the playbook on systems built with certain builders.
   156  
   157  -   `packer_http_addr` If using a builder that provides an http server for file
   158      transfer (such as hyperv, parallels, qemu, virtualbox, and vmware), this
   159      will be set to the address. You can use this address in your provisioner to
   160      download large files over http. This may be useful if you're experiencing
   161      slower speeds using the default file provisioner. A file provisioner using
   162      the `winrm` communicator may experience these types of difficulties.