Home

Welcome to CMDB's documentation!

The configuration management database (CMDB) is a system that stores server information.

Requirements

In order to use this tool, there are a few things you need to install.

1. Python
2. swig
3. MySQL server
4. virtualenv

Installation

1. Make sure all the requirements from the prior section are installed.
2. Clone this repo.
3. Create a new virtual environment and enter it. Run:

$ virtualenv venv
$ source venv/bin/activate

1. Install the requirements. Run:

(venv)$ pip install -r requirements.txt

Core Components

These parts of the project contain the core functionality of CMDB. These include:

• A database that stores server information along with an API
  • Using the database API directly does not provide authentication and authorization, so it is recommended to use the HTTP API to interact with the database
• An HTTP API for interacting with the database
• A Python client library for the HTTP API

Database

The database is the most important part of CMDB. It organizes and stores all metadata about servers. We expose an API to directly communicate with the database.

Features

There are three types of information that the CMDB stores.

1. Fields: these are the fields that the database is configured with, which currently are: the application, environment, and tier.
2. Tags: these are arbitrary key-value pairs that servers can be attributed with.
3. VIPs: VIPs, or Virtual IP addresses, have their own endpoint. They can also be tagged with arbitrary key-value pairs, servers can be associated with the VIPs, and there can be names associated with the VIPs.

In addition, there is a filtering system in place so you can search for servers that match the particular field, tag or VIP. However, this best used through the web and client APIs.

Getting started

In order to use any of the other components, you need to configure the database. Make sure that a "cmdb" database is created in mysql. To do so, just run (as root mysql user)

mysql> CREATE USER '<username>'@'localhost' IDENTIFIED BY '<password>';
mysql> CREATE DATABASE cmdb;
mysql> GRANT ALL on cmdb.* to '<username>'@'localhost';

Usage

Visit the CMDB API page to learn about how to use the cmdb API and what methods are available.

Web API Server

The Web API Server is a Flask application that communicates with the database.

Features

• Authentication: There is a user/ password system in place for security. Once a user has authenticated, they will be given a session ID which they can then use for authentication for subsequent requests to the server.

• Authorization: There are three permissions for users.

  1. Read: A user with read permission can only view data.
  2. Write: A user with write permission can read and write to the database.
  3. Admin: A user with admin permission can read and write to the database in addition to adding/deleting users and setting user permissions.

Getting started

Once a server database has been created, you can start up the Flask server (make sure you are in the virtualenv). Run:

$ source bin/activate
(venv)$ cd src
(venv)$ python server.py -u <username> -p <password>

You can specify what hostname or port of the server by using the optional arguments -H, --host or -P, --port. For example:

(venv)$ python server.py -u <username> -p <password> --host localhost --port 80

The default host is 127.0.0.1 and the default port is 5000. The first POST request to the /user endpoint will create an administrative user that will be able to create other users, so make sure do this first:

$ curl -X POST -H "Content-Type: application/json" 127.0.0.1:5000/user --data '{"username": "<admin username here>", "password": "<admin password here>"}'

Usage

Once the server is established, you can make HTTP requests to the Web API. Look at the documentation located server.

Python Client Library

The Python client library sends HTTP requests to a given web API server.

Features

The Python client library properly formats the requests to a given web API server, according to the API defined in the web API server, and handles passing in session tokens.

Getting started

For an application to use the client library, you only need to include the cmdb_client.py file in your $PYTHONPATH and say:

import cmdb_client

in your application to get full access to it.

Usage

Visit the client API page to learn about how to use the cmdb_client API and what methods are provided.

Documentation

In order to properly generate the documentation, make sure you have the requirements installed from the installation section above. To view documentation, run (in the virtualenv):

(venv)$ cd docs
(venv)$ make html

Parsing Scripts

In addition to the core features which focus on interacting with and serving server information, we also have a set of scripts that allow for easy importing of already existing server configurations. You can add them to your $PATH or just use the scripts in the repository.

SoftLayer

One source of server configuration is the SoftLayer JSON files. The populate_db script takes in a json file and populates the database with information from that json file.

Usage

To run the script, you should have a server running along with a username and password in the database. This line of code will run the script:

$ populate_db.py [--html HTML] username password server json

Required arguments:

username    Username for authentication for the cmdb
password    Password for the corresponding username
server      URL of the server
json        Full path of the file that contains the metadata in JSON

Optional arguments:

--html HTML  Full path of the file that contains the tier configuration

Puppet

Another source of server information can come from existing Puppet config files. The parse_vip_puppet script takes a recipe and populates the database with vip information.

Usage

To run the script, you should have a server running along with a username and password in the database. This line of code will run the script:

$ parse_vip_puppet.py username password server file_path

Required arguments:

username    Username for authentication for the cmdb
password    Password for the corresponding username
server      URL of the server
file_path   Full path of the file that contains the tier configuration information