Merge pull request #9869 from hashicorp/review/pr-9864

Review and Adaptation to PR #9864

website/source/docs/provisioning/ansible_common.html.md

@@ -86,6 +86,10 @@ Some of these options are for advanced usage only and should not be used unless
 
     Note: if an absolute path is given, the `ansible_local` provisioner will assume that it corresponds to the exact location on the guest system.
 
+    ```ruby
+    ansible.galaxy_role_file = "requirements.yml"
+    ```
+
 - `galaxy_roles_path` (string) - The path to the directory where Ansible Galaxy roles must be installed
 
     By default, this option is set to `nil`, which means that the Galaxy roles will be installed in a `roles` subdirectory located in the parent directory of the `playbook` file.

website/source/docs/provisioning/ansible_local.html.md

@@ -143,6 +143,29 @@ This section lists the _specific_ options for the Ansible Local provisioner. In
 
 ## Tips and Tricks
 
+### Install Galaxy Roles in a path owned by root
+
+ <div 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.
+</div>
+
+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.
+
+To work around that, you can use `ansible.galaxy_command` to prepend the command with `sudo`, as illustrated in the example below:
+
+```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
+```
+
 ### Ansible Parallel Execution from a Guest
 
 With the following configuration pattern, you can install and execute Ansible only on a single guest machine (the `"controller"`) to provision all your machines.