An open source solution for cost management of cloud and hybrid cloud environments.
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates (#117) May 9, 2018
apidoc Add apidoc generation and hosting. Closes #39. (#75) Apr 27, 2018
docs AWS Tags API (#574) Jan 17, 2019
koku Catch potential None in provider stats flow. #Closes 577. (#578) Jan 18, 2019
openshift add additional env vars to openshift template (#566) Jan 10, 2019
scripts small usability improvement to create-test-customer script (#568) Jan 11, 2019
.codecov.yml Updating patch section of codecov yaml for victory (#176) May 24, 2018
.coveragerc Integration work for 3scale gateway (#380) Sep 27, 2018
.env.example Provide an example environment file for faster on-boarding. (#49) Apr 20, 2018
.gitignore 160 instance trend updates (#267) Jul 19, 2018
.pyup.yml Added pipfile to .pyup.yaml (#55) Apr 20, 2018
.travis.yml add py37 env to tox.ini (#569) Jan 14, 2019
CONTRIBUTING.rst Make updates for project rename. Closes #62. (#65) Apr 26, 2018
Dockerfile fix openshift template & friends - make environment variables work ag… May 3, 2018
Dockerfile-env Adding report processing statistics to provider API response (#564) Jan 9, 2019
Dockerfile-test Koku docker compose (#539) Dec 20, 2018
LICENSE Update Licence Mar 23, 2018
Makefile Koku docker compose (#539) Dec 20, 2018
Pipfile Scheduled weekly dependency update for week 02 (#570) Jan 15, 2019
Pipfile.lock Scheduled weekly dependency update for week 02 (#570) Jan 15, 2019
README.rst Document Openshift as the preferred development setup. Closes #166. (#… Jun 14, 2018
apidoc.json Add apidoc generation and hosting. Closes #39. (#75) Apr 27, 2018
docker-compose.yml updating compose db credentials (#547) Jan 2, 2019
koku-test.yml Koku docker compose (#539) Dec 20, 2018 Koku docker compose (#539) Dec 20, 2018
tox.ini add py37 env to tox.ini (#569) Jan 14, 2019



license Build Status codecov Updates Python 3 Docs


Koku's goal is to provide an open source solution for cost management of cloud and hybrid cloud environments. This is offered via a web interface that exposes resource consumption and cost data in easily digestible and filterable views. The project also aims to provide insight into this data and ultimately provide suggested optimizations for reducing cost and eliminating unnecessary resource usage.

Full documentation is available through readthedocs.

Getting Started

This is a Python project developed using Python 3.6. Make sure you have at least this version installed.


To get started developing against Koku first clone a local copy of the git repository.

git clone

Developing inside a virtual environment is recommended. A Pipfile is provided. Pipenv is recommended for combining virtual environment (virtualenv) and dependency management (pip). To install pipenv, use pip

pip3 install pipenv

Then project dependencies and a virtual environment can be created using

pipenv install --dev

To activate the virtual environment run

pipenv shell

Preferred Environment

Please refer to Working with Openshift.

Alternative Environment

If deploying with Openshift seems overly complex you can try an alternate local environment where you will need to install and setup some of the dependencies and configuration.


This project is developed using the Django web framework. Many configuration settings can be read in from a .env file. An example file .env.example is provided in the repository. To use the defaults simply

cp .env.example .env

Modify as you see fit.


PostgreSQL is used as the database backend for Koku. A docker-compose file is provided for creating a local database container. If modifications were made to the .env file the docker-compose file will need to be modified to ensure matching database credentials. Several commands are available for interacting with the database.

# This will launch a Postgres container
make start-db

# This will run Django's migrations against the database
make run-migrations

# This will stop and remove a currently running database and run the above commands
make reinitdb

Assuming the default .env file values are used, to access the database directly using psql run

psql koku -U koku -h localhost -p 15432

There is a known limitation with docker-compose and Linux environments with SELinux enabled. You may see the following error during the postgres container deployment:

"mkdir: cannot create directory '/var/lib/pgsql/data/userdata': Permission denied" can be resolved by granting ./pg_data ownership permissions to uid:26 (postgres user in centos/postgresql-96-centos7)

If a docker container running Postgres is not feasible, it is possible to run Postgres locally as documented in the Postgres tutorial. The default port for local Postgres installations is 5432. Make sure to modify the .env file accordingly. To initialize the database run

make run-migrations

To run a local dev Django server you can use

make serve

API Documentation Generation

To generate and host the API documentation locally you need to Install APIDoc.

Generate the project API documenttion by running the following command

make gen-apidoc

In order to host the docs locally you need to collect the static files

make collect-static

Now start the server with as described above and point your browser to

Testing and Linting

Koku uses tox to standardize the environment used when running tests. Essentially, tox manages its own virtual environment and a copy of required dependencies to run tests. To ensure a clean tox environment run

tox -r

This will rebuild the tox virtual env and then run all tests.

To run unit tests specifically:

tox -e py36

To lint the code base

tox -e lint


Please refer to Contributing.