An inventory system to store, query and analyze infrastructure, configurations or any other type of data.

The system can be useful to store/query/analyze information such as configurations for loadbalancers, containers, virtual machines, physical hardware, cloud infrastructure/components or any other kind of data you see fit. Each asset has an associated type and can contain any kind of arbitrary given the system is schema less.

1. Installation
2. Configuration
3. Starting the Service
4. Auth Tokens
5. User Guide
6. Local Auth Groups
7. Development

System packages are available for installation. You can also manually build the project.

Godep (not needed for packaged install)
go >= 1.4.2 (not needed for packaged install)
elasticsearch >= 1.4.x

rpm and deb packages can be found on packagecloud.io. Installation instructions are also available there if needed.

To perform a manual install continue to the section below:

# Build and install
$ go get github.com/vindalu/vindalu
$ cd $GOPATH/src/github.com/vindalu/vindalu
$ godep restore
$ make all

This will install the the directory structure under ./build/opt/vindalu/, which should be copied to /opt/vindalu. Once copied change to that directory and proceed with configuration section.

Start by copying the sample configuration files in the etc directory.

$ cp etc/vindalu.json.sample etc/vindalu.json
$ cp etc/local-groups.json.sample etc/local-groups.json

Fill in the appropriate values keeping in mind that paths in the config file that do not start with / are treated as relative paths from the current working directory. After your configuration is complete you can start the service. Here's a description of the various configuration options.

Auth is required for all write requests as well as to listen to event subscriptions. By default basic http auth is enabled using the etc/htpasswd file. The default credentials are admin:vindaloo.

The groups_file is used to specify which users are allowed to create asset types as per the LocalAuthGroups. A sample config file is located under etc/.

LDAP auth is also available. This can be used by setting the type field to ldap and adding the appropriate options in the config section. The available options are url, search_base, cache_ttl, bind_dn, and bind_password. bind_password can either be a string or a location to a file containing the password. In the case of a file the path must be proceeded by file:// e.g (default).

file:///opt/vindalu/etc/bindpasswd

Currently, elasticsearch is the only supported backend. The only values that may require modifying are host and port based on your setup.

Endpoint configurations.

The required_fields specifies the fields that are required for any given asset (default: status, environment). Although more field requirments can be added, the default keys should not be removed.

The enforced_fields specifies fields that can only contain the specified values (default: status, environment).

This is the number of results that will be returned when the size parameter is not specified. (default: 100)

Path to the web directory.

The version field should not be touched. Changing this will prevent the process from starting up.

Once the installation and configuration are complete, you'll need to make sure elasticsearch is restarted. To do so run the following as necessary:

$ /etc/init.d/elasticsearch restart

Once elasticsearch is running (it can take some time to become available), execute the following command to start the service:

$ ./bin/vindalu-ctl start

You can now start using the system by using this http://localhost:5454 url.

Here you can find the basics and fundamentals to start using the inventory system.

Every asset has a asset type. To avoid the creation of unwanted types, only users in the admin group of the LocalAuthGroups are allowed to create asset types. The type will automatically be created upon the creation of the asset if done by an authorized admin user. More information about the LocalAuthGroups can be found below.

Versions are automatically created on each write. When a write occurs, the existing asset is copied over to the versions index incrementing the version number then performing the write. It is possible get a list of versions or specific versions of a given asset. A version to version diff can also be obtained.

Each asset must have an associated type. Before an asset can be created, the asset type must be created. As mentioned before, only admins are allowed to create new asset types. An asset has versions available. These are only available after the first write operation. A current asset has no version.

The following verbs and endpoints are available:

- GET /v3/

Response e.g.:

[
    {"name": "virtualserver", "count": 1233}, 
    {"name": "dnsrecord", "count": 1543}
]

- GET /v3/<asset_type>/properties

Response e.g.:

[
   "id",
   "timestamp",
   "created_by",
   "updated_by",
   "environment",
   "status",
   ...
]

- GET /v3/<asset_type>/<asset_id>

Response e.g.:

{
    "id": "foo.bar.org"
    "type":"virtualserver",
    "timestamp": <epoch>,
    "data":{
        "status":"running",
        "environment": "dev",
        "created_by": "user1",
        "updated_by": "user2"
        ....
    }
}

- GET /v3/<asset_type>/<asset_id>?version=<version>

The response is the same as an asset but also includes the version attribute.

Response e.g.:

{
    "id": "<asset_id>"
    "type":"<asset_type>",
    "timestamp": <epoch>,
    "data":{
        "status":"running",
        "environment": "dev",
        "version": <version>,
        "created_by": "user1",
        "updated_by": "user2"
        ....
    }
}

Asset versions can be obtained by calling the following endpoint.

- GET /v3/<asset_type>/<asset_id>/versions

Additionally version to version incremental diffs can also be obtained using the diff parameter.

- GET /v3/<asset_type>/<asset_id>/versions?diff

Response e.g.:

[{
    "version": 2,
    "against_version": 1,
    "updated_by": "....."
    "timestamp": <time_value>
    diff: "<diff_data>"
},{
    ....
}]

When creating an asset 2 fields are required - status and environment or as specified in your config. When creating an asset 2 additional fields are automatically added - created_by and updated_by with the user specified as part of the auth.

- POST /v3/<asset_type>/<asset_id>

    {
        "name": "foo.bar.com",
        "status": "running",
        "environment": "development"
        ...
    }

Response e.g.:

{ "id": "<asset_id>" }

Editing an asset will also update the updated_by field with the authenticated user.

- PUT /v3/<asset_type>/<asset_id>?delete_fields=foo,bar

    {
        "status": "stopped"
        "description": null
        ...
    }

Response e.g.:

{ "id": "<asset_id>" }

In the above example we update the status field and delete the fields called foo and bar.

- DELETE /v3/<asset_type>/<asset_id>

As a request body:

- GET /v3/<asset_type>

    {
        "status": "stopped",
        "os": "ubuntu"
    }

As query parameters:

- GET /v3/<asset_type>?status=stopped&os=ubuntu

This matches both attributes. Additionally the following parameters are also available:

• sort: Sort the result by the given attribute in ascending or descending order (e.g. sort=name:asc or sort=name:desc)

• from: This can be used for pagination to specify the offset (e.g. from=0)

• size: Number of results to return from the offset from if specified (e.g. size=100)

• aggregate: This is used to aggregate counts of a given field. For instance, for a field called os with values centos and ubuntu, to get a distinct count of values you would set the aggregator to os.

For example:

GET /v3/<asset_type>?aggregate=os

Response:

[{
    "name": "centos",
    "count": 200
},{
    "name": "ubuntu",
    "count": 123
}]

If enabled events are fired on all write actions. The available event types are:

Below are samples for each type:

{
    "type": "assettype.created",
    "timestamp": "....",
    "payload": {
        "id": "loadbalancer"
    }
} 

{
    "type": "asset.created",
    "timestamp": "....",
    "payload": {
        "id": "foo.bar.org",
        "type": "virtualserver",
        "timestamp": "...",
        "data": {
            "user_supplied": "data_on_creation"
        }
    }
}

{
    "type": "asset.updated",
    "timestamp": "....",
    "payload": {
        "id": "foo.bar.org",
        "type": "virtualserver",
        "timestamp": "...",
        "data": {
            "data_that": "was_updated"
        }
    }
}

{
    "type": "asset.deleted",
    "timestamp": "....",
    "payload": {
        "id": "foo.bar.org"
    }
}   

To use token authentication, you need generate a token with HTTP basic authentication (default login is admin/vindalu):

- POST /auth/access_token

Example:

$ curl -XPOST localhost:5454/auth/access_token -u admin
Enter host password for user 'admin':

Response:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiZXhwIjoxNDY3Njc2MDc2LCJpYXQiOjE0NDE3NTYwNzYsImlzcyI6InZpbmRhbG9vIiwic3ViIjoiYWRtaW4ifQ.gYN5tSk-ZYKQ--2w4NzuJ1Zt-VAnzOSCdDbl3JJK7P3" }

You can now use this token as a url parameter or in the header.

To use it as a url parameter, you need to use the access_token. Here is an example to create a new asset using the access_token parameter:

curl -XPOST localhost:5454/v3/serviceprofile/my_profile?access_token=<token> -d '{
    "status": "enabled",
    "environment": "production"
}'

The same request as above using headers, would look like this:

curl -XPOST -H "Authorization: BEARER <token>" localhost:5454/v3/serviceprofile/my_profile -d '{
    "status":" enabled",
    "environment": "production"
}'

Local auth groups are primarily used to create asset types. The configuration file can be found at etc/local-groups.json. Even though auth is disabled, a simple lookup against the local-groups.json file to prevent accidental asset type creation.

Add the usernames to the admin field you wish to allow. The user must match that used for 'HTTP Basic Auth'. The password can be left blank. If auth is enabled, then actual authentication with the backend will be performed.

Example:

{
    "admin": [ "user1", "user2" ]
}

In order to setup the development environment you'll need the following:

- Godep
- golang >= 1.4.2
- make
- docker

To perform a local (native) build you can simply run:

godep restore
make all

Assuming all requirements are met, a full linux build can be performed as follows:

./scripts/build.sh

This will produce the following:

• Linux binaries and other necessary files under the build folder

• A .rpm and .deb in the build folder

• A docker image called vindalu/vindalu

• Testing has primarily been done on Oracle 6.6/7 and docker though it should work on any OS as long as the requirements are met.