Skip to content

Latest commit

 

History

History
168 lines (124 loc) · 5.86 KB

dev.md

File metadata and controls

168 lines (124 loc) · 5.86 KB

Contributions

If you wish to contribute code, please consider the following:

  • Code should be reasonably PEP8-like. I'm not too strict on this.
  • One logical change per merge request.
  • By putting in a merge request or putting code in comments, you automatically grant me permission to include this code in ansible-cmdb under the license (GPLv3) that ansible-cmdb uses. The copyright for contributed code is retained by the contributor.
  • Please don't be disappointed or angry if your contributions end up unused. It's not that they aren't appreciated, but I can be somewhat strict when it comes to code quality, feature creep, etc.

When in doubt, just open a pull request and post a comment on what you're unclear of, and we'll figure it out.

Inner workings

Here's a quick introduction on how ansible-cmdb works internally.

  1. The main section in ansible-cmdb reads the commandline params and instantiates an Ansible object.
  2. The Ansible object first reads in all the facts by calling Ansible.parse_fact_dir() for each argument. This includes the user-extended facts.
  3. If hosts file(s) should be parsed (-i option), ansible calls Ansible.parse_hosts_inventory(). This first reads in all found hosts files into one big string, and then it parses it. For this it uses the AnsibleHostParser class.
  4. The AnsibleHostParser class first parses the inventory and then creates a dictionary with all known ansible node names (hosts) as the keys, but with empty values. It then goes through the 'children', 'vars' and normal sections from the inventory and applies the found information to the hosts dictionary.
  5. When AnsibleHostParser is done, the Ansible class takes all the parsed hosts information and updates its own version of the hosts dictionary.
  6. Finally, the output is generated by the main section.

Updating a host in the Ansible object is done using the Ansible.update_host method. This method does a deep-update of a dictionary. This lets ansible-cmdb overlay information from the facts dir, extended / manual facts and hosts inventory files.

Running from the git repo

If you want to run ansible-cmdb directly from the Git repo:

$ cd ansible-cmdb
$ export PYTHONPATH="$(readlink -f lib)"
$ src/ansible-cmdb

Building

Make targets

For building, make is used. Here are some useful targets:

  • make test: build some tests.
  • make release: build a release.
  • make clean: remove build and other artifacts.

Build packages and source-ball

To build Debian, RedHat and source-packages for ansible-cmdb you'll need a Debian based operating system and you'll have to install the following dependencies:

  • git
  • make
  • python-markdown
  • zip
  • fakeroot
  • alien
  • Python 'wheel' package

You can then build the packages with

make release REL_VERSION=$VERSION

where $VERSION is a (arbitrary) version number.

In order to build releases, your repository will have to be completely clean: everything must be commited and there must be no untracked files. If you want to build a test release, you can temporary stash your untracked changes:

git stash -u

Testing

Testing releases:

Running from github source:

$ cd ansible-cmdb
$ export PYTHONPATH=lib
$ src/ansible-cmdb examples/out > ~/cmdb.html
$ src/ansible-cmdb -i examples/hosts examples/out > ~/cmdb.html
$ src/ansible-cmdb -p local_js=1 -i examples/hosts examples/out > ~/cmdb.html

Installing from github source:

$ cd ansible-cmdb
$ sudo python ./setup.py install
$ ansible-cmdb ansible-cmdb/examples/out > ~/cmdb.html
$ ansible-cmdb -i ansible-cmdb/examples/hosts ansible-cmdb/examples/out > ~/cmdb.html
$ ansible-cmdb -p local_js=1 -i ansible-cmdb/examples/hosts ansible-cmdb/examples/out > ~/cmdb.html
$ sudo pip uninstall mako
$ sudo pip uninstall pyyaml
$ sudo pip uninstall ansible-cmdb
$ sudo rm /usr/local/bin/ansible-cmdb

Installing from source tarbal:

$ tar -vxzf ansible-cmdb-*.tar.gz
$ cd ansible-cmdb-*
$ sudo make install
$ ansible-cmdb out > ~/cmdb.html
$ ansible-cmdb -i hosts out > ~/cmdb.html
$ ansible-cmdb -p local_js=1 -i hosts out > ~/cmdb.html
$ cd ansible-cmdb-*
$ sudo make uninstall

Installing from .deb file:

$ dpkg -i -i ansible-cmdb-*.deb
$ ansible-cmdb out > ~/cmdb.html
$ ansible-cmdb -i hosts out > ~/cmdb.html
$ ansible-cmdb -p local_js=1 -i hosts out > ~/cmdb.html
$ sudo dpkg --purge ansible-cmdb

Installing from .rpm file:

$ sudo yum install ansible-cmdb*.rpm
$ ansible-cmdb out > ~/cmdb.html
$ ansible-cmdb -i hosts out > ~/cmdb.html
$ ansible-cmdb -p local_js=1 -i hosts out > ~/cmdb.html
$ sudo yum uninstall ansible-cmdb

License

Ansible-cmdb is licensed under the GPLv3:

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

For the full license, see the LICENSE file.

History

Ansible-cmdb started as a short Python script, which I blogged about.

Cris van Pelt then took that and expanded it into a HTML page. Eventually I forked it to Github and made it public, adding features. Many people collaborated to make Ansible-cmdb into what it is today.