Vanilla install from apt
Ubuntu 14.04 x64
The instructions on http://docs.ansible.com do not match the latest release, will mislead a new user and fail to instruct them to create a working digital_ocean playbook.
The reason is that the docs are unversioned, track the github head and do not contain information about breaking changes. If you install the latest released version from a package manager, you cannot read a compatible version of documentation on the ansible site.
For example, the current digital_ocean module page states "new in version 1.3". This implies that the documentation is compatible with any version more recent than 1.3 but because there are undocumented breaking changes which mean that parameters like region_id have changed type and have new expected values, the whole documentation page is terribly misleading.
Steps To Reproduce:
A new droplet is created
Depending on how you supply the api_token, your error might be
unsupported parameter for module: api_token
ValueError: invalid literal for int() with base 10: 'nyc2'
The remedy is to run ansible from the head source version and then following the documentation will be valid but it seems deeply ironic for a configuration management tool not to not let its users be strict about versioning!
I just got bit by this (I'm trying to learn Ansible). +1
+1 Just lost hours to this!
Hi, sorry for the inconvenience here. That parameter change should have been marked as version_added: 2.0, as it is not in the 1.9 branch at this time. This is partially due to the fact that the module was modified quite a bit for the new DO API, so some parameters were removed and others were added. The Notes section should also be more clear about this (and I will update the docs for now to state this).
If you would like to start using the new module version in 1.9.x, which matches the docs, you can download it from the git repository and replace your version of digital_ocean.py in site-packages/ansible/modules/core/cloud/digital_ocean/.
Beyond that, we have had plans internally for a couple of weeks to start offering two versions of the docs - stable and devel, which will track the current stable release and the devel branch to allow for more clear documentation, especially in cases like the above where a major change took place. Keep an eye out for this in the near future. Because of this, we're going to go ahead and close this issue for now. If you have any further questions regarding our docs plans please feel free to start a thread on one of the project mailing lists (preferably the ansible-devel list):
Thanks, and sorry again for the confusion!
I just checked http://docs.ansible.com/digital_ocean_module.html and I don't think that 'closed' addresses this issue - there's still no clear indication that this is for 2.x API and wont apply to us Ubuntu users who are on 1.9.1
"region_id | This is the slug of the region you would like your server to be created in."
this is infact not true
@dgtlmoon I closed this because the reported issue was about process, and not necessarily the mistake in the DO module docs. Due to the fact that the module changed significantly in devel, I'm leaning towards correcting that via the doc split I mentioned above. I will put a note in that doc though, to mention the change and that using ansible-doc digital_ocean will show you the correct documentation for your installed version.
@jmi-c how about only closing this once the stable docs have been released? As it stands, neither the specific digital ocean issue nor the general versioning issue have been resolved and new users will continue to lose time. The intention is great but if I closed all the things I intended to do...
I get the following:
msg: unsupported parameter for module: api_token
What am I supposed to do? I don't necessarily see the solution in this issue dialog.
@khomco it means you have a mismatched version of ansible vs. the docs. Follow the ansible installation instructions for installing from source rather than from a package manager and then following the docs should be correct and you will no longer get this error.
+1 on this issue, and agree with sentiments to not close until stable docs are released. From a newcomers perspective, a large part of the appeal of Ansible is the ease of ramp up and the thorough documentation. Not being able to trust that documentation definitely makes it difficult to sell.
To be fair, the docs have been updated to reflect the 2.0 nature of this feature. However, I suspect many tend to work top down, and may not get to that particular part of the document until after hitting several walls trying to get examples rolling from above sections. Perhaps something to chalk up to RTFM, but there it is.
I'm a newcomer and just lost hours to this problem.
If this is closed, is there a reference to a open issue where versioned documentation is the aim?