github.com/ratanraj/packer@v1.3.2/website/source/docs/provisioners/ansible-local.html.md (about)

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