aherman
/
packer
mirror of https://github.com/hashicorp/packer
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Autogenerated docs for ansible local provisioner (#10829)

Browse Source
pull/10894/head
George Wilson 5 years ago committed by GitHub
parent 8c4eb5f4aa
commit 15a2e59bba
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 234 additions and 144 deletions
Show Stats Download Patch File Download Diff File

140
provisioner/ansible-local/provisioner.go
Unescape View File

@ -1,4 +1,5 @@
//go:generate mapstructure-to-hcl2 -type Config
//go:generate struct-markdown
package ansiblelocal
@ -23,51 +24,126 @@ const DefaultStagingDir = "/tmp/packer-provisioner-ansible-local"
type Config struct {
common.PackerConfig `mapstructure:",squash"`
ctx interpolate.Context
// The command to run ansible
Command string
// Extra options to pass to the ansible command
// The command to invoke ansible. Defaults to
// `ansible-playbook`. If you would like to provide a more complex command,
// for example, something that sets up a virtual environment before calling
// ansible, take a look at the ansible wrapper guide below for inspiration.
// Please note that Packer expects Command to be a path to an executable.
// Arbitrary bash scripting will not work and needs to go inside an
// executable script.
Command string `mapstructure:"command"`
// Extra arguments to pass to Ansible.
// These arguments _will not_ be passed through a shell and arguments should
// not be quoted. Usage example:
//
// ```json
// "extra_arguments": [ "--extra-vars", "Region={{user `Region`}} Stage={{user `Stage`}}" ]
// ```
// In certain scenarios where you want to pass ansible command line arguments
// that include parameter and value (for example `--vault-password-file pwfile`),
// from ansible documentation this is correct format but that is NOT accepted here.
// Instead you need to do it like `--vault-password-file=pwfile`.
//
// If you are running a Windows build on AWS, Azure, Google Compute, or OpenStack
// and would like to access the auto-generated password that Packer uses to
// connect to a Windows instance via WinRM, you can use the template variable
// `{{.WinRMPassword}}` in this option. For example:
//
// ```json
// "extra_arguments": [
// "--extra-vars", "winrm_password={{ .WinRMPassword }}"
// ]
// ```
ExtraArguments []string `mapstructure:"extra_arguments"`
// Path to group_vars directory
// 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.
GroupVars string `mapstructure:"group_vars"`
// Path to host_vars directory
// 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.
HostVars string `mapstructure:"host_vars"`
// The playbook dir to upload.
// 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.
PlaybookDir string `mapstructure:"playbook_dir"`
// The main playbook file to execute.
// The playbook file to be executed by ansible. This file must exist on your
// local system and will be uploaded to the remote machine. This option is
// exclusive with `playbook_files`.
PlaybookFile string `mapstructure:"playbook_file"`
// The playbook files to execute.
// The playbook files to be executed by ansible. These files must exist on
// your local system. If the files don't exist in the `playbook_dir` or you
// don't set `playbook_dir` they will be uploaded to the remote machine. This
// option is exclusive with `playbook_file`.
PlaybookFiles []string `mapstructure:"playbook_files"`
// An array of local paths of playbook files to upload.
// 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.
PlaybookPaths []string `mapstructure:"playbook_paths"`
// An array of local paths of roles to upload.
// 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.
RolePaths []string `mapstructure:"role_paths"`
// The directory where files will be uploaded. Packer requires write
// permissions in this directory.
// 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.
StagingDir string `mapstructure:"staging_directory"`
// If true, staging directory is removed after executing ansible.
// If set to `true`, the content of the `staging_directory` will be removed after
// executing ansible. By default this is set to `false`.
CleanStagingDir bool `mapstructure:"clean_staging_directory"`
// The optional inventory file
// 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 building. 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
// ```
InventoryFile string `mapstructure:"inventory_file"`
// The optional inventory groups
// `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
// ```
InventoryGroups []string `mapstructure:"inventory_groups"`
// The optional ansible-galaxy requirements file
// A requirements file which provides a way to
// install roles or collections with the [ansible-galaxy
// cli](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#the-ansible-galaxy-command-line-tool)
// on the local machine before executing `ansible-playbook`. By default, this is empty.
GalaxyFile string `mapstructure:"galaxy_file"`
// The command to run ansible-galaxy
// The command to invoke ansible-galaxy. By default, this is
// `ansible-galaxy`.
GalaxyCommand string `mapstructure:"galaxy_command"`
}

2
provisioner/ansible-local/provisioner.hcl2spec.go
Unescape View File

@ -18,7 +18,7 @@ type FlatConfig struct {
PackerOnError *string `mapstructure:"packer_on_error" cty:"packer_on_error" hcl:"packer_on_error"`
PackerUserVars map[string]string `mapstructure:"packer_user_variables" cty:"packer_user_variables" hcl:"packer_user_variables"`
PackerSensitiveVars []string `mapstructure:"packer_sensitive_variables" cty:"packer_sensitive_variables" hcl:"packer_sensitive_variables"`
Command *string `cty:"command" hcl:"command"`
Command *string `mapstructure:"command" cty:"command" hcl:"command"`
ExtraArguments []string `mapstructure:"extra_arguments" cty:"extra_arguments" hcl:"extra_arguments"`
GroupVars *string `mapstructure:"group_vars" cty:"group_vars" hcl:"group_vars"`
HostVars *string `mapstructure:"host_vars" cty:"host_vars" hcl:"host_vars"`

114
website/content/docs/provisioners/ansible-local.mdx
Unescape View File

@ -107,117 +107,9 @@ where ./playbook.yml contains
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. This option is exclusive with `playbook_files`.
- `playbook_files` (array of strings) - The playbook files to be executed by
ansible. These files must exist on your local system. If the files don't
exist in the `playbook_dir` or you don't set `playbook_dir` they will be
uploaded to the remote machine. This option is exclusive with
`playbook_file`.
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:
```text
"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 building. 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/latest/galaxy.html#the-ansible-galaxy-command-line-tool)
on the remote machine. By default, this is empty.
- `galaxy_command` (string) - The command to invoke ansible-galaxy. By
default, this is ansible-galaxy.
- `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.
- `clean_staging_directory` (boolean) - If set to `true`, the content of the
`staging_directory` will be removed after executing ansible. By default,
this is set to `false`.
Note that one of `playbook_file` or `playbook_files` is required.
@include '/provisioner/ansible/Config-not-required.mdx'
@include 'provisioners/common-config.mdx'

122
website/content/partials/provisioner/ansible-local/Config-not-required.mdx
Unescape View File

@ -0,0 +1,122 @@
<!-- Code generated from the comments of the Config struct in provisioner/ansible-local/provisioner.go; DO NOT EDIT MANUALLY -->
- `command` (string) - The command to invoke ansible. Defaults to
`ansible-playbook`. If you would like to provide a more complex command,
for example, something that sets up a virtual environment before calling
ansible, take a look at the ansible wrapper guide below for inspiration.
Please note that Packer expects Command to be a path to an executable.
Arbitrary bash scripting will not work and needs to go inside an
executable script.
- `extra_arguments` ([]string) - Extra arguments to pass to Ansible.
These arguments _will not_ be passed through a shell and arguments should
not be quoted. Usage example:
```json
"extra_arguments": [ "--extra-vars", "Region={{user `Region`}} Stage={{user `Stage`}}" ]
```
In certain scenarios where you want to pass ansible command line arguments
that include parameter and value (for example `--vault-password-file pwfile`),
from ansible documentation this is correct format but that is NOT accepted here.
Instead you need to do it like `--vault-password-file=pwfile`.
If you are running a Windows build on AWS, Azure, Google Compute, or OpenStack
and would like to access the auto-generated password that Packer uses to
connect to a Windows instance via WinRM, you can use the template variable
`{{.WinRMPassword}}` in this option. For example:
```json
"extra_arguments": [
"--extra-vars", "winrm_password={{ .WinRMPassword }}"
]
```
- `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.
- `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_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. This option is
exclusive with `playbook_files`.
- `playbook_files` ([]string) - The playbook files to be executed by ansible. These files must exist on
your local system. If the files don't exist in the `playbook_dir` or you
don't set `playbook_dir` they will be uploaded to the remote machine. This
option is exclusive with `playbook_file`.
- `playbook_paths` ([]string) - 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.
- `role_paths` ([]string) - 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.
- `clean_staging_directory` (bool) - If set to `true`, the content of the `staging_directory` will be removed after
executing ansible. By default this is set to `false`.
- `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 building. 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
```
- `inventory_groups` ([]string) - `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
```
- `galaxy_file` (string) - A requirements file which provides a way to
install roles or collections with the [ansible-galaxy
cli](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#the-ansible-galaxy-command-line-tool)
on the local machine before executing `ansible-playbook`. By default, this is empty.
- `galaxy_command` (string) - The command to invoke ansible-galaxy. By default, this is
`ansible-galaxy`.
Write Preview
Loading…
Cancel
Save