New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more detailed documentation on how to use multiple inventories #47586

Open
wants to merge 4 commits into
base: devel
from

Conversation

Projects
None yet
5 participants
@zharalim
Contributor

zharalim commented Oct 24, 2018

SUMMARY

Add a separate section on how to use multiple inventory directories with an example.

The documentation on multiple inventories was a bit hard to find as it was located only in the dynamic inventory documentation page. In addition that section doesn't have many details on how multiple inventories actually work.

This seems to be an undocumented feature related to "multiple sources" described in Working with dynamic inventory. Multiple sources documentation talks about using a directory and having multiple different inventory sources inside the directory. The new documented use case is different as it uses multiple inventory directories to promote DRY principle. The new documentation is in line with the comments in #36600 by @bcoca.

Using multiple directories is a bit cumbersome because you need to use multiple -i parameters but with ansible.cfg or ANSIBLE_INVENTORY it's manageable.

I understand if this is not a feature you want to promote in the docs, it resolved some issues for me so I thought that I'll try documenting it.

Comments appreciated :)

ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

documentation

ANSIBLE VERSION

Tested the example with 2.7. Should also work at least with 2.6.

ansible 2.7.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = [u'/home/vagrant/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python2.7/dist-packages/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.12 (default, Dec  4 2017, 14:50:18) [GCC 5.4.0 20160609]
ADDITIONAL INFORMATION

N/A

@ansibot

This comment has been minimized.

Contributor

ansibot commented Oct 24, 2018

Hi @zharalim, thank you for submitting this pull-request!

click here for bot help

@ansibot

This comment has been minimized.

Contributor

ansibot commented Oct 24, 2018

@zharalim

This comment has been minimized.

Contributor

zharalim commented Nov 3, 2018

I had another look on the dynamic inventory docs and realized that "Using Inventory Directories and Multiple Inventory Sources" is a related feature but not exactly the same thing. I removed the reference to that section from the new documentation. I also updated the pr description to better describe the issue.

@bcoca

You might want to start with 'multiple sources' and then show that using a directory is a way to aggregate sources and then give examples on that.

Show resolved Hide resolved docs/docsite/rst/user_guide/intro_inventory.rst Outdated

@ansibot ansibot added needs_revision and removed core_review labels Nov 5, 2018

@zharalim

This comment has been minimized.

Contributor

zharalim commented Nov 8, 2018

I added an example on how to aggregate sources with a directory and tried to take different inventory sources into consideration better than previously.

@acozine

This is great information - thank you @zharalim for putting it together. I think it could be made even better by making the example more detailed, to illustrate what happens when you amalgamate inventory sources in this way. Are you interested in working on this more?

Show resolved Hide resolved docs/docsite/rst/user_guide/intro_inventory.rst
Show resolved Hide resolved docs/docsite/rst/user_guide/intro_inventory.rst Outdated
Show resolved Hide resolved docs/docsite/rst/user_guide/intro_inventory.rst Outdated
Show resolved Hide resolved docs/docsite/rst/user_guide/intro_inventory.rst Outdated
@bcoca

bcoca approved these changes Nov 16, 2018

@ansibot ansibot added core_review and removed needs_revision labels Nov 16, 2018

@zharalim

This comment has been minimized.

Contributor

zharalim commented Nov 20, 2018

I'll see if I can make the use cases clearer and improve the examples.

@ansibot ansibot added the stale_ci label Nov 20, 2018

@ansibot ansibot added the docsite label Dec 4, 2018

@zharalim zharalim force-pushed the zharalim:doc_multiple_inventory_sources branch from 97613db to 52fe3a5 Dec 6, 2018

@ansibot ansibot removed the stale_ci label Dec 6, 2018

@zharalim

This comment has been minimized.

Contributor

zharalim commented Dec 6, 2018

Okay, hope it's a bit better now :)

Summary:

  • Simplified the examples
  • Removed the "common" inventory from the example as it felt a bit complicated
  • Described the use cases better and added examples on how variable conflicts work
  • Moved the new section to be right after "How variables are merged"
@bcoca

bcoca approved these changes Dec 6, 2018

@ansibot ansibot added the stale_ci label Dec 14, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment