new repository

1 files changed, 99 insertions, 0 deletions

diff --git a/devdocs/vagrant/provisioning%2Fansible_local.html b/devdocs/vagrant/provisioning%2Fansible_local.html
new file mode 100644
index 00000000..48742f8b
--- /dev/null
+++ b/devdocs/vagrant/provisioning%2Fansible_local.html
@@ -0,0 +1,99 @@
+<h1 id="ansible-local-provisioner">  Ansible Local Provisioner </h1> <p><strong>Provisioner name: <code>ansible_local</code></strong></p> <p>The Vagrant Ansible Local provisioner allows you to provision the guest using <a href="http://ansible.com">Ansible</a> playbooks by executing <strong><code>ansible-playbook</code> directly on the guest machine</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> <p>The main advantage of the Ansible Local provisioner in comparison to the <a href="ansible">Ansible (remote) provisioner</a> is that it does not require any additional software on your Vagrant host.</p> <p>On the other hand, <a href="https://docs.ansible.com/intro_installation.html#installing-the-control-machine">Ansible must obviously be installed</a> on your guest machine(s).</p> <p><strong>Note:</strong> By default, Vagrant will <em>try</em> to automatically install Ansible if it is not yet present on the guest machine (see the <code>install</code> option below for more details).</p> <h2 id="usage">  Usage </h2> <p>This page only documents the specific parts of the <code>ansible_local</code> provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the <a href="ansible_intro">introduction to Ansible and Vagrant</a>.</p> <p>The Ansible Local provisioner requires that all the Ansible Playbook files are available on the guest machine, at the location referred by the <code>provisioning_path</code> option. Usually these files are initially present on the host machine (as part of your Vagrant project), and it is quite easy to share them with a Vagrant <a href="../synced-folders/index">Synced Folder</a>.</p> <h3 id="simplest-configuration">  Simplest Configuration </h3> <p>To run Ansible from 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 VM
+  config.vm.provision "ansible_local" do |ansible|
+    ansible.playbook = "playbook.yml"
+  end
+end
+</pre></div>
+<p><strong>Requirements:</strong></p> <ul> <li>
+<p>The <code>playbook.yml</code> file is stored in your Vagrant's project home directory.</p> </li> <li>
+<p>The <a href="../synced-folders/basic_usage">default shared directory</a> is enabled (<code>.</code> → <code>/vagrant</code>).</p> </li> </ul> <h2 id="options">  Options </h2> <p>This section lists the <em>specific</em> options for the Ansible Local 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="#install"><code>install</code></a> (boolean) - Try to automatically install Ansible on the guest system.</p> <p>This option is enabled by default.</p> <p>Vagrant will try to install (or upgrade) Ansible when one of these conditions are met:</p> <ul> <li>Ansible is not installed (or cannot be found). </li> <li>The <a href="ansible_common#version"><code>version</code></a> option is set to <code>"latest"</code>. </li> <li>The current Ansible version does not correspond to the <a href="ansible_common#version"><code>version</code></a> option. </li> </ul> <blockquote class="alert alert-warning"> <p><strong>Attention:</strong> There is no guarantee that this automated installation will replace a custom Ansible setup, that might be already present on the Vagrant box.</p> </blockquote>
+</li> <li>
+<p><a href="#install_mode"><code>install_mode</code></a> (<code>:default</code>, <code>:pip</code>, or <code>:pip_args_only</code>) - Select the way to automatically install Ansible on the guest system.</p> <ul> <li>
+<a href="#default"><code>:default</code></a>: Ansible is installed from the operating system package manager. This mode doesn't support <code>version</code> selection. For many platforms (e.g Debian, FreeBSD, OpenSUSE) the official package repository is used, except for the following Linux distributions: <ul> <li>On Ubuntu-like systems, the latest Ansible release is installed from the <code>ppa:ansible/ansible</code> repository. The compatibility is maintained only for active long-term support (LTS) versions. </li> <li>On RedHat-like systems, the latest Ansible release is installed from the <a href="http://fedoraproject.org/wiki/EPEL">EPEL</a> repository. </li> </ul> </li> <li>
+<p><a href="#pip"><code>:pip</code></a>: Ansible is installed from <a href="https://pypi.python.org/pypi">PyPI</a> with <a href="https://pip.pypa.io">pip</a> package installer. With this mode, Vagrant will systematically try to <a href="https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py">install the latest pip version</a>. With the <code>:pip</code> mode you can optionally install a specific Ansible release by setting the <a href="ansible_common#version"><code>version</code></a> option.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provision "ansible_local" do |ansible|
+  ansible.playbook = "playbook.yml"
+  ansible.install_mode = "pip"
+  ansible.version = "2.2.1.0"
+end
+</pre></div>
+<p>With this configuration, Vagrant will install <code>pip</code> and then execute the command</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo pip install --upgrade ansible==2.2.1.0
+</pre></div>
+</li> <li>
+<p><a href="#pip_args_only"><code>:pip_args_only</code></a>: This mode is very similar to the <code>:pip</code> mode, with the difference that in this case no pip arguments will be automatically set by Vagrant.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provision "ansible_local" do |ansible|
+  ansible.playbook = "playbook.yml"
+  ansible.install_mode = "pip_args_only"
+  ansible.pip_args = "-r /vagrant/requirements.txt"
+end
+</pre></div>
+<p>With this configuration, Vagrant will install <code>pip</code> and then execute the command</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo pip install -r /vagrant/requirements.txt
+</pre></div>
+</li> </ul> <p>The default value of <code>install_mode</code> is <code>:default</code>, and any invalid value for this option will silently fall back to the default value.</p> </li> <li>
+<p><a href="#pip_args"><code>pip_args</code></a> (string) - When Ansible is installed via pip, this option allows the definition of additional pip arguments to be passed along on the command line (for example, <a href="https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-i"><code>--index-url</code></a>).</p> <p>By default, this option is not set.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provision "ansible_local" do |ansible|
+  ansible.playbook = "playbook.yml"
+  ansible.install_mode = :pip
+  ansible.pip_args = "--index-url https://pypi.internal"
+end
+</pre></div>
+<p>With this configuration, Vagrant will install <code>pip</code> and then execute the command</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo pip install --index-url https://pypi.internal --upgrade ansible
+</pre></div>
+</li> <li>
+<p><a href="#provisioning_path"><code>provisioning_path</code></a> (string) - An absolute path on the guest machine where the Ansible files are stored. The <code>ansible-galaxy</code> and <code>ansible-playbook</code> commands are executed from this directory. This is the location to place an <a href="http://docs.ansible.com/ansible/intro_configuration.html">ansible.cfg</a> file, in case you need it.</p> <p>The default value is <code>/vagrant</code>.</p> </li> <li>
+<p><a href="#tmp_path"><code>tmp_path</code></a> (string) - An absolute path on the guest machine where temporary files are stored by the Ansible Local provisioner.</p> <p>The default value is <code>/tmp/vagrant-ansible</code></p> </li> </ul> <h2 id="tips-and-tricks">  Tips and Tricks </h2> <h3 id="install-galaxy-roles-in-a-path-owned-by-root">  Install Galaxy Roles in a path owned by root </h3> 
+<blockquote class="alert alert-warning"> <strong>Disclaimer:</strong> This tip is not a recommendation to install galaxy roles out of the vagrant user space, especially if you rely on ssh agent forwarding to fetch the roles. </blockquote> <p>Be careful that <code>ansible-galaxy</code> command is executed by default as vagrant user. Setting <code>galaxy_roles_path</code> to a folder like <code>/etc/ansible/roles</code> will fail, and <code>ansible-galaxy</code> will extract the role a second time in <code>/home/vagrant/.ansible/roles/</code>. Then if your playbook uses <code>become</code> to run as <code>root</code>, it will fail with a <em>"role was not found"</em> error.</p> <p>To work around that, you can use <code>ansible.galaxy_command</code> to prepend the command with <code>sudo</code>, as illustrated in the example below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure(2) do |config|
+  config.vm.box = "centos/7"
+  config.vm.provision "ansible_local" do |ansible|
+    ansible.become = true
+    ansible.playbook = "playbook.yml"
+    ansible.galaxy_role_file = "requirements.yml"
+    ansible.galaxy_roles_path = "/etc/ansible/roles"
+    ansible.galaxy_command = "sudo ansible-galaxy install --role-file=%{role_file} --roles-path=%{roles_path} --force"
+  end
+end
+</pre></div>
+<h3 id="ansible-parallel-execution-from-a-guest">  Ansible Parallel Execution from a Guest </h3> <p>With the following configuration pattern, you can install and execute Ansible only on a single guest machine (the <code>"controller"</code>) to provision all your machines.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+
+  config.vm.box = "ubuntu/trusty64"
+
+  config.vm.define "node1" do |machine|
+    machine.vm.network "private_network", ip: "172.17.177.21"
+  end
+
+  config.vm.define "node2" do |machine|
+    machine.vm.network "private_network", ip: "172.17.177.22"
+  end
+
+  config.vm.define 'controller' do |machine|
+    machine.vm.network "private_network", ip: "172.17.177.11"
+
+    machine.vm.provision :ansible_local do |ansible|
+      ansible.playbook       = "example.yml"
+      ansible.verbose        = true
+      ansible.install        = true
+      ansible.limit          = "all" # or only "nodes" group, etc.
+      ansible.inventory_path = "inventory"
+    end
+  end
+
+end
+</pre></div>
+<p>You need to create a static <code>inventory</code> file that corresponds to your <code>Vagrantfile</code> machine definitions:</p> <div class="highlight"><pre class="highlight plaintext">controller ansible_connection=local
+node1      ansible_ssh_host=172.17.177.21 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node1/virtualbox/private_key
+node2      ansible_ssh_host=172.17.177.22 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node2/virtualbox/private_key
+
+[nodes]
+node[1:2]
+</pre></div>
+<p>And finally, you also have to create an <a href="https://docs.ansible.com/intro_configuration.html#openssh-specific-settings"><code>ansible.cfg</code> file</a> to fully disable SSH host key checking. More SSH configurations can be added to the <code>ssh_args</code> parameter (e.g. agent forwarding, etc.)</p> <div class="highlight"><pre class="highlight plaintext">[defaults]
+host_key_checking = no
+
+[ssh_connection]
+ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes
+</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_local.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/ansible_local.html</a>
+  </p>
+</div>