Merge pull request #2153 from gildegoma/ansible-docs-cleanup-and-vv

provisioners/ansible: Update documentation, Code Cleanup (and Extend Log Verbosity option)

plugins/provisioners/ansible/provisioner.rb

@@ -4,15 +4,13 @@ module VagrantPlugins
       def provision
         ssh = @machine.ssh_info
 
-        inventory_file_path = self.setup_inventory_file
+        # Connect with Vagrant user (unless --user or --private-key are overidden by 'raw_arguments')
         options = %W[--private-key=#{ssh[:private_key_path]} --user=#{ssh[:username]}]
 
         # Joker! Not (yet) supported arguments can be passed this way.
         options << "#{config.raw_arguments}" if config.raw_arguments
 
-        options << "--inventory-file=#{inventory_file_path}"
-        options << "--ask-sudo-pass" if config.ask_sudo_pass
-
+        # Append Provisioner options (higher precedence):
         if config.extra_vars
           extra_vars = config.extra_vars.map do |k,v|
             v = v.gsub('"', '\\"')
@@ -23,25 +21,13 @@ module VagrantPlugins
 
             "#{k}=#{v}"
           end
-
           options << "--extra-vars=\"#{extra_vars.join(" ")}\""
         end
-
-        if config.limit
-          if not config.limit.kind_of?(Array)
-            config.limit = [config.limit]
-          end
-          config.limit = config.limit.join(",")
-          options << "--limit=#{config.limit}"
-        end
-
+        options << "--inventory-file=#{self.setup_inventory_file}"
         options << "--sudo" if config.sudo
         options << "--sudo-user=#{config.sudo_user}" if config.sudo_user
-        if config.verbose
-          options << (config.verbose.to_s == "extra" ?  "-vvv" :  "--verbose")
-        end
-
-        # Append Provisioner options (higher precedence):
+        options << "#{self.get_verbosity_argument}" if config.verbose
+        options << "--ask-sudo-pass" if config.ask_sudo_pass
         options << "--tags=#{as_list_argument(config.tags)}" if config.tags
         options << "--skip-tags=#{as_list_argument(config.skip_tags)}" if config.skip_tags
         options << "--limit=#{as_list_argument(config.limit)}" if config.limit
@@ -70,6 +56,10 @@ module VagrantPlugins
         end
       end
 
+      protected
+
+      # Auto-generate "safe" inventory file based on Vagrantfile,
+      # unless inventory_path is explicitly provided
       def setup_inventory_file
         return config.inventory_path if config.inventory_path
 
@@ -86,7 +76,17 @@ module VagrantPlugins
         return generated_inventory_file.to_s
       end
 
-      protected
+      def get_verbosity_argument
+        if config.verbose.to_s =~ /^v+$/
+          # Hopefully ansible-playbook accepts "silly" arguments like '-vvvvv', as '-vvv'
+          "-#{config.verbose}"
+        elsif config.verbose.to_s == 'extra'
+          '-vvv'
+        else
+          # fall back to default verbosity
+          '--verbose'
+        end
+      end
 
       def as_list_argument(v)
         v.kind_of?(Array) ? v.join(',') : v

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

@@ -16,6 +16,15 @@ page will not go into how to use Ansible or how to write Ansible playbooks, sinc
 is a complete deployment and configuration management system that is beyond the scope of
 a single page of documentation.
 
+<div class="alert alert-warn">
+  <p>
+    <strong>Warning:</strong> If you're not familiar with Ansible and Vagrant already,
+    I recommend starting with the <a href="/v2/provisioning/shell.html">shell
+    provisioner</a>. However, if you're comfortable with Vagrant already, Vagrant
+    is a great way to learn Ansible.
+  </p>
+</div>
+
 ## Inventory File
 
 When using Ansible, it needs to know on which machines a given playbook should run. It does
@@ -122,7 +131,13 @@ These variables take the highest precedence over any other variables.
 * `ansible.sudo_user` can be set to a string containing a username on the guest who should be used
 by the sudo command.
 * `ansible.ask_sudo_pass` can be set to `true` to require Ansible to prompt for a sudo password.
-* `ansible.limit` can be set to a string or an array of machines or groups from the inventory file
-to further narrow down which hosts are affected.
-* `ansible.verbose` can be set to `true` to increase Ansible's verbosity to obtain more detailed logging
-during playbook execution.
+* `ansible.limit` can be set to a string or an array of machines or groups from the inventory file to further narrow down which hosts are affected.
+* `ansible.verbose` can be set to increase Ansible's verbosity to obtain full detailed logging. By default, Vagrant uses Ansible default verbosity (`--verbose` or `-v`). By enabling this option following higher verbosity can be activated:
+  * `'vv'`
+  * `'vvv'`, also aliased as `'extra'`
+* `ansible.tags` can be set to a string or an array of tags. Only plays, roles and tasks tagged with these values will be executed.
+* `ansible.skip_tags` can be set to a string or an array of tags. Only plays, roles and tasks that *do not match* these values will be executed.
+* `ansible.start_at_task` can be set to a string corresponding to the task name where the playbook provision will start.
+* `ansible.raw_arguments` is an *unsafe wildcard* string that can be used to take advantage of `ansible-playbook` arguments that are not (yet) supported by this Vagrant provisioner plugin. This can be very useful when integrating with bleeding edge Ansible versions. Following precedence rules apply:
+  * Any supported options (described above) will override conflicting `raw_arguments` value (e.g. `--tags` or `--start-at-task`)
+  * Vagrant default user authentication can be overridden via `raw_arguments` (with custom values for `--user` and `--private-key`)