diff options
author | Yanis Guenane <yguenane@gmail.com> | 2018-08-31 16:42:07 +0200 |
---|---|---|
committer | ansibot <ansibot@users.noreply.github.com> | 2018-08-31 10:42:07 -0400 |
commit | 857a553fa10eed015b11e8c8f323920915281f03 (patch) | |
tree | b7089fcb9f7d6898e6c93cebcbd56bb22e2d1d31 | |
parent | fbf55a09cc80a5c762e67c4935cccfe8dd1c2898 (diff) | |
download | ansible-857a553fa10eed015b11e8c8f323920915281f03.tar.gz |
Vultr: Create the Vultr Guide (#44515)
-rw-r--r-- | docs/docsite/rst/index.rst | 1 | ||||
-rw-r--r-- | docs/docsite/rst/scenario_guides/guide_vultr.rst | 144 | ||||
-rw-r--r-- | docs/docsite/rst/scenario_guides/guides.rst | 1 |
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. |