Add some inventory plugin documentation #44727
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ansibot
added
affects_2.7
s-hertel
removed
the
needs_triage
s-hertel
force-pushed
the
add_more_inventory_docs
branch
3 times, most recently
from
ff27944
to
5dd5363
Compare
s-hertel
force-pushed
the
add_more_inventory_docs
branch
3 times, most recently
from
e34186e
to
f4fcccf
Compare
bcoca
reviewed
Aug 27, 2018
| @@ -39,6 +39,31 @@ The only requirement for using an inventory plugin after it is enabled is to pro | |||
| Ansible will try to use the list of enabled inventory plugins, in order, against each inventory source provided. | |||
| Once an inventory plugin succeeds at parsing a source, the any remaining inventory plugins will be skipped for that source. | |||
|
|
|||
| To transition to using an inventory plugin with a YAML configuration source from an inventory script, first create a file with the accepted filename schema for the plugin in question (each plugin should document any naming restrictions). For example, the aws_ec2 inventory plugin takes a file in the format <user_given_name>.aws_ec2.<yml/yaml> and the openstack inventory plugin parses clouds.<yml/yaml> or openstack.<yml/yaml>. After creating the file add ``plugin: plugin_name`` (where plugin_name could be aws_ec2, for example) to the first line. | |||
|
|
|||
| The 'auto' inventory plugin is enabled by default and works by using the first line of the configuration file to indicate the plugin that should attempt to parse it (which is aws_ec2 here). The whitelist is also configurable. After the plugin is enabled and any required options or credentials have been provided, the output of ``ansible-inventory -i demo.aws_ec2.yml --graph`` should be populated. To make a YAML configuration file accessible by default without specifying ``-i`` you can set the default inventory path (via ``inventory`` in the ansible.cfg [defaults] section or the :envvar:`ANSIBLE_HOSTS` environment variable) to your inventory source(s). Now running ``ansible-inventory --graph`` should yield the same output as when you passed your YAML configuration source(s) directly. Custom inventory plugins and the documentation required to parse sources may also be added in your plugin path to be used in the same way. | |||
There was a problem hiding this comment.
doesn't need to be the first line, since yaml reads the whole doc anyways it just needs to be th plugin: field
bcoca
reviewed
Aug 27, 2018
| The 'auto' inventory plugin is enabled by default and works by using the first line of the configuration file to indicate the plugin that should attempt to parse it (which is aws_ec2 here). The whitelist is also configurable. After the plugin is enabled and any required options or credentials have been provided, the output of ``ansible-inventory -i demo.aws_ec2.yml --graph`` should be populated. To make a YAML configuration file accessible by default without specifying ``-i`` you can set the default inventory path (via ``inventory`` in the ansible.cfg [defaults] section or the :envvar:`ANSIBLE_HOSTS` environment variable) to your inventory source(s). Now running ``ansible-inventory --graph`` should yield the same output as when you passed your YAML configuration source(s) directly. Custom inventory plugins and the documentation required to parse sources may also be added in your plugin path to be used in the same way. | ||
|
|
||
| The inventory source you provide may be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). The directory is parsed recursively alphabetically and is not configurable so things should be named accordingly for it to work predictably with constructed. If an inventory plugin you are using supports constructed itself you can work around this by adding your constructed groups to those inventory plugin configuration files (as now it will not use constructed until it has added your hosts from that source). You may also want to reorder the precedence of which plugin attempts to parse a source first using the using the ansible.cfg ['inventory'] `enable_plugins` list. | ||
|
|
There was a problem hiding this comment.
you an also use command line to impose order with multiple -i source as they are processed in that order
achinthagunasekara
approved these changes
Aug 27, 2018
s-hertel
force-pushed
the
add_more_inventory_docs
branch
from
1f6babe
to
1a6a3bd
Compare
…king for those moving from a script
s-hertel
force-pushed
the
add_more_inventory_docs
branch
from
1a6a3bd
to
9d4ca58
Compare
s-hertel
force-pushed
the
add_more_inventory_docs
branch
from
9d4ca58
to
4623f46
Compare
achinthagunasekara
approved these changes
Aug 28, 2018
acozine
approved these changes
Aug 29, 2018
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
SUMMARY
Add some additional documentation about getting inventory plugins working for those moving from a script.
ISSUE TYPE
COMPONENT NAME
docs/docsite/rst/plugins/inventory.rst
ANSIBLE VERSION