1 files changed, 64 insertions, 0 deletions
diff --git a/devdocs/vagrant/provisioning%2Fansible.html b/devdocs/vagrant/provisioning%2Fansible.html
new file mode 100644
index 00000000..70895a6b
--- /dev/null
+++ b/devdocs/vagrant/provisioning%2Fansible.html
@@ -0,0 +1,64 @@
+<h1 id="ansible-provisioner">  Ansible Provisioner </h1> <p><strong>Provisioner name: <code>ansible</code></strong></p> <p>The Vagrant Ansible provisioner allows you to provision the guest using <a href="http://ansible.com">Ansible</a> playbooks by executing <strong><code>ansible-playbook</code> from the Vagrant host</strong>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Ansible and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.</p> </blockquote>
+<h2 id="setup-requirements">  Setup Requirements </h2> <ul> <li>
+<p><strong><a href="https://docs.ansible.com/intro_installation.html#installing-the-control-machine">Install Ansible</a> on your Vagrant host</strong>.</p> </li> <li>
+<p>Your Vagrant host should ideally provide a recent version of OpenSSH that <a href="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">supports ControlPersist</a>.</p> </li> </ul> <p>If installing Ansible directly on the Vagrant host is not an option in your development environment, you might be looking for the <a href="ansible_local">Ansible Local provisioner</a> alternative.</p> <h2 id="usage">  Usage </h2> <p>This page only documents the specific parts of the <code>ansible</code> (remote) provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the <a href="ansible_intro">introduction to Ansible and Vagrant</a>.</p> <h3 id="simplest-configuration">  Simplest Configuration </h3> <p>To run Ansible against your Vagrant guest, the basic <code>Vagrantfile</code> configuration looks like:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+
+  #
+  # Run Ansible from the Vagrant Host
+  #
+  config.vm.provision "ansible" do |ansible|
+    ansible.playbook = "playbook.yml"
+  end
+
+end
+</pre></div>
+<h2 id="options">  Options </h2> <p>This section lists the <em>specific</em> options for the Ansible (remote) provisioner. In addition to the options listed below, this provisioner supports the <a href="ansible_common"><strong>common options</strong> for both Ansible provisioners</a>.</p> <ul> <li>
+<p><a href="#ask_become_pass"><code>ask_become_pass</code></a> (boolean) - require Ansible to <a href="https://docs.ansible.com/intro_getting_started.html#remote-connection-information">prompt for a password</a> when switching to another user with the <a href="http://docs.ansible.com/ansible/become.html">become/sudo mechanism</a>.</p> <p>The default value is <code>false</code>.</p> </li> <li>
+<p><a href="#ask_sudo_pass"><code>ask_sudo_pass</code></a> (boolean) - Backwards compatible alias for the <a href="#ask_become_pass">ask_become_pass</a> option.</p> <blockquote class="alert alert-warning"> <p><strong>Deprecation:</strong> The <code>ask_sudo_pass</code> option is deprecated and will be removed in a future release. Please use the <a href="#ask_become_pass"><strong><code>ask_become_pass</code></strong></a> option instead.</p> </blockquote>
+</li> <li>
+<p><a href="#ask_vault_pass"><code>ask_vault_pass</code></a> (boolean) - require Ansible to <a href="https://docs.ansible.com/playbooks_vault.html#vault">prompt for a vault password</a>.</p> <p>The default value is <code>false</code>.</p> </li> <li>
+<p><a href="#force_remote_user"><code>force_remote_user</code></a> (boolean) - require Vagrant to set the <code>ansible_ssh_user</code> setting in the generated inventory, or as an extra variable when a static inventory is used. All the Ansible <code>remote_user</code> parameters will then be overridden by the value of <code>config.ssh.username</code> of the <a href="../vagrantfile/ssh_settings">Vagrant SSH Settings</a>.</p> <p>If this option is set to <code>false</code> Vagrant will set the Vagrant SSH username as a default Ansible remote user, but <code>remote_user</code> parameters of your Ansible plays or tasks will still be taken into account and thus override the Vagrant configuration.</p> <p>The default value is <code>true</code>.</p> <blockquote class="alert alert-info"> <p><strong>Compatibility Note:</strong> This option was introduced in Vagrant 1.8.0. Previous Vagrant versions behave like if this option was set to <code>false</code>.</p> </blockquote>
+</li> <li>
+<p><a href="#host_key_checking"><code>host_key_checking</code></a> (boolean) - require Ansible to <a href="https://docs.ansible.com/intro_getting_started.html#host-key-checking">enable SSH host key checking</a>.</p> <p>The default value is <code>false</code>.</p> </li> <li>
+<p><a href="#raw_ssh_args"><code>raw_ssh_args</code></a> (array of strings) - require Ansible to apply a list of OpenSSH client options.</p> <p>Example: <code>['-o ControlMaster=no']</code>.</p> <p>It is an <em>unsafe wildcard</em> that can be used to pass additional SSH settings to Ansible via <code>ANSIBLE_SSH_ARGS</code> environment variable, overriding any other SSH arguments (e.g. defined in an <a href="https://docs.ansible.com/intro_configuration.html#ssh-args"><code>ansible.cfg</code> configuration file</a>).</p> </li> </ul> <h2 id="tips-and-tricks">  Tips and Tricks </h2> <h3 id="ansible-parallel-execution">  Ansible Parallel Execution </h3> <p>Vagrant is designed to provision <a href="../multi-machine">multi-machine environments</a> in sequence, but the following configuration pattern can be used to take advantage of Ansible parallelism:</p> <div class="highlight"><pre class="highlight ruby" data-language="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
+</pre></div>
+<blockquote class="alert alert-info"> <p><strong>Tip:</strong> If you apply this parallel provisioning pattern with a static Ansible inventory, you will have to organize the things so that <a href="https://github.com/hashicorp/vagrant/pull/5765#issuecomment-120247738">all the relevant private keys are provided to the <code>ansible-playbook</code> command</a>. The same kind of considerations applies if you are using multiple private keys for a same machine (see <a href="../vagrantfile/ssh_settings"><code>config.ssh.private_key_path</code> SSH setting</a>).</p> </blockquote>
+<h3 id="force-paramiko-connection-mode">  Force Paramiko Connection Mode </h3> <p>The Ansible provisioner is implemented with native OpenSSH support in mind, and there is no official support for <a href="https://github.com/paramiko/paramiko/">paramiko</a> (A native Python SSHv2 protocol library).</p> <p>If you really need to use this connection mode though, it is possible to enable paramiko as illustrated in the following configuration examples:</p> <p>With auto-generated inventory:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.raw_arguments = ["--connection=paramiko"]
+</pre></div>
+<p>With a custom inventory, the private key must be specified (e.g. via an <code>ansible.cfg</code> configuration file, <code>--private-key</code> argument, or as part of your inventory file):</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.inventory_path = "./my-inventory"
+ansible.raw_arguments  = [
+  "--connection=paramiko",
+  "--private-key=/home/.../.vagrant/machines/.../private_key"
+]
+</pre></div><div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2010&ndash;2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br>
+    <a href="https://www.vagrantup.com/docs/provisioning/ansible.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/ansible.html</a>
+  </p>
+</div>