"Fossies" - the Fresh Open Source Software Archive

Member "vagrant-2.2.14/website/pages/docs/provisioning/ansible_intro.mdx" (20 Nov 2020, 11181 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 - Short Introduction
    4 sidebar_title: Ansible Intro
    5 description: |-
    6   This page includes options and information that is applicable to both Vagrant
    7   Ansible provisioners.
    8 ---
    9 
   10 # Ansible and Vagrant
   11 
   12 The information below is applicable to both Vagrant Ansible provisioners:
   13 
   14 - [`ansible`](/docs/provisioning/ansible), where Ansible is executed on the **Vagrant host**
   15 - [`ansible_local`](/docs/provisioning/ansible_local), where Ansible is executed on the **Vagrant guest**
   16 
   17 The list of common options for these two provisioners is documented in a [separate documentation page](/docs/provisioning/ansible_common).
   18 
   19 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.
   20 
   21 To learn more about Ansible, please consult the [Ansible Documentation Site](https://docs.ansible.com/).
   22 
   23 ## The Playbook File
   24 
   25 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
   26 [playbook documentation](https://docs.ansible.com/playbooks.html) goes into great detail on how to author playbooks, and there are a number of [best practices](https://docs.ansible.com/playbooks_best_practices.html) that can be applied to use Ansible's powerful features effectively.
   27 
   28 A playbook that installs and starts (or restarts) the NTP daemon via YUM looks like:
   29 
   30 ```
   31 ---
   32 - hosts: all
   33   tasks:
   34     - name: ensure ntpd is at the latest version
   35       yum: pkg=ntp state=latest
   36       notify:
   37       - restart ntpd
   38   handlers:
   39     - name: restart ntpd
   40       service: name=ntpd state=restarted
   41 ```
   42 
   43 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.
   44 
   45 ### Running Ansible
   46 
   47 The `playbook` option is strictly required by both Ansible provisioners ([`ansible`](/docs/provisioning/ansible) and [`ansible_local`](/docs/provisioning/ansible_local)), as illustrated in this basic `Vagrantfile` configuration:
   48 
   49 ```ruby
   50 Vagrant.configure("2") do |config|
   51 
   52   # Use :ansible or :ansible_local to
   53   # select the provisioner of your choice
   54   config.vm.provision :ansible do |ansible|
   55     ansible.playbook = "playbook.yml"
   56   end
   57 end
   58 ```
   59 
   60 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:
   61 
   62 ```text
   63 .
   64 |-- Vagrantfile
   65 |-- provisioning
   66 |   |-- group_vars
   67 |           |-- all
   68 |   |-- roles
   69 |           |-- bar
   70 |           |-- foo
   71 |   |-- playbook.yml
   72 ```
   73 
   74 In such an arrangement, the `ansible.playbook` path should be adjusted accordingly:
   75 
   76 ```ruby
   77 Vagrant.configure("2") do |config|
   78   config.vm.provision "ansible" do |ansible|
   79     ansible.playbook = "provisioning/playbook.yml"
   80   end
   81 end
   82 ```
   83 
   84 ## The Inventory File
   85 
   86 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/intro_inventory.html) file which lists those machines. In the context of Vagrant, there are two ways to approach working with inventory files.
   87 
   88 ### Auto-Generated Inventory
   89 
   90 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.
   91 
   92 #### Example with the [`ansible`](/docs/provisioning/ansible) provisioner
   93 
   94 ```text
   95 # Generated by Vagrant
   96 
   97 default ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/default/virtualbox/private_key'
   98 ```
   99 
  100 Note that the generated inventory file is stored as part of your local Vagrant environment in
  101 `.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory`.
  102 
  103 #### Example with the [`ansible_local`](/docs/provisioning/ansible_local) provisioner
  104 
  105 ```text
  106 # Generated by Vagrant
  107 
  108 default ansible_connection=local
  109 ```
  110 
  111 Note that the generated inventory file is uploaded to the guest VM in a subdirectory of [`tmp_path`](/docs/provisioning/ansible_local), e.g. `/tmp/vagrant-ansible/inventory/vagrant_ansible_local_inventory`.
  112 
  113 #### Host Variables
  114 
  115 As of Vagrant 1.8.0, the [`host_vars`](/docs/provisioning/ansible_common#host_vars) option can be used to set [variables for individual hosts](https://docs.ansible.com/ansible/intro_inventory.html#host-variables) in the generated inventory file (see also the notes on group variables below).
  116 
  117 With this configuration example:
  118 
  119 ```ruby
  120 Vagrant.configure("2") do |config|
  121   config.vm.define "host1"
  122   config.vm.define "host2"
  123   config.vm.provision "ansible" do |ansible|
  124     ansible.playbook = "playbook.yml"
  125     ansible.host_vars = {
  126       "host1" => {"http_port" => 80,
  127                   "maxRequestsPerChild" => 808},
  128       "host2" => {"http_port" => 303,
  129                   "maxRequestsPerChild" => 909}
  130     }
  131   end
  132 end
  133 ```
  134 
  135 Vagrant would generate the following inventory file:
  136 
  137 ```text
  138 # Generated by Vagrant
  139 
  140 host1 ansible_ssh_host=... http_port=80 maxRequestsPerChild=808
  141 host2 ansible_ssh_host=... http_port=303 maxRequestsPerChild=909
  142 ```
  143 
  144 #### Groups and Group Variables
  145 
  146 The [`groups`](/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.
  147 
  148 As of Vagrant 1.8.0, it is also possible to specify [group variables](https://docs.ansible.com/ansible/intro_inventory.html#group-variables), and group members as [host ranges (with numeric or alphabetic patterns)](https://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups).
  149 
  150 With this configuration example:
  151 
  152 ```ruby
  153 Vagrant.configure("2") do |config|
  154 
  155   config.vm.box = "ubuntu/trusty64"
  156 
  157   config.vm.define "machine1"
  158   config.vm.define "machine2"
  159 
  160   config.vm.provision "ansible" do |ansible|
  161     ansible.playbook = "playbook.yml"
  162     ansible.groups = {
  163       "group1" => ["machine1"],
  164       "group2" => ["machine2"],
  165       "group3" => ["machine[1:2]"],
  166       "group4" => ["other_node-[a:d]"], # silly group definition
  167       "all_groups:children" => ["group1", "group2"],
  168       "group1:vars" => {"variable1" => 9,
  169                         "variable2" => "example"}
  170     }
  171   end
  172 end
  173 ```
  174 
  175 Vagrant would generate the following inventory file:
  176 
  177 ```text
  178 # Generated by Vagrant
  179 
  180 machine1 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine1/virtualbox/private_key'
  181 machine2 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine2/virtualbox/private_key'
  182 
  183 [group1]
  184 machine1
  185 
  186 [group2]
  187 machine2
  188 
  189 [group3]
  190 machine[1:2]
  191 
  192 [group4]
  193 other_node-[a:d]
  194 
  195 [all_groups:children]
  196 group1
  197 group2
  198 
  199 [group1:vars]
  200 variable1=9
  201 variable2=example
  202 ```
  203 
  204 **Notes:**
  205 
  206 - 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.
  207 - 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.
  208 - Unmanaged machines and undefined groups are not added to the inventory, to avoid useless Ansible errors (e.g. _unreachable host_ or _undefined child group_)
  209 
  210   For example, `machine3` and `group3` in the example below would not be added to the generated inventory file:
  211 
  212   ```ruby
  213   ansible.groups = {
  214     "group1" => ["machine1"],
  215     "group2" => ["machine2", "machine3"],
  216     "all_groups:children" => ["group1", "group2", "group3"]
  217   }
  218   ```
  219 
  220 - [Host range patterns (numeric and alphabetic ranges)](https://docs.ansible.com/ansible/intro_inventory.html#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_).
  221 
  222 ### Static Inventory
  223 
  224 The second option is for situations where you would like to have more control over the inventory management.
  225 
  226 With the [`inventory_path`](/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.
  227 
  228 A very simple inventory file for use with Vagrant might look like:
  229 
  230 ```text
  231 default ansible_ssh_host=192.168.111.222
  232 ```
  233 
  234 Where the above IP address is one set in your Vagrantfile:
  235 
  236 ```text
  237 config.vm.network :private_network, ip: "192.168.111.222"
  238 ```
  239 
  240 **Notes:**
  241 
  242 - The machine names in `Vagrantfile` and `ansible.inventory_path` files should correspond, unless you use `ansible.limit` option to reference the correct machines.
  243 - 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"`.
  244 - The SSH host addresses (and ports) must obviously be specified twice, in `Vagrantfile` and `ansible.inventory_path` files.
  245 - 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)).
  246 
  247 ### The Ansible Configuration File
  248 
  249 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.
  250 
  251 When shipping an Ansible configuration file it is good to know that:
  252 
  253 - as of Ansible 1.5, the lookup order is the following:
  254   - any path set as `ANSIBLE_CONFIG` environment variable
  255   - `ansible.cfg` in the runtime working directory
  256   - `.ansible.cfg` in the user home directory
  257   - `/etc/ansible/ansible.cfg`
  258 - Ansible commands don't look for a configuration file relative to the playbook file location (e.g. in the same directory)
  259 - an `ansible.cfg` file located in the same directory as your `Vagrantfile` will be used by default.
  260 - it is also possible to reference any other location with the [config_file](/docs/provisioning/ansible_common#config_file) provisioner option. In this case, Vagrant will set the `ANSIBLE_CONFIG` environment variable accordingly.