Vultr: Create the Vultr Guide (#44515)

3 files changed, 146 insertions, 0 deletions

diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst
index 2763e839ff..a94fe09fec 100644
--- a/docs/docsite/rst/index.rst
+++ b/docs/docsite/rst/index.rst
@@ -59,6 +59,7 @@ Ansible releases a new major release of Ansible approximately every two months.
    scenario_guides/guide_rax
    scenario_guides/guide_rolling_upgrade
    scenario_guides/guide_vagrant
+   scenario_guides/guide_vultr
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/docsite/rst/scenario_guides/guide_vultr.rst b/docs/docsite/rst/scenario_guides/guide_vultr.rst
new file mode 100644
index 0000000000..39b2e66069
--- /dev/null
+++ b/docs/docsite/rst/scenario_guides/guide_vultr.rst
@@ -0,0 +1,144 @@
+Vultr Guide
+===========
+
+Ansible offers a set of modules to interact with `Vultr <https://www.vultr.com>`_ cloud platform.
+
+This set of module forms a framework that allows one to easily manage and orchestrate one's infratructure on Vultr cloud platform.
+
+
+Requirements
+------------
+
+There is actually no technical requirement; simply an already created Vultr account.
+
+
+Configuration
+-------------
+
+Vultr modules offer a rather flexible way with regard to configuration.
+
+Configuration is read in that order:
+
+- Environment Variables (eg. ``VULTR_API_KEY``, ``VULTR_API_TIMEOUT``)
+- File specified by environment variable ``VULTR_API_CONFIG``
+- ``vultr.ini`` file located in current working directory
+- ``$HOME/.vultr.ini``
+
+
+Ini file are structured this way:
+
+.. code-block:: ini
+
+  [default]
+  key = MY_API_KEY
+  timeout = 60
+
+  [personal_account]
+  key = MY_PERSONAL_ACCOUNT_API_KEY
+  timeout = 30
+
+
+If ``VULTR_API_ACCOUNT`` enviroment variable or ``api_account`` module parameter is not specified, modules will look for the section named "default".
+
+
+Authentication
+--------------
+
+Before using the Ansible modules to interact with Vultr, ones need an API key.
+If one doesn't own one yet, log in to `Vultr <https://www.vultr.com>`_ go to Account, then API, enable API then the API key should show up.
+
+Ensure you allow the usage of the API key from the proper IP addresses.
+
+Refer to the Configuration section to find out where to put this information.
+
+To check that everything is working properly run the following command:
+
+.. code-block:: console
+
+  #> VULTR_API_KEY=XXX ansible -m vultr_account_facts localhost
+  localhost | SUCCESS => {
+    "ansible_facts": {
+        "vultr_account_facts": {
+            "balance": -8.9,
+            "last_payment_amount": -10.0,
+            "last_payment_date": "2018-07-21 11:34:46",
+            "pending_charges": 6.0
+        }
+    },
+    "changed": false,
+    "vultr_account_facts": {
+        "balance": -8.9,
+        "last_payment_amount": -10.0,
+        "last_payment_date": "2018-07-21 11:34:46",
+        "pending_charges": 6.0
+    },
+    "vultr_api": {
+        "api_account": "default",
+        "api_endpoint": "https://api.vultr.com",
+        "api_retries": 5,
+        "api_timeout": 60
+    }
+  }
+
+
+If a similar output displays then everything is setup properly, else please ensure the proper ``VULTR_API_KEY`` has been specified and that Access Control on Vultr > Account > API page are accurate.
+
+
+Usage
+-----
+
+Since `Vultr <https://www.vultr.com>`_ offers a public API, the execution of the module to manage the infrastructure on their platform will happen on localhost. This translates to:
+
+.. code-block:: yaml
+
+  ---
+  - hosts: localhost
+    tasks:
+      - name: Create a 10G volume
+        vultr_block_storage:
+          name: my_disk
+          size: 10
+          region: New Jersey
+
+
+From that point on, only you creativity is the limit. Make sure to read the documentation of the `available modules <https://docs.ansible.com/ansible/latest/modules/list_of_cloud_modules.html#vultr>`_.
+
+
+Dynamic Inventory
+-----------------
+
+Ansible provides a dynamic inventory plugin for `Vultr <https://www.vultr.com>`_.
+The configuration process is exactly the same as the one for the modules.
+
+To be able to use it one needs to enable it first by specifying the following in the ``ansible.cfg`` file:
+
+.. code-block:: ini
+
+  [inventory]
+  enable_plugins=vultr
+
+And provide a configuration file to be used with the plugin, the minimal configuration file looks like this:
+
+.. code-block:: yaml
+
+  ---
+  plugin: vultr
+
+To list the available hosts one can simply run:
+
+.. code-block:: console
+
+  #> ansible-inventory - i vultr.yml
+
+
+This allows one - for example - to take action on nodes grouped by location or OS name:
+
+.. code-block:: yaml
+
+  ---
+  - hosts: Amsterdam
+    tasks:
+      - name: Rebooting the machine
+        shell: reboot
+        become: True
+
diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst
index 6358864484..4f91d570ec 100644
--- a/docs/docsite/rst/scenario_guides/guides.rst
+++ b/docs/docsite/rst/scenario_guides/guides.rst
@@ -16,5 +16,6 @@ This section is new and evolving.  The idea here is to explore particular use ca
    guide_rolling_upgrade
    guide_docker
    guide_packet
+   guide_vultr
 
 Pending topics may include: Docker, Jenkins, Google Compute Engine, Linode/DigitalOcean, Continuous Deployment, and more.