tamtam-vagrant-reload 1.1.2 → 1.2.1

data/vendor/cache/vagrant-2092df529ae7/website/content/docs/provisioning/ansible.mdx

@@ -0,0 +1,145 @@
+---
+layout: docs
+page_title: Ansible - Provisioning
+description: |-
+  The Vagrant Ansible provisioner allows you to provision the guest using
+  Ansible playbooks by executing "ansible-playbook" from the Vagrant host.
+---
+
+# Ansible Provisioner
+
+**Provisioner name: `ansible`**
+
+The Vagrant Ansible provisioner allows you to provision the guest using [Ansible](http://ansible.com) playbooks by executing **`ansible-playbook` from the Vagrant host**.
+
+~> **Warning:**
+If you are not familiar with Ansible and Vagrant already, we recommend starting with the [shell provisioner](/vagrant/docs/provisioning/shell). However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.
+
+## Setup Requirements
+
+- **[Install Ansible](https://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](https://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).
+
+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](/vagrant/docs/provisioning/ansible_local) alternative.
+
+## Usage
+
+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](/vagrant/docs/provisioning/ansible_intro).
+
+### Simplest Configuration
+
+To run Ansible against your Vagrant guest, the basic `Vagrantfile` configuration looks like:
+
+```ruby
+Vagrant.configure("2") do |config|
+
+  #
+  # Run Ansible from the Vagrant Host
+  #
+  config.vm.provision "ansible" do |ansible|
+    ansible.playbook = "playbook.yml"
+  end
+
+end
+```
+
+## Options
+
+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](/vagrant/docs/provisioning/ansible_common).
+
+- `ask_become_pass` (boolean) - require Ansible to [prompt for a password](https://docs.ansible.com/intro_getting_started.html#remote-connection-information) when switching to another user with the [become/sudo mechanism](http://docs.ansible.com/ansible/become.html).
+
+  The default value is `false`.
+
+- `ask_sudo_pass` (boolean) - Backwards compatible alias for the [ask_become_pass](#ask_become_pass) option.
+
+  ~> **Deprecation:**
+  The `ask_sudo_pass` option is deprecated and will be removed in a future release. Please use the [**`ask_become_pass`**](#ask_become_pass) option instead.
+
+* `ask_vault_pass` (boolean) - require Ansible to [prompt for a vault password](https://docs.ansible.com/playbooks_vault.html#vault).
+
+  The default value is `false`.
+
+* `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](/vagrant/docs/vagrantfile/ssh_settings).
+
+  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 default value is `true`.
+
+  -> **Compatibility Note:** This option was introduced in Vagrant 1.8.0. Previous Vagrant versions behave like if this option was set to `false`.
+
+- `host_key_checking` (boolean) - require Ansible to [enable SSH host key checking](https://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](https://docs.ansible.com/intro_configuration.html#ssh-args)).
+
+## Tips and Tricks
+
+### Ansible Parallel Execution
+
+Vagrant is designed to provision [multi-machine environments](/vagrant/docs/multi-machine) in sequence, but the following configuration pattern can be used to take advantage of Ansible parallelism:
+
+```ruby
+# Vagrant 1.7+ automatically inserts a different
+# insecure keypair for each new VM created. The easiest way
+# to use the same keypair for all the machines is to disable
+# this feature and rely on the legacy insecure key.
+# config.ssh.insert_key = false
+#
+# Note:
+# As of Vagrant 1.7.3, it is no longer necessary to disable
+# the keypair creation when using the auto-generated inventory.
+
+N = 3
+(1..N).each do |machine_id|
+  config.vm.define "machine#{machine_id}" do |machine|
+    machine.vm.hostname = "machine#{machine_id}"
+    machine.vm.network "private_network", ip: "192.168.77.#{20+machine_id}"
+
+    # Only execute once the Ansible provisioner,
+    # when all the machines are up and ready.
+    if machine_id == N
+      machine.vm.provision :ansible do |ansible|
+        # Disable default limit to connect to all the machines
+        ansible.limit = "all"
+        ansible.playbook = "playbook.yml"
+      end
+    end
+  end
+end
+```
+
+-> **Tip:**
+If you apply this parallel provisioning pattern with a static Ansible inventory,
+you will have to organize the things so that [all the relevant private keys are
+provided to the `ansible-playbook` command](https://github.com/hashicorp/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](/vagrant/docs/vagrantfile/ssh_settings)).
+
+### 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 though, it is possible to enable paramiko as illustrated in the following configuration examples:
+
+With auto-generated inventory:
+
+```ruby
+ansible.raw_arguments = ["--connection=paramiko"]
+```
+
+With a custom inventory, the private key must be specified (e.g. via an `ansible.cfg` configuration file, `--private-key` argument, or as part of your inventory file):
+
+```ruby
+ansible.inventory_path = "./my-inventory"
+ansible.raw_arguments  = [
+  "--connection=paramiko",
+  "--private-key=/home/.../.vagrant/machines/.../private_key"
+]
+```

data/vendor/cache/vagrant-2092df529ae7/website/content/docs/provisioning/ansible_common.mdx

@@ -0,0 +1,195 @@
+---
+layout: docs
+page_title: Common Ansible Options - Provisioning
+description: This page details the common options to the Vagrant Ansible provisioners.
+---
+
+# Shared Ansible Options
+
+The following options are available to both Vagrant Ansible provisioners:
+
+- [`ansible`](/vagrant/docs/provisioning/ansible)
+- [`ansible_local`](/vagrant/docs/provisioning/ansible_local)
+
+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.
+
+- `become` (boolean) - Perform all the Ansible playbook tasks [as another user](https://docs.ansible.com/ansible/latest/become.html), different from the user used to log into the guest system.
+
+  The default value is `false`.
+
+- `become_user` (string) - Set the default username to be used by the Ansible `become` [privilege escalation](https://docs.ansible.com/ansible/latest/become.html) mechanism.
+
+  By default this option is not set, and the Ansible default value (`root`) will be used.
+
+- `compatibility_mode` (string) - Set the **minimal** version of Ansible to be supported. Vagrant will only use parameters that are compatible with the given version.
+
+  Possible values:
+
+  - `"auto"` _(Vagrant will automatically select the optimal compatibility mode by checking the Ansible version currently available)_
+  - `"1.8"` _(Ansible versions prior to 1.8 should mostly work well, but some options might not be supported)_
+  - `"2.0"` _(The generated Ansible inventory will be incompatible with Ansible 1.x)_
+
+  By default this option is set to `"auto"`. If Vagrant is not able to detect any supported Ansible version, it will fall back on the compatibility mode `"1.8"` with a warning.
+
+  Vagrant will error if the specified compatibility mode is incompatible with the current Ansible version.
+
+  ~> **Attention:** Vagrant doesn't perform any validation between the `compatibility_mode` value and the value of the [`version`](#version) option.
+
+  -> **Compatibility Note:** This option was introduced in Vagrant 2.0. The behavior of previous Vagrant versions can be simulated by setting the `compatibility_mode` to `"1.8"`.
+
+- `config_file` (string) - The path to an [Ansible Configuration file](https://docs.ansible.com/ansible/latest/intro_configuration.html).
+
+  By default, this option is not set, and Ansible will [search for a possible configuration file in some default locations](/vagrant/docs/provisioning/ansible_intro#the-ansible-configuration-file).
+
+- `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.
+
+- `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.
+
+  ```ruby
+  ansible.galaxy_role_file = "requirements.yml"
+  ```
+
+- `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.
+
+- `groups` (hash) - Set of inventory groups to be included in the [auto-generated inventory file](/vagrant/docs/provisioning/ansible_intro).
+
+  Example:
+
+  ```ruby
+  ansible.groups = {
+    "web" => ["vm1", "vm2"],
+    "db"  => ["vm3"]
+  }
+  ```
+
+  Example with [group variables](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#assigning-a-variable-to-many-machines-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.
+
+- `host_vars` (hash) - Set of inventory host variables to be included in the [auto-generated inventory file](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#assigning-a-variable-to-one-machine-host-variables).
+
+  Example:
+
+  ```ruby
+  ansible.host_vars = {
+    "host1" => {"http_port" => 80,
+                "maxRequestsPerChild" => 808,
+                "comments" => "text with spaces"},
+    "host2" => {"http_port" => 303,
+                "maxRequestsPerChild" => 909}
+  }
+  ```
+
+  Note: 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](https://docs.ansible.com/ansible/latest/intro_inventory.html), a [dynamic inventory script](https://docs.ansible.com/ansible/latest/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](https://docs.ansible.com/ansible/latest/intro_dynamic_inventory.html#using-multiple-inventory-sources)).
+
+  By default, this option is disabled and Vagrant generates an inventory based on the `Vagrantfile` information.
+
+- `limit` (string or array of strings) - Set of machines or groups from the inventory file to further control which hosts [are affected](https://docs.ansible.com/ansible/latest/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.
+
+- `playbook_command` (string) - The command used to run playbooks.
+
+  The default value is `ansible-playbook`
+
+- `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.
+
+  Examples:
+
+  - `['--check', '-M', '/my/modules']`
+  - `["--connection=paramiko", "--forks=10"]`
+
+    ~> **Attention:** The `ansible` provisioner does not support whitespace characters in `raw_arguments`
+    elements. Therefore **don't write** something like `["-c paramiko"]`, which
+    will result with an invalid `" paramiko"` parameter value.
+
+- `skip_tags` (string or array of strings) - Only plays, roles and tasks that [_do not match_ these values will be executed](https://docs.ansible.com/ansible/latest/playbooks_tags.html).
+
+- `start_at_task` (string) - The task name where the [playbook execution will start](https://docs.ansible.com/ansible/latest/playbooks_startnstep.html#start-at-task).
+
+- `sudo` (boolean) - Backwards compatible alias for the [`become`](#become) option.
+
+  ~> **Deprecation:**
+  The `sudo` option is deprecated and will be removed in a future release. Please use the [**`become`**](#become) option instead.
+
+* `sudo_user` (string) - Backwards compatible alias for the [`become_user`](#become_user) option.
+
+  ~> **Deprecation:**
+  The `sudo_user` option is deprecated and will be removed in a future release. Please use the [**`become_user`**](#become_user) option instead.
+
+- `tags` (string or array of strings) - Only plays, roles and tasks [tagged with these values will be executed](https://docs.ansible.com/ansible/latest/playbooks_tags.html) .
+
+- `vault_password_file` (string) - The path of a file containing the password used by [Ansible Vault](https://docs.ansible.com/ansible/latest/playbooks_vault.html#vault).
+
+- `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.
+
+- `version` (string) - The expected Ansible version.
+
+  This option is disabled by default.
+
+  When an Ansible version is defined (e.g. `"2.1.6.0"`), the Ansible provisioner will be executed only if Ansible is installed at the requested version.
+
+  When this option is set to `"latest"`, no version check is applied.
+
+  -> **Tip:** With the `ansible_local` provisioner, it is currently possible to use this option
+  to specify which version of Ansible must be automatically installed, but **only** in combination with the [**`install_mode`**](/vagrant/docs/provisioning/ansible_local#install_mode) set to **`:pip`**.

data/vendor/cache/vagrant-2092df529ae7/website/content/docs/provisioning/ansible_intro.mdx

@@ -0,0 +1,264 @@
+---
+layout: docs
+page_title: Ansible - Short Introduction
+description: |-
+  This page includes options and information that is applicable to both Vagrant
+  Ansible provisioners.
+---
+
+# Ansible and Vagrant
+
+The information below is applicable to both Vagrant Ansible provisioners:
+
+- [`ansible`](/vagrant/docs/provisioning/ansible), where Ansible is executed on the **Vagrant host**
+- [`ansible_local`](/vagrant/docs/provisioning/ansible_local), where Ansible is executed on the **Vagrant guest**
+
+The list of common options for these two provisioners is documented in a [separate documentation page](/vagrant/docs/provisioning/ansible_common).
+
+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](https://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](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html) goes into great detail on how to author playbooks, and there are a number of [tips and tricks](https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.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
+  become: yes
+  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 do not have YUM by changing the playbook tasks. Ansible ships with a number of [modules](https://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`](/vagrant/docs/provisioning/ansible) and [`ansible_local`](/vagrant/docs/provisioning/ansible_local)), 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](https://docs.ansible.com/playbooks_best_practices.html#directory-layout) like this:
+
+```text
+.
+|-- 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](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#intro-inventory) 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.
+
+#### Ansible provisioner example
+
+Example with the [`ansible`](/vagrant/docs/provisioning/ansible) provisioner.
+
+```text
+# Generated by Vagrant
+
+default ansible_host=127.0.0.1 ansible_port=2200 ansible_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`.
+
+#### Ansible local provision
+
+Example with the [`ansible_local`](/vagrant/docs/provisioning/ansible_local) provisioner
+
+```text
+# 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`](/vagrant/docs/provisioning/ansible_local), e.g. `/tmp/vagrant-ansible/inventory/vagrant_ansible_local_inventory`.
+
+#### Host Variables
+
+As of Vagrant 1.8.0, the [`host_vars`](/vagrant/docs/provisioning/ansible_common#host_vars) option can be used to set [variables for individual hosts](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#assigning-a-variable-to-one-machine-host-variables) in the generated inventory file (see also the notes on group variables below).
+
+With this configuration example:
+
+```ruby
+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
+```
+
+Vagrant would generate the following inventory file:
+
+```text
+# Generated by Vagrant
+
+host1 ansible_host=... http_port=80 maxRequestsPerChild=808
+host2 ansible_host=... http_port=303 maxRequestsPerChild=909
+```
+
+#### Groups and Group Variables
+
+The [`groups`](/vagrant/docs/provisioning/ansible_common#groups) 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](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#assigning-a-variable-to-many-machines-group-variables), and group members as [host ranges (with numeric or alphabetic patterns)](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#inventory-basics-formats-hosts-and-groups).
+
+With this configuration example:
+
+```ruby
+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 the following inventory file:
+
+```text
+# Generated by Vagrant
+
+machine1 ansible_host=127.0.0.1 ansible_port=2200 ansible_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine1/virtualbox/private_key'
+machine2 ansible_host=127.0.0.1 ansible_port=2222 ansible_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](https://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)](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#inventory-basics-formats-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 would like to have more control over the inventory management.
+
+With the [`inventory_path`](/vagrant/docs/provisioning/ansible_common#inventory_path) option, you can reference a specific inventory resource (e.g. a static inventory file, a [dynamic inventory script](https://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](https://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:
+
+```text
+default ansible_host=192.168.111.222
+```
+
+Where the above IP address is one set in your Vagrantfile:
+
+```text
+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 `ansible.inventory_path` option by default is only scoped to apply to a single guest in the inventory file, and does not apply to all defined guests. To allow access to all available machines in the inventory, it is necessary to set `ansible.limit = "all"`.
+- 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](https://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:
+
+- as of Ansible 1.5, the lookup order is the following:
+  - any path set as `ANSIBLE_CONFIG` environment variable
+  - `ansible.cfg` in the runtime working directory
+  - `.ansible.cfg` in the user home directory
+  - `/etc/ansible/ansible.cfg`
+- Ansible commands don't look for a configuration file relative to the playbook file location (e.g. in the same directory)
+- an `ansible.cfg` file located in the same directory as your `Vagrantfile` will be used by default.
+- it is also possible to reference any other location with the [config_file](/vagrant/docs/provisioning/ansible_common#config_file) provisioner option. In this case, Vagrant will set the `ANSIBLE_CONFIG` environment variable accordingly.