+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+@@ -27,199 +20,62 @@ a single page of documentation. ## Setup Requirements -* [Install Ansible](http://docs.ansible.com/intro_installation.html#installing-the-control-machine) on your Vagrant host. -* Your Vagrant host should ideally provide a recent version of OpenSSH that [supports ControlPersist](http://docs.ansible.com/faq.html#how-do-i-get-ansible-to-reuse-connections-enable-kerberized-ssh-or-have-ansible-pay-attention-to-my-local-ssh-config-file) + - **[Install Ansible](http://docs.ansible.com/intro_installation.html#installing-the-control-machine) on your Vagrant host**. -## Inventory File + - Your Vagrant host should ideally provide a recent version of OpenSSH that [supports ControlPersist](http://docs.ansible.com/faq.html#how-do-i-get-ansible-to-reuse-connections-enable-kerberized-ssh-or-have-ansible-pay-attention-to-my-local-ssh-config-file). -When using Ansible, it needs to know on which machines a given playbook should run. It does -this by way of an [inventory](http://docs.ansible.com/intro_inventory.html) file which lists those machines. -In the context of Vagrant, there are two ways to approach working with inventory files. +If installing Ansible directly on the Vagrant host is not an option in your development environment, you might be looking for the Ansible Local provisioner alternative. -### Auto-Generated Inventory +## Usage -The first and simplest option is to not provide one to Vagrant at all. Vagrant will generate an -inventory file encompassing all of the virtual machines it manages, and use it for provisioning -machines. The generated inventory file is stored as part of your local Vagrant environment in `.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory`. +This page only documents the specific parts of the `ansible` (remote) provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the [introduction to Ansible and Vagrant](/v2/provisioning/ansible_intro.html). -**Groups of Hosts** +### Simplest Configuration -The `ansible.groups` option can be used to pass a hash of group names and group members to be included in the generated inventory file. - -With this configuration example: - -``` -ansible.groups = { - "group1" => ["machine1"], - "group2" => ["machine2"], - "all_groups:children" => ["group1", "group2"] -} -``` - -Vagrant would generate an inventory file that might look like: - -``` -# Generated by Vagrant - -machine1 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_private_key_file=/home/.../.vagrant/machines/machine1/virtualbox/private_key -machine2 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2201 ansible_ssh_private_key_file=/home/.../.vagrant/machines/machine2/virtualbox/private_key - -[group1] -machine1 - -[group2] -machine2 - -[all_groups:children] -group1 -group2 -``` - -**Notes** - - * The generation of group variables blocks (e.g. `[group1:vars]`) are intentionally not supported, as it is [not recommended to store group variables in the main inventory file](http://docs.ansible.com/intro_inventory.html#splitting-out-host-and-group-specific-data). A good practice is to store these group (or host) variables in `YAML` files stored in `group_vars/` or `host_vars/` directories in the playbook (or inventory) directory. - * Unmanaged machines and undefined groups are not added to the inventory, to avoid useless Ansible errors (e.g. *unreachable host* or *undefined child group*) - * Prior to Vagrant 1.7.3, the `ansible_ssh_private_key_file` variable was not set in generated inventory, but passed as command line argument to `ansible-playbook` command. - -For example, `machine3`, `group3` and `group1:vars` in the example below would not be added to the generated inventory file: - -``` -ansible.groups = { - "group1" => ["machine1"], - "group2" => ["machine2", "machine3"], - "all_groups:children" => ["group1", "group2", "group3"], - "group1:vars" => { "variable1" => 9, "variable2" => "example" } -} -``` - -### Static Inventory - -The second option is for situations where you'd like to have more control over the inventory management. -With the `ansible.inventory_path` option, you can reference a specific inventory resource (e.g. a static inventory file, a [dynamic inventory script](http://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](http://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources)). Vagrant will then use this inventory information instead of generating it. - -A very simple inventory file for use with Vagrant might look like: - -``` -default ansible_ssh_host=192.168.111.222 -``` - -Where the above IP address is one set in your Vagrantfile: - -``` -config.vm.network :private_network, ip: "192.168.111.222" -``` - -**Notes:** - - * The machine names in `Vagrantfile` and `ansible.inventory_path` files should correspond, unless you use `ansible.limit` option to reference the correct machines. - * The SSH host addresses (and ports) must obviously be specified twice, in `Vagrantfile` and `ansible.inventory_path` files. - -## Playbook - -The second component of a successful Ansible provisioner setup is the Ansible playbook -which contains the steps that should be run on the guest. Ansible's -[playbook documentation](http://docs.ansible.com/playbooks.html) goes into great -detail on how to author playbooks, and there are a number of -[best practices](http://docs.ansible.com/playbooks_best_practices.html) that can be applied to use -Ansible's powerful features effectively. A playbook that installs and starts (or restarts -if it was updated) the NTP daemon via YUM looks like: - -``` ---- -- hosts: all - tasks: - - name: ensure ntpd is at the latest version - yum: pkg=ntp state=latest - notify: - - restart ntpd - handlers: - - name: restart ntpd - service: name=ntpd state=restarted -``` - -You can of course target other operating systems that don't have YUM by changing the -playbook tasks. Ansible ships with a number of [modules](http://docs.ansible.com/modules.html) -that make running otherwise tedious tasks dead simple. - -## Running Ansible - -To run Ansible against your Vagrant guest, the basic Vagrantfile configuration looks like: +To run Ansible against your Vagrant guest, the basic `Vagrantfile` configuration looks like: ```ruby -Vagrant.configure("2") do |config| +Vagrant.configure(2) do |config| + + # + # Run Ansible from the Vagrant Host + # config.vm.provision "ansible" do |ansible| ansible.playbook = "playbook.yml" end + end ``` -Since an Ansible playbook can include many files, you may also collect the related files in -a directory structure like this: +## Options -``` -$ tree -. -|-- Vagrantfile -|-- provisioning -| |-- group_vars -| |-- all -| |-- playbook.yml -``` +This section lists the specific options for the Ansible (remote) provisioner. In addition to the options listed below, this provisioner supports the [common options for both Ansible provisioners](/v2/provisioning/ansible_common.html). -In such an arrangement, the `ansible.playbook` path should be adjusted accordingly: +- `ask_sudo_pass` (boolean) - require Ansible to [prompt for a sudo password](http://docs.ansible.com/intro_getting_started.html#remote-connection-information). -```ruby -Vagrant.configure("2") do |config| - config.vm.provision "ansible" do |ansible| - ansible.playbook = "provisioning/playbook.yml" - end -end -``` + The default value is `false`. -Vagrant will try to run the `playbook.yml` playbook against all machines defined in your Vagrantfile. +- `ask_vault_pass` (boolean) - require Ansible to [prompt for a vault password](http://docs.ansible.com/playbooks_vault.html#vault). -**Backward Compatibility Note**: + The default value is `false`. -Up to Vagrant 1.4, the Ansible provisioner could potentially connect (multiple times) to all hosts from the inventory file. -This behaviour is still possible by setting `ansible.limit = 'all'` (see more details below). +- `force_remote_user` (boolean) - require Vagrant to set the `ansible_ssh_user` setting in the generated inventory, or as an extra variable when a static inventory is used. All the Ansible `remote_user` parameters will then be overridden by the value of `config.ssh.username` of the [Vagrant SSH Settings](/v2/vagrantfile/ssh_settings.html). -## Additional Options + If this option is set to `false` Vagrant will set the Vagrant SSH username as a default Ansible remote user, but `remote_user` parameters of your Ansible plays or tasks will still be taken into account and thus override the Vagrant configuration. -The Ansible provisioner also includes a number of additional options that can be set, -all of which get passed to the `ansible-playbook` command that ships with Ansible. + The default value is `true`. -* `ansible.extra_vars` can be used to pass additional variables (with highest priority) to the playbook. This parameter can be a path to a JSON or YAML file, or a hash. For example: + **Note:** This option was introduced in Vagrant 1.8.0. Previous Vagrant versions behave like if this option was set to `false`. - ``` - ansible.extra_vars = { - ntp_server: "pool.ntp.org", - nginx: { - port: 8008, - workers: 4 - } - } - ``` - These variables take the highest precedence over any other variables. -* `ansible.sudo` can be set to `true` to cause Ansible to perform commands using sudo. -* `ansible.sudo_user` can be set to a string containing a username on the guest who should be used -by the sudo command. -* `ansible.ask_sudo_pass` can be set to `true` to require Ansible to prompt for a sudo password. -* `ansible.ask_vault_pass` can be set to `true` to require Ansible to prompt for a vault password. -* `ansible.vault_password_file` can be set to a string containing the path of a file containing the password used by Ansible Vault. -* `ansible.limit` can be set to a string or an array of machines or groups from the inventory file to further control which hosts are affected. Note that: - * As of Vagrant 1.5, the machine name (taken from Vagrantfile) is set as **default limit** to ensure that `vagrant provision` steps only affect the expected machine. Setting `ansible.limit` will override this default. - * Setting `ansible.limit = 'all'` can be used to make Ansible connect to all machines from the inventory file. -* `ansible.verbose` can be set to increase Ansible's verbosity to obtain detailed logging: - * `'v'`, verbose mode - * `'vv'` - * `'vvv'`, more - * `'vvvv'`, connection debugging -* `ansible.tags` can be set to a string or an array of tags. Only plays, roles and tasks tagged with these values will be executed. -* `ansible.skip_tags` can be set to a string or an array of tags. Only plays, roles and tasks that *do not match* these values will be executed. -* `ansible.start_at_task` can be set to a string corresponding to the task name where the playbook provision will start. -* `ansible.raw_arguments` can be set to an array of strings corresponding to a list of `ansible-playbook` arguments (e.g. `['--check', '-M /my/modules']`). It is an *unsafe wildcard* that can be used to apply Ansible options that are not (yet) supported by this Vagrant provisioner. As of Vagrant 1.7, `raw_arguments` has the highest priority and its values can potentially override or break other Vagrant settings. -* `ansible.raw_ssh_args` can be set to an array of strings corresponding to a list of OpenSSH client parameters (e.g. `['-o ControlMaster=no']`). It is an *unsafe wildcard* that can be used to pass additional SSH settings to Ansible via `ANSIBLE_SSH_ARGS` environment variable. -* `ansible.host_key_checking` can be set to `true` which will enable host key checking. As of Vagrant 1.5, the default value is `false` and as of Vagrant 1.7 the user known host file (e.g. `~/.ssh/known_hosts`) is no longer read nor modified. In other words: by default, the Ansible provisioner behaves the same as Vagrant native commands (e.g `vagrant ssh`). +- `host_key_checking` (boolean) - require Ansible to [enable SSH host key checking](http://docs.ansible.com/intro_getting_started.html#host-key-checking). + + The default value is `false`. + +- `raw_ssh_args` (array of strings) - require Ansible to apply a list of OpenSSH client options. + + Example: `['-o ControlMaster=no']`. + + It is an *unsafe wildcard* that can be used to pass additional SSH settings to Ansible via `ANSIBLE_SSH_ARGS` environment variable, overriding any other SSH arguments (e.g. defined in an [`ansible.cfg` configuration file](http://docs.ansible.com/intro_configuration.html#ssh-args)). ## Tips and Tricks @@ -265,46 +121,12 @@ end If you apply this parallel provisioning pattern with a static Ansible inventory, you'll have to organize the things so that [all the relevant private keys are provided to the `ansible-playbook` command](https://github.com/mitchellh/vagrant/pull/5765#issuecomment-120247738). The same kind of considerations applies if you are using multiple private keys for a same machine (see [`config.ssh.private_key_path` SSH setting](/v2/vagrantfile/ssh_settings.html)). -### Provide a local `ansible.cfg` file - -Certain settings in Ansible are (only) adjustable via a [configuration file](http://docs.ansible.com/intro_configuration.html), and you might want to ship such a file in your Vagrant project. - -As `ansible-playbook` command looks for local `ansible.cfg` configuration file in its *current directory* (but not in the directory that contains the main playbook), you have to store this file adjacent to your Vagrantfile. - -Note that it is also possible to reference an Ansible configuration file via `ANSIBLE_CONFIG` environment variable, if you want to be flexible about the location of this file. - -### Why does the Ansible provisioner connect as the wrong user? - -It is good to know that the following Ansible settings always override the `config.ssh.username` option defined in [Vagrant SSH Settings](/v2/vagrantfile/ssh_settings.html): - -* `ansible_ssh_user` variable -* `remote_user` (or `user`) play attribute -* `remote_user` task attribute - -Be aware that copying snippets from the Ansible documentation might lead to this problem, as `root` is used as the remote user in many [examples](http://docs.ansible.com/playbooks_intro.html#hosts-and-users). - -Example of an SSH error (with `vvv` log level), where an undefined remote user `xyz` has replaced `vagrant`: - -``` -TASK: [my_role | do something] ***************** -<127.0.0.1> ESTABLISH CONNECTION FOR USER: xyz -<127.0.0.1> EXEC ['ssh', '-tt', '-vvv', '-o', 'ControlMaster=auto',... -fatal: [ansible-devbox] => SSH encountered an unknown error. We recommend you re-run the command using -vvvv, which will enable SSH debugging output to help diagnose the issue. -``` - -In a situation like the above, to override the `remote_user` specified in a play you can use the following line in your Vagrantfile `vm.provision` block: - -``` -ansible.extra_vars = { ansible_ssh_user: 'vagrant' } -``` - ### Force Paramiko Connection Mode The Ansible provisioner is implemented with native OpenSSH support in mind, and there is no official support for [paramiko](https://github.com/paramiko/paramiko/) (A native Python SSHv2 protocol library). If you really need to use this connection mode, it is though possible to enable paramiko as illustrated in the following configuration examples: - With auto-generated inventory: ``` diff --git a/website/docs/source/v2/provisioning/ansible_common.html.md b/website/docs/source/v2/provisioning/ansible_common.html.md new file mode 100644 index 000000000..44b787e7e --- /dev/null +++ b/website/docs/source/v2/provisioning/ansible_common.html.md @@ -0,0 +1,134 @@ +--- +page_title: "Common Ansible Options - Provisioning" +sidebar_current: "provisioning-ansible-common" +--- + +# Shared Ansible Options + +The following options are available to both Ansible provisioners: + + - [`ansible`](/v2/provisioning/ansible.html) + - [`ansible_local`](/v2/provisioning/ansible_local.html) + +These options get passed to the `ansible-playbook` command that ships with Ansible, either via command line arguments or environment variables, depending on Ansible own capabilities. + +Some of these options are for advanced usage only and should not be used unless you understand their purpose. + +- `extra_vars` (string or hash) - Pass additional variables (with highest priority) to the playbook. + + This parameter can be a path to a JSON or YAML file, or a hash. + + Example: + + ```ruby + ansible.extra_vars = { + ntp_server: "pool.ntp.org", + nginx: { + port: 8008, + workers: 4 + } + } + ``` + These variables take the highest precedence over any other variables. + +- `host_vars` (hash) - Set of inventory host variables to be included in the [auto-generated inventory file](http://docs.ansible.com/ansible/intro_inventory.html#host-variables). + + Example: + + ```ruby + ansible.host_vars = { + "host1" => {"http_port" => 80, + "maxRequestsPerChild" => 808}, + "host2" => {"http_port" => 303, + "maxRequestsPerChild" => 909} + } + ``` + + Notes: + + - This option has no effect when the `inventory_path` option is defined. + +- `groups` (hash) - Set of inventory groups to be included in the [auto-generated inventory file](/v2/provisioning/ansible_intro.html). + + Example: + + ```ruby + ansible.groups = { + "web" => ["vm1", "vm2"], + "db" => ["vm3"] + } + ``` + Example with [group variables](http://docs.ansible.com/ansible/intro_inventory.html#group-variables): + + ```ruby + ansible.groups = { + "atlanta" => ["host1", "host2"], + "atlanta:vars" => {"ntp_server" => "ntp.atlanta.example.com", + "proxy" => "proxy.atlanta.example.com"} + } + ``` + + Notes: + + - Alphanumeric patterns are not supported (e.g. `db-[a:f]`, `vm[01:10]`). + - This option has no effect when the `inventory_path` option is defined. + +- `inventory_path` (string) - The path to an Ansible inventory resource (e.g. a [static inventory file](http://docs.ansible.com/intro_inventory.html), a [dynamic inventory script](http://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](http://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources)). + + By default, this option is disabled and Vagrant generates an inventory based on the `Vagrantfile` information. + +- `galaxy_command` (template string) - The command pattern used to install Galaxy roles when `galaxy_role_file` is set. + + The following (optional) placeholders can be used in this command pattern: + - `%{role_file}` is replaced by the absolute path to the `galaxy_role_file` option + - `%{roles_path}` is + - replaced by the absolute path to the `galaxy_roles_path` option when such option is defined, or + - replaced by the absolute path to a `roles` subdirectory sitting in the `playbook` parent directory. + + By default, this option is set to + + `ansible-galaxy install --role-file=%{role_file} --roles-path=%{roles_path} --force` + +- `galaxy_role_file` (string) - The path to the Ansible Galaxy role file. + + By default, this option is set to `nil` and Galaxy support is then disabled. + + Note: if an absolute path is given, the `ansible_local` provisioner will assume that it corresponds to the exact location on the guest system. + +- `galaxy_roles_path` (string) - The path to the directory where Ansible Galaxy roles must be installed + + By default, this option is set to `nil`, which means that the Galaxy roles will be installed in a `roles` subdirectory located in the parent directory of the `playbook` file. + +- `limit` (string or array of strings) - Set of machines or groups from the inventory file to further control which hosts [are affected](http://docs.ansible.com/glossary.html#limit-groups). + + The default value is set to the machine name (taken from `Vagrantfile`) to ensure that `vagrant provision` command only affect the expected machine. + + Setting `limit = "all"` can be used to make Ansible connect to all machines from the inventory file. + +- `raw_arguments` (array of strings) - a list of additional `ansible-playbook` arguments. + + It is an *unsafe wildcard* that can be used to apply Ansible options that are not (yet) supported by this Vagrant provisioner. As of Vagrant 1.7, `raw_arguments` has the highest priority and its values can potentially override or break other Vagrant settings. + + Example: `['--check', '-M /my/modules']`). + +- `skip_tags` (string or array of strings) - Only plays, roles and tasks that [*do not match* these values will be executed](http://docs.ansible.com/playbooks_tags.html). + +- `start_at_task` (string) - The task name where the [playbook execution will start](http://docs.ansible.com/playbooks_startnstep.html#start-at-task). + +- `sudo` (boolean) - Cause Ansible to perform all the playbook tasks [using sudo](http://docs.ansible.com/glossary.html#sudo). + + The default value is `false`. + +- `sudo_user` (string) - set the default username who should be used by the sudo command. + +- `tags` (string or array of strings) - Only plays, roles and tasks [tagged with these values will be executed](http://docs.ansible.com/playbooks_tags.html) . + +- `verbose` (boolean or string) - Set Ansible's verbosity to obtain detailed logging + + Default value is `false` (minimal verbosity). + + Examples: `true` (equivalent to `v`), `-vvv` (equivalent to `vvv`), `vvvv`. + + Note that when the `verbose` option is enabled, the `ansible-playbook` command used by Vagrant will be displayed. + +- `vault_password_file` (string) - The path of a file containing the password used by [Ansible Vault](http://docs.ansible.com/playbooks_vault.html#vault). diff --git a/website/docs/source/v2/provisioning/ansible_intro.html.md b/website/docs/source/v2/provisioning/ansible_intro.html.md new file mode 100644 index 000000000..cf8d4d01e --- /dev/null +++ b/website/docs/source/v2/provisioning/ansible_intro.html.md @@ -0,0 +1,253 @@ +--- +page_title: "Ansible - Short Introduction" +sidebar_current: "provisioning-ansible-intro" +--- + +# Ansible and Vagrant + +The information below is applicable to both Ansible provisioners: + + - [`ansible`](/v2/provisioning/ansible.html), where Ansible is executed on the **Vagrant host** + + - [`ansible_local`](/v2/provisioning/ansible_local.html), where Ansible is executed on the **Vagrant guest** + +The list of common options for these two provisioners is documented in a [separate documentation page](/v2/provisioning/ansible_common.html). + +This documentation page will not go into how to use Ansible or how to write Ansible playbooks, since Ansible is a complete deployment and configuration management system that is beyond the scope of Vagrant documentation. + +To learn more about Ansible, please consult the [Ansible Documentation Site](http://docs.ansible.com/). + +## The Playbook File + +The first component of a successful Ansible provisioner setup is the Ansible playbook which contains the steps that should be run on the guest. Ansible's +[playbook documentation](http://docs.ansible.com/playbooks.html) goes into great detail on how to author playbooks, and there are a number of [best practices](http://docs.ansible.com/playbooks_best_practices.html) that can be applied to use Ansible's powerful features effectively. + +A playbook that installs and starts (or restarts) the NTP daemon via YUM looks like: + +``` +--- +- hosts: all + tasks: + - name: ensure ntpd is at the latest version + yum: pkg=ntp state=latest + notify: + - restart ntpd + handlers: + - name: restart ntpd + service: name=ntpd state=restarted +``` + +You can of course target other operating systems that don't have YUM by changing the playbook tasks. Ansible ships with a number of [modules](http://docs.ansible.com/modules.html) that make running otherwise tedious tasks dead simple. + +### Running Ansible + +The `playbook` option is strictly required by both Ansible provisioners ([`ansible`](/v2/provisioning/ansible.html) and [`ansible_local`](/v2/provisioning/ansible_local.html)), as illustrated in this basic Vagrantfile` configuration: + +```ruby +Vagrant.configure(2) do |config| + + # Use :ansible or :ansible_local to + # select the provisioner of your choice + config.vm.provision :ansible do |ansible| + ansible.playbook = "playbook.yml" + end +end +``` + +Since an Ansible playbook can include many files, you may also collect the related files in a [directory structure](http://docs.ansible.com/playbooks_best_practices.html#directory-layout) like this: + +``` +. +|-- Vagrantfile +|-- provisioning +| |-- group_vars +| |-- all +| |-- roles +| |-- bar +| |-- foo +| |-- playbook.yml +``` + +In such an arrangement, the `ansible.playbook` path should be adjusted accordingly: + +```ruby +Vagrant.configure(2) do |config| + config.vm.provision "ansible" do |ansible| + ansible.playbook = "provisioning/playbook.yml" + end +end +``` + +## The Inventory File + +When using Ansible, it needs to know on which machines a given playbook should run. It does this by way of an [inventory](http://docs.ansible.com/intro_inventory.html) file which lists those machines. In the context of Vagrant, there are two ways to approach working with inventory files. + +### Auto-Generated Inventory + +The first and simplest option is to not provide one to Vagrant at all. Vagrant will generate an inventory file encompassing all of the virtual machines it manages, and use it for provisioning machines. + +**Example with the [`ansible`](/v2/provisioning/ansible.html) provisioner:** + +``` +# Generated by Vagrant + +default ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/default/virtualbox/private_key' +``` + +Note that the generated inventory file is stored as part of your local Vagrant environment in +`.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory`. + +**Example with the [`ansible_local`](/v2/provisioning/ansible_local.html) provisioner:** + +``` +# Generated by Vagrant + +default ansible_connection=local +``` + +Note that the generated inventory file is uploaded to the guest VM in a subdirectory of [`tmp_path`](/v2/provisioning/ansible_local.html), e.g. `/tmp/vagrant-ansible/inventory/vagrant_ansible_local_inventory`. + +**Host variables:** + +As of Vagrant 1.8.0, the [`host_vars`](/v2/provisioning/ansible_common.html) option can be used to set [variables for individual hosts](http://docs.ansible.com/ansible/intro_inventory.html#host-variables) in the generated inventory file (see also the notes on group variables below). + +``` +Vagrant.configure(2) do |config| + config.vm.define "host1" + config.vm.define "host2" + config.vm.provision "ansible" do |ansible| + ansible.playbook = "playbook.yml" + ansible.host_vars = { + "host1" => {"http_port" => 80, + "maxRequestsPerChild" => 808}, + "host2" => {"http_port" => 303, + "maxRequestsPerChild" => 909} + } + end +end +``` + +Generated inventory: + +``` +# Generated by Vagrant + +host1 ansible_ssh_host=... http_port=80 maxRequestsPerChild=808 +host2 ansible_ssh_host=... http_port=303 maxRequestsPerChild=909 +``` + +**How to generate Inventory Groups:** + +The [`groups`](/v2/provisioning/ansible_common.html) option can be used to pass a hash of group names and group members to be included in the generated inventory file. + +As of Vagrant 1.8.0, it is also possible to specify [group variables](http://docs.ansible.com/ansible/intro_inventory.html#group-variables), and group members as [host ranges (with numeric or alphabetic patterns)](http://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups). + +With this configuration example: + +``` +Vagrant.configure(2) do |config| + + config.vm.box = "ubuntu/trusty64" + + config.vm.define "machine1" + config.vm.define "machine2" + + config.vm.provision "ansible" do |ansible| + ansible.playbook = "playbook.yml" + ansible.groups = { + "group1" => ["machine1"], + "group2" => ["machine2"], + "group3" => ["machine[1:2]"], + "group4" => ["other_node-[a:d]"], # silly group definition + "all_groups:children" => ["group1", "group2"], + "group1:vars" => {"variable1" => 9, + "variable2" => "example"} + } + end +end +``` + +Vagrant would generate an inventory file that might look like: + +``` +# Generated by Vagrant + +machine1 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine1/virtualbox/private_key' +machine2 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine2/virtualbox/private_key' + +[group1] +machine1 + +[group2] +machine2 + +[group3] +machine[1:2] + +[group4] +other_node-[a:d] + +[all_groups:children] +group1 +group2 + +[group1:vars] +variable1=9 +variable2=example +``` + +**Notes:** + + - Prior to Vagrant 1.7.3, the `ansible_ssh_private_key_file` variable was not set in generated inventory, but passed as command line argument to `ansible-playbook` command. + - The generation of group variables blocks (e.g. `[group1:vars]`) is only possible since Vagrant 1.8.0. Note however that setting variables directly in the inventory is not the [preferred practice in Ansible](http://docs.ansible.com/intro_inventory.html#splitting-out-host-and-group-specific-data). If possible, group (or host) variables should be set in `YAML` files stored in the `group_vars/` or `host_vars/` directories in the playbook (or inventory) directory instead. + - Unmanaged machines and undefined groups are not added to the inventory, to avoid useless Ansible errors (e.g. *unreachable host* or *undefined child group*) + + For example, `machine3` and `group3` in the example below would not be added to the generated inventory file: + + ```ruby + ansible.groups = { + "group1" => ["machine1"], + "group2" => ["machine2", "machine3"], + "all_groups:children" => ["group1", "group2", "group3"] + } + ``` + - [Host range patterns (numeric and alphabetic ranges)](http://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups) will not be validated by Vagrant. As of Vagrant 1.8.0, host range patterns will be added as group members to the inventory anyway, this might lead to errors in Ansible (e.g *unreachable host*). + +### Static Inventory + +The second option is for situations where you'd like to have more control over the inventory management. + +With the `inventory_path` option, you can reference a specific inventory resource (e.g. a static inventory file, a [dynamic inventory script](http://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](http://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources)). Vagrant will then use this inventory information instead of generating it. + +A very simple inventory file for use with Vagrant might look like: + +``` +default ansible_ssh_host=192.168.111.222 +``` + +Where the above IP address is one set in your Vagrantfile: + +``` +config.vm.network :private_network, ip: "192.168.111.222" +``` + +**Notes:** + + - The machine names in `Vagrantfile` and `ansible.inventory_path` files should correspond, unless you use `ansible.limit` option to reference the correct machines. + - The SSH host addresses (and ports) must obviously be specified twice, in `Vagrantfile` and `ansible.inventory_path` files. + - Sharing hostnames across Vagrant host and guests might be a good idea (e.g. with some Ansible configuration task, or with a plugin like [`vagrant-hostmanager`](https://github.com/smdahlen/vagrant-hostmanager)). + +### The Ansible Configuration File + +Certain settings in Ansible are (only) adjustable via a [configuration file](http://docs.ansible.com/intro_configuration.html), and you might want to ship such a file in your Vagrant project. + +When shipping an Ansible configuration file it is good to know that: + + - it is possible to reference an Ansible configuration file via `ANSIBLE_CONFIG` environment variable, if you want to be flexible about the location of this file. + - `ansible-playbook` **never** looks for `ansible.cfg` in the directory that contains the main playbook file. + - As of Ansible 1.5, the lookup order is the following: + + - `ANSIBLE_CONFIG` an environment variable + - `ansible.cfg` in the runtime current directory + - `.ansible.cfg` in the user home directory + - `/etc/ansible/ansible.cfg` diff --git a/website/docs/source/v2/provisioning/ansible_local.html.md b/website/docs/source/v2/provisioning/ansible_local.html.md new file mode 100644 index 000000000..1c68ddbef --- /dev/null +++ b/website/docs/source/v2/provisioning/ansible_local.html.md @@ -0,0 +1,147 @@ +--- +page_title: "Ansible Local - Provisioning" +sidebar_current: "provisioning-ansible-local" +--- + +# Ansible Local Provisioner + +**Provisioner name: `ansible_local`** + +The Ansible Local provisioner allows you to provision the guest using [Ansible](http://ansible.com) playbooks by executing **`ansible-playbook` directly on the guest machine**. + +
+ Warning: If you're not familiar with Ansible and Vagrant already, + I recommend starting with the shell + provisioner. However, if you're comfortable with Vagrant already, Vagrant + is a great way to learn Ansible. +
+Set-Item WSMan:\localhost\Service\AllowUnencrypted -Value True Set-Item WSMan:\localhost\Service\Auth\Basic -Value True -\ No newline at end of file + diff --git a/website/docs/source/v2/virtualbox/boxes.html.md b/website/docs/source/v2/virtualbox/boxes.html.md index 6026369c0..3c8a8330a 100644 --- a/website/docs/source/v2/virtualbox/boxes.html.md +++ b/website/docs/source/v2/virtualbox/boxes.html.md @@ -159,4 +159,4 @@ of the NAT device without colons. When bringing up a VirtualBox backed machine, Vagrant [imports](http://www.virtualbox.org/manual/ch08.html#vboxmanage-import) -the first "ovf" file found in the box contents. +the "box.ovf" file found in the box contents. diff --git a/website/docs/source/v2/virtualbox/networking.html.md b/website/docs/source/v2/virtualbox/networking.html.md index 55e7d4c4c..5811373de 100644 --- a/website/docs/source/v2/virtualbox/networking.html.md +++ b/website/docs/source/v2/virtualbox/networking.html.md @@ -36,8 +36,8 @@ end ## VirtualBox NIC Type -You can specify a specific nictype for the created network interface -by using the `nictype` parameter. This isn't prefixed by `virtualbox__` +You can specify a specific NIC type for the created network interface +by using the `nic_type` parameter. This isn't prefixed by `virtualbox__` for legacy reasons, but is VirtualBox-specific. This is an advanced option and should only be used if you know what @@ -48,6 +48,6 @@ Example: ```ruby Vagrant.configure("2") do |config| config.vm.network "private_network", ip: "192.168.50.4", - nictype: "virtio" + nic_type: "virtio" end ``` diff --git a/website/www/Makefile b/website/www/Makefile new file mode 100644 index 000000000..63bb4cab1 --- /dev/null +++ b/website/www/Makefile @@ -0,0 +1,10 @@ +all: build + +init: + bundle + +dev: init + bundle exec middleman server + +build: init + bundle exec middleman build \ No newline at end of file diff --git a/website/www/README.md b/website/www/README.md index 814da3877..3645fa52c 100644 --- a/website/www/README.md +++ b/website/www/README.md @@ -14,13 +14,7 @@ requests like any normal GitHub project, and we'll merge it in. ## Running the Site Locally -Running the site locally is simple. Clone this repo and run the following -commands: - -``` -$ bundle -$ bundle exec middleman server -``` +Running the site locally is simple. Clone this repo and run `make dev`. Then open up `localhost:4567`. Note that some URLs you may need to append ".html" to make them work (in the navigation and such). diff --git a/website/www/Vagrantfile b/website/www/Vagrantfile index 2d8d8c9b4..cb40d506b 100644 --- a/website/www/Vagrantfile +++ b/website/www/Vagrantfile @@ -6,8 +6,9 @@ sudo apt-get -y update sudo apt-get -y install curl sudo su -l -c 'gpg --keyserver hkp://keys.gnupg.net --recv-keys D39DC0E3' vagrant sudo su -l -c 'curl -L https://get.rvm.io | bash -s stable --auto-dotfiles' vagrant -sudo su -l -c 'rvm install 2.0.0' vagrant -sudo su -l -c 'rvm --default use 2.0.0' vagrant +sudo su -l -c 'rvm install 2.2.2' vagrant +sudo su -l -c 'rvm --default use 2.2.2' vagrant +sudo su -l -c 'gem install bundler' vagrant sudo su -l -c 'cd /vagrant && bundle install --jobs 2' vagrant SCRIPT diff --git a/website/www/source/images/icons/icon_debian.png b/website/www/source/images/icons/icon_debian.png index 0e92d4fcc..3c096cecb 100644 Binary files a/website/www/source/images/icons/icon_debian.png and b/website/www/source/images/icons/icon_debian.png differ diff --git a/website/www/source/layouts/layout.erb b/website/www/source/layouts/layout.erb index f0d2538e5..14c0d307d 100644 --- a/website/www/source/layouts/layout.erb +++ b/website/www/source/layouts/layout.erb @@ -52,6 +52,7 @@