provisioners/ansible: update doc for GH-5765 (wip)

website/docs/source/v2/provisioning/ansible.html.md

@@ -61,8 +61,8 @@ 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
+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
+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
@@ -79,6 +79,7 @@ group2
 
  * 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:
 
@@ -227,21 +228,26 @@ by the sudo command.
 Vagrant is designed to provision [multi-machine environments](/v2/multi-machine) in sequence, but the following configuration pattern can be used to take advantage of Ansible parallelism:
 
 ```
-  # By default, Vagrant 1.7+ automatically inserts a different
+# 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
+# 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.
 
-  config.vm.define 'machine2' do |machine|
+N = 3
-    machine.vm.hostname = 'machine2'
+(1..N).each do |machine_id|
-    machine.vm.network "private_network", ip: "192.168.77.22"
+  config.vm.define "machine#{machine_id}" do |machine|
-  end
 
-  config.vm.define 'machine1' do |machine|
+    machine.vm.hostname = "machine#{machine_id}"
-    machine.vm.hostname = 'machine1'
+    machine.vm.network "private_network", ip: "192.168.77.#{20+machine_id}"
-    machine.vm.network "private_network", ip: "192.168.77.21"
 
+    if machine_id == N
+
+      # TODO add a comment
       machine.vm.provision :ansible do |ansible|
         ansible.playbook = "playbook.yml"
 
@@ -249,8 +255,20 @@ Vagrant is designed to provision [multi-machine environments](/v2/multi-machine)
         ansible.limit = 'all'
       end
     end
+
+  end
+end
 ```
 
+**Caveats:**
+
+- Vagrant will only
+
+
+TODO: add a note about mixing parallel and custom inventory
+TODO: multiple keys are not supported with parallelism, except if you pass them as raw_ssh_args!
+
+
 ### 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.
@@ -283,3 +301,26 @@ In a situation like the above, to override the `remote_user` specified in a play
 ```
 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:
+
+```
+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):
+
+```
+ansible.inventory_path = "./my-inventory"
+ansible.raw_arguments  = [
+  "--connection=paramiko",
+  "--private-key=/home/.../.vagrant/machines/.../private_key"
+]
+```