"Fossies" - the Fresh Open Source Software Archive

Member "vagrant-2.2.14/website/pages/docs/provisioning/ansible_local.mdx" (20 Nov 2020, 10821 Bytes) of package /linux/misc/vagrant-2.2.14.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 ---
    2 layout: docs
    3 page_title: Ansible Local - Provisioning
    4 sidebar_title: Ansible Local
    5 description: >-
    6   The Vagrant Ansible Local provisioner allows you to provision the guest using
    7   Ansible playbooks by executing "ansible-playbook" directly on the guest
    8 
    9   machine.
   10 ---
   11 
   12 # Ansible Local Provisioner
   13 
   14 **Provisioner name: `ansible_local`**
   15 
   16 The Vagrant Ansible Local provisioner allows you to provision the guest using [Ansible](http://ansible.com) playbooks by executing **`ansible-playbook` directly on the guest machine**.
   17 
   18 ~> **Warning:** If you are not familiar with Ansible and Vagrant already, we recommend starting with the [shell provisioner](/docs/provisioning/shell). However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.
   19 
   20 ## Setup Requirements
   21 
   22 The main advantage of the Ansible Local provisioner in comparison to the [Ansible (remote) provisioner](/docs/provisioning/ansible) is that it does not require any additional software on your Vagrant host.
   23 
   24 On the other hand, [Ansible must obviously be installed](https://docs.ansible.com/intro_installation.html#installing-the-control-machine) on your guest machine(s).
   25 
   26 **Note:** By default, Vagrant will _try_ to automatically install Ansible if it is not yet present on the guest machine (see the `install` option below for more details).
   27 
   28 ## Usage
   29 
   30 This page only documents the specific parts of the `ansible_local` provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the [introduction to Ansible and Vagrant](/docs/provisioning/ansible_intro).
   31 
   32 The Ansible Local provisioner requires that all the Ansible Playbook files are available on the guest machine, at the location referred by the `provisioning_path` 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 [Synced Folder](/docs/synced-folders/).
   33 
   34 ### Simplest Configuration
   35 
   36 To run Ansible from your Vagrant guest, the basic `Vagrantfile` configuration looks like:
   37 
   38 ```ruby
   39 Vagrant.configure("2") do |config|
   40   # Run Ansible from the Vagrant VM
   41   config.vm.provision "ansible_local" do |ansible|
   42     ansible.playbook = "playbook.yml"
   43   end
   44 end
   45 ```
   46 
   47 **Requirements:**
   48 
   49 - The `playbook.yml` file is stored in your Vagrant's project home directory.
   50 
   51 - The [default shared directory](/docs/synced-folders/basic_usage) is enabled (`.` → `/vagrant`).
   52 
   53 ## Options
   54 
   55 This section lists the _specific_ options for the Ansible Local provisioner. In addition to the options listed below, this provisioner supports the [**common options** for both Ansible provisioners](/docs/provisioning/ansible_common).
   56 
   57 - `install` (boolean) - Try to automatically install Ansible on the guest system.
   58 
   59   This option is enabled by default.
   60 
   61   Vagrant will try to install (or upgrade) Ansible when one of these conditions are met:
   62 
   63   - Ansible is not installed (or cannot be found).
   64   - The [`version`](/docs/provisioning/ansible_common#version) option is set to `"latest"`.
   65   - The current Ansible version does not correspond to the [`version`](/docs/provisioning/ansible_common#version) option.
   66 
   67     ~> **Attention:**
   68     There is no guarantee that this automated installation will replace a custom Ansible setup, that might be already present on the Vagrant box.
   69 
   70 * `install_mode` (`:default`, `:pip`, or `:pip_args_only`) - Select the way to automatically install Ansible on the guest system.
   71 
   72   - `:default`: Ansible is installed from the operating system package manager. This mode doesn't support `version` selection. For many platforms (e.g Debian, FreeBSD, OpenSUSE) the official package repository is used, except for the following Linux distributions:
   73 
   74     - On Ubuntu-like systems, the latest Ansible release is installed from the `ppa:ansible/ansible` repository. The compatibility is maintained only for active long-term support (LTS) versions.
   75     - On RedHat-like systems, the latest Ansible release is installed from the [EPEL](http://fedoraproject.org/wiki/EPEL) repository.
   76 
   77   - `:pip`: Ansible is installed from [PyPI](https://pypi.python.org/pypi) with [pip](https://pip.pypa.io) package installer. With this mode, Vagrant will systematically try to [install the latest pip version](https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py). With the `:pip` mode you can optionally install a specific Ansible release by setting the [`version`](/docs/provisioning/ansible_common#version) option.
   78 
   79     Example:
   80 
   81     ```ruby
   82     config.vm.provision "ansible_local" do |ansible|
   83       ansible.playbook = "playbook.yml"
   84       ansible.install_mode = "pip"
   85       ansible.version = "2.2.1.0"
   86     end
   87     ```
   88 
   89     With this configuration, Vagrant will install `pip` and then execute the command
   90 
   91     ```shell
   92     sudo pip install --upgrade ansible==2.2.1.0
   93     ```
   94 
   95     As-is `pip` is installed if needed via a default command which looks like
   96 
   97     ```shell
   98     curl https://bootstrap.pypa.io/get-pip.py | sudo python
   99     ```
  100 
  101     This can be problematic in certain scenarios, for example, when behind a proxy. It is possible to override this default command by providing an explicit command to run as part of the config using `pip_install_cmd`. For example:
  102 
  103     ```ruby
  104     config.vm.provision "ansible_local" do |ansible|
  105       ansible.playbook = "playbook.yml"
  106       ansible.install_mode = "pip"
  107       ansible.pip_install_cmd = "https_proxy=http://your.proxy.server:port curl -s https://bootstrap.pypa.io/get-pip.py | sudo https_proxy=http/your.proxy.server:port python"
  108       ansible.version = "2.2.1.0"
  109     end
  110     ```
  111 
  112     In this case case `pip` will be installed via the command:
  113 
  114     ```shell
  115     https_proxy=http://your.proxy.server:port curl -s https://bootstrap.pypa.io/get-pip.py | sudo https_proxy=http://your.proxy.server:porpython
  116     ```
  117 
  118     If `pip_install_cmd` is not provided in the config, then `pip` is installed via the default command.
  119 
  120   - `:pip_args_only`: This mode is very similar to the `:pip` mode, with the difference that in this case no pip arguments will be automatically set by Vagrant.
  121 
  122     Example:
  123 
  124     ```ruby
  125     config.vm.provision "ansible_local" do |ansible|
  126       ansible.playbook = "playbook.yml"
  127       ansible.install_mode = "pip_args_only"
  128       ansible.pip_args = "-r /vagrant/requirements.txt"
  129     end
  130     ```
  131 
  132     With this configuration, Vagrant will install `pip` and then execute the command
  133 
  134     ```shell
  135     sudo pip install -r /vagrant/requirements.txt
  136     ```
  137 
  138     The default value of `install_mode` is `:default`, and any invalid value for this option will silently fall back to the default value.
  139 
  140 * `pip_args` (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, [`--index-url`](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-i)).
  141 
  142   By default, this option is not set.
  143 
  144   Example:
  145 
  146   ```ruby
  147   config.vm.provision "ansible_local" do |ansible|
  148     ansible.playbook = "playbook.yml"
  149     ansible.install_mode = :pip
  150     ansible.pip_args = "--index-url https://pypi.internal"
  151   end
  152   ```
  153 
  154   With this configuration, Vagrant will install `pip` and then execute the command
  155 
  156   ```shell
  157   sudo pip install --index-url https://pypi.internal --upgrade ansible
  158   ```
  159 
  160 * `provisioning_path` (string) - An absolute path on the guest machine where the Ansible files are stored. The `ansible-galaxy` and `ansible-playbook` commands are executed from this directory. This is the location to place an [ansible.cfg](http://docs.ansible.com/ansible/intro_configuration.html) file, in case you need it.
  161 
  162   The default value is `/vagrant`.
  163 
  164 * `tmp_path` (string) - An absolute path on the guest machine where temporary files are stored by the Ansible Local provisioner.
  165 
  166   The default value is `/tmp/vagrant-ansible`
  167 
  168 ## Tips and Tricks
  169 
  170 ### Install Galaxy Roles in a path owned by root
  171 
  172 ~> **Disclaimer:** 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.
  173 
  174 Be careful that `ansible-galaxy` command is executed by default as vagrant user. Setting `galaxy_roles_path` to a folder like `/etc/ansible/roles` will fail, and `ansible-galaxy` will extract the role a second time in `/home/vagrant/.ansible/roles/`. Then if your playbook uses `become` to run as `root`, it will fail with a _"role was not found"_ error.
  175 
  176 To work around that, you can use `ansible.galaxy_command` to prepend the command with `sudo`, as illustrated in the example below:
  177 
  178 ```ruby
  179 Vagrant.configure(2) do |config|
  180   config.vm.box = "centos/7"
  181   config.vm.provision "ansible_local" do |ansible|
  182     ansible.become = true
  183     ansible.playbook = "playbook.yml"
  184     ansible.galaxy_role_file = "requirements.yml"
  185     ansible.galaxy_roles_path = "/etc/ansible/roles"
  186     ansible.galaxy_command = "sudo ansible-galaxy install --role-file=%{role_file} --roles-path=%{roles_path} --force"
  187   end
  188 end
  189 ```
  190 
  191 ### Ansible Parallel Execution from a Guest
  192 
  193 With the following configuration pattern, you can install and execute Ansible only on a single guest machine (the `"controller"`) to provision all your machines.
  194 
  195 ```ruby
  196 Vagrant.configure("2") do |config|
  197 
  198   config.vm.box = "ubuntu/trusty64"
  199 
  200   config.vm.define "node1" do |machine|
  201     machine.vm.network "private_network", ip: "172.17.177.21"
  202   end
  203 
  204   config.vm.define "node2" do |machine|
  205     machine.vm.network "private_network", ip: "172.17.177.22"
  206   end
  207 
  208   config.vm.define 'controller' do |machine|
  209     machine.vm.network "private_network", ip: "172.17.177.11"
  210 
  211     machine.vm.provision :ansible_local do |ansible|
  212       ansible.playbook       = "example.yml"
  213       ansible.verbose        = true
  214       ansible.install        = true
  215       ansible.limit          = "all" # or only "nodes" group, etc.
  216       ansible.inventory_path = "inventory"
  217     end
  218   end
  219 
  220 end
  221 ```
  222 
  223 You need to create a static `inventory` file that corresponds to your `Vagrantfile` machine definitions:
  224 
  225 ```
  226 controller ansible_connection=local
  227 node1      ansible_host=172.17.177.21 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node1/virtualbox/private_key
  228 node2      ansible_host=172.17.177.22 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node2/virtualbox/private_key
  229 
  230 [nodes]
  231 node[1:2]
  232 ```
  233 
  234 And finally, you also have to create an [`ansible.cfg` file](https://docs.ansible.com/intro_configuration.html#openssh-specific-settings) to fully disable SSH host key checking. More SSH configurations can be added to the `ssh_args` parameter (e.g. agent forwarding, etc.)
  235 
  236 ```
  237 [defaults]
  238 host_key_checking = no
  239 
  240 [ssh_connection]
  241 ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes
  242 ```