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