Merge pull request #11 from eduardocerqueira/python3

Janitor upgrade to run on python3

AUTHORS

@@ -1,7 +1,6 @@
-All the team members and collaborators
-that touched this project somehow will be added to the list
-below:
+All collaborators with this project:
 
-Team Members:
+Collaborators:
 -------------
-- Eduardo Cerqueira <[email protected]>
+- Eduardo Cerqueira <https://github.com/eduardocerqueira>
+- Pavol Kotvan <https://github.com/patchkez>

Makefile

@@ -2,10 +2,10 @@ default: help
 
 NAME=janitor
 MAN=janitor.1
-VERSION=0.1
+VERSION=0.2
 RPMDIST=$(shell rpm --eval '%dist')
 #RELEASE=1$(rpmsuffix)$(RPMDIST)
-RELEASE=1
+RELEASE=0
 PWD=$(shell bash -c "pwd -P")
 RPMTOP=$(PWD)/rpmbuild
 SPEC=$(NAME).spec
@@ -18,7 +18,7 @@ help:
 	@echo
 	@echo "clean     clean temp files from local workspace"
 	@echo "doc       generate sphinx documentation and man pages"
-	@echo "test      run unit tests locally"
+	@echo "test      run functional/unit tests locally"
 	@echo "tarball   generate tarball of p roject"
 	@echo "rpm       build source codes and generate rpm file"
 	@echo "srpm      generate SRPM file"

README.md

@@ -1,38 +1,193 @@
 
 ![copr build](https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/package/janitor/status_image/last_build.png)
 
-# janitor
+# Janitor
 
-MOTIVATION
-----------
+<img align="left" width="100" height="100" src="https://raw.githubusercontent.com/eduardocerqueira/janitor/python3/docs/source/logo.jpg">
 
-One of my Openstack tenants that I use to run tests for an internal tool has a very limited quota so all the time I need to stop my tests and automations and spend few minutes
-cleaning up public/floating ips, destroying virtual machines and others. The idea to have janitor or a butler is actually an old idea and a coworker had implemented
-it but in a more sophisticated and fashion way this is a simply version and currently only focusing in Openstack maybe further I'll extend it to AWS, Openshift and others.
+Janitor is a Linux component to perform quota management tasks to an [Openstack](https://www.openstack.org/) tenant. 
 
-WHAT IS THIS
--------------
+It `is not` an official Openstack's tool, and Janitor's code is wrapping Openstack python client libraries:
 
-Linux tool to help clean-up tasks for Openstack.
+* [python-openstackclient](https://pypi.org/project/python-openstackclient/) to manage authentication and as general API 
+* [python-neutronclient](https://github.com/openstack/python-neutronclient) to manage network
+* [python-novaclient](https://github.com/openstack/python-novaclient) to manage compute nodes and vms
+* [python-glanceclient](https://github.com/openstack/python-glanceclient) to manage cloud images
+* [python-cinderclient](https://github.com/openstack/python-cinderclient) to manage volumes and block storage
 
-USAGE
+## Table of content
+* [Motivation](README.md#motivation)
+* [Install and usage](README.md#install-and-usage)
+* [Setup your dev environment](README.md#local-dev-environment)
+* [Running janitor functional tests](tests/README.md#janitor-tests)
+* [Contributing](README.md#contributing)
+* [Build RPM and release](README.md#build-rpm-and-release)
+* [DEMO](README.md#demo)
 
-clean up virtual machines and release floating ips for Openstack keep items declared in the whitelist.txt file:
+## Motivation
 
-1. load your Openstack rc to system environment variable or pass as parameter
-2. run janitor
+I have been using OpenStack continuously since 2014 as a resource to run workloads with the main purpose of 
+testing software. Manage a healthy Openstack tenant quota is vital when working with CI/CD and a large number of 
+automated pipelines which run 24/7. A long time ago I and my team were having a lot of headaches with one of internal 
+Openstack the cluster which at that time had a very limited quota and workload capacity but was important for the 
+test workflow. With the constant false-positive for test failing due to lack of public/floating IP, storage/volume, 
+and even virtual CPU when provisioning new VMs, we got the idea of implementing Janitor, a super simple script/codes 
+to `automate the clean-up task of deleting left-over virtual machines as well network and volume from an Openstack 
+tenant, all managed by API and remote calls.`  
 
-    source ~/mytenant-openrc.sh
 
-	janitor openstack --whitelist /tmp/whitelist.txt --keystone v3
-	janitor openstack --openrc /tmp/mytenant-openrc.sh --whitelist /tmp/whitelist.txt --keystone v3
+## Install and Usage
+
+For [Fedora](https://fedoraproject.org/):
+
+1. from [Copr](https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/) 
+
+```
+dnf copr enable eduardocerqueira/janitor
+dnf install janitor
+```
+
+or if you prefer you can install the repo from https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/
+and maybe is needed to disable **gpgcheck=0**
+
+```
+[eduardocerqueira-janitor]
+name=Copr repo for janitor owned by eduardocerqueira
+baseurl=https://copr-be.cloud.fedoraproject.org/results/eduardocerqueira/janitor/epel-7-$basearch/
+type=rpm-md
+skip_if_unavailable=True
+gpgcheck=0
+gpgkey=https://copr-be.cloud.fedoraproject.org/results/eduardocerqueira/janitor/pubkey.gpg
+repo_gpgcheck=0
+enabled=1
+enabled_metadata=1
+```
+
+2. from local build::
+
+```
+make rpm
+dnf install rpmbuild/RPMS/x86_64/janitor-0.2-0.x86_64.rpm
+```
+
+for CentOS:
+
+**requires openstack repo**. check the latest repo https://wiki.openstack.org/wiki/Release_Naming
+
+```
+sudo yum install centos-release-openstack-newton.noarch
+sudo yum install install rpmbuild/RPMS/x86_64/janitor-0.2-0.x86_64.rpm
+```
+
+using Janitor to clean up left-over virtual machines and release floating ips for Openstack tenant:
+
+```
+source ~/mytenant-openrc.sh
+janitor openstack --whitelist /tmp/whitelist.txt --keystone v3
+
+# or passing the path for your openrc file
+janitor openstack --openrc /tmp/mytenant-openrc.sh --whitelist /tmp/whitelist.txt --keystone v3
+```
 
 listing history for your janitor:
 
-	janitor history
+```
+janitor history
+```
+
+## local dev environment
+
+**Requirements:**
+* Linux OS *tested on Fedora and CentOS*
+* Python3
+* packages: 
+
+```
+# install packages needed to interact with make, build RPM, make release to Copr, and generate doc
+sudo dnf install redhat-rpm-config rpm-build python3-devel gcc python3-devel python3-pip python3-wheel python3-setuptools, python3-sphinx copr-cli
+
+# prep your python env
+git clone [email protected]:eduardocerqueira/janitor.git
+cd janitor
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements/devel.txt
+
+# check janitor installation
+python janitor/cli.py --help
+openstack --openrc /home/ecerquei/osp/janitor-openrc.sh --whitelist /home/ecerquei/osp/janitor-whitelist.txt --keystone v3
+```
+
+see [running janitor functional tests](tests/README.md#janitor-tests)
+
+also you can explore the  **make tasks** running `make`.
+
+when running `make doc` the generated doc can be access at : file:///home/user/git/janitor/docs/build/html/index.html
+
+
+## Contributing
+
+Any idea, suggestions and pacthes are welcome to this project! Fork the project, make your code change, run the test locally
+to ensure your changes are not breaking any functionality, remember to run the code static analysis before submitting your 
+PR and if needed open [issues or discussion](https://github.com/eduardocerqueira/janitor/issues) on this project.
+
+```
+# make flake8
+```
+
+## Build RPM and release
+
+	$ make
+
+	Usage: make <target> where <target> is one of
+
+	clean     clean temp files from local workspace
+	doc       generate sphinx documentation and man pages
+	test      run functional/unit tests locally
+	tarball   generate tarball of project
+	rpm       build source codes and generate rpm file
+	srpm      generate SRPM file
+	build     generate srpm and send to build in copr
+	all       clean test doc rpm
+	flake8    check Python style based on flake8
+
+Running from your local machine, you can generate your own RPM running:
+
+	$ make rpm
+
+if your environment is properly setup you should have your RPM at: /home/user/git/janitor/rpmbuild/RPMS/x86_64/janitor-0.0.2-0.x86_64.rpm
+
+janitor is being built on [Fedora Copr https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/builds/](https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/builds/)
+
+running a new build you need to check your ~/.config/copr-fedora file and run:
+
+	make build
+
+Before starting the release process, check your account permissions in Copr.
+
+	$ make srpm
+
+   1. copy rpmbuild/SRPMS/janitor-0.0.2-0.src.rpm to janitor/copr
+   2. push janitor/copr to github
+
+  `copr-cli` will be used, installed by `sudo yum/dnf install copr-cli` and configure it.
+
+Request as `Builder` for projects `janitor`, wait until admin approves.
+
+$ copr-cli build janitor https://github.com/eduardocerqueira/janitor/raw/master/copr/janitor-0.0.2-0.src.rpm
+
+Go and grab a cup of tea or coffee, the release build will be come out soon ::
+
+    # tag based builds: `https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/builds/`
+
+**Copr and RPM release helpful Links**
+* https://fedorahosted.org/copr/wiki/HowToEnableRepo
+* http://fedoraproject.org/wiki/Infrastructure/fedorapeople.org#Accessing_Your_fedorapeople.org_Space
+* https://fedorahosted.org/copr/wiki/UserDocs#CanIgiveaccesstomyrepotomyteammate
+* https://copr.fedoraproject.org/api/
+
 
-DEMO
-----
+## DEMO
 
 Running the program without parameters:
 
@@ -52,7 +207,7 @@ Running the program without parameters:
 
 Running the program with with parameters to make clean-up:
 
-	[ecerquei@dev ~]$ janitor openstack --openrc /home/ecerquei/git/janitor/tests/test-openrc.sh --whitelist /home/ecerquei/git/janitor/tests/whitelist.txt --keystone v2
+	[ecerquei@dev ~]$ janitor openstack --openrc /home/ecerquei/git/janitor/tests/test-openrc.sh --whitelist /home/ecerquei/git/janitor/tests/whitelist.txt --keystone v3
 	+---------------------+--------------+------------------+-----------------------------+--------------------------------------------+--------+----------------------+
 	|      TIMESTAMP      |    ACTION    |       NAME       |             IPs             |                   IMAGE                    | FLAVOR |   CREATED AT (UTC)   |
 	+---------------------+--------------+------------------+-----------------------------+--------------------------------------------+--------+----------------------+
@@ -102,99 +257,8 @@ Running the program with parameter to print history file:
     | 2017-07-13 15:00:57 | deleted | 358be8d1-6d4a-4db7-973f-8369d4ff86f7 |
     +---------------------+---------+--------------------------------------+	
 
-# For developer and contributers
 
-Note:
-	At the moment janitor requires python2.7 and it is not compatible with python3 yet!
-
-This section describes how to build a new RPM for janitor;
-
-* Fedora 31
-
-	```
-	sudo dnf install redhat-rpm-config python-devel gcc python2-devel python-pip python-wheel
-	virtualenv -p /usr/bin/python2.7 venv
-	source venv/bin/activate
-	pip install -r requirements/devel.txt
-
-	# test
-	python janitor/cli.py --help
-	```
-
-or using **make** so it requires basic packages in your machine I recommend: python-setuptools, python-sphinx, python-devel and gcc
-
-## RPM / Build
-
-	$ make
-
-	Usage: make <target> where <target> is one of
-
-	clean     clean temp files from local workspace
-	doc       generate sphinx documentation and man pages
-	test      run unit tests locally
-	tarball   generate tarball of project
-	rpm       build source codes and generate rpm file
-	srpm      generate SRPM file
-	build     generate srpm and send to build in copr
-	all       clean test doc rpm
-	flake8    check Python style based on flake8
-
-Running from your local machine, you can generate your own RPM running:
-
-	$ make rpm
-
-and if your environment is setup properly you should have your RPM at: /home/user/git/janitor/rpmbuild/RPMS/x86_64/janitor-0.0.1-1.x86_64.rpm
-
-janitor is being built on Fedora Copr: https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/builds/
-
-running a new build you need to check your ~/.config/copr-fedora file and run:
-
-	make build
-
-
-## install
-
-Installing from your local machine, after you build your own RPM just run:
-
-for Fedora:
-
-	sudo dnf install /home/user/git/janitor/rpmbuild/RPMS/x86_64/janitor-0.0.1-1.x86_64.rpm
-
-for CentOS:
-
-	*requires openstack repo*. you can consult here the latest repo https://wiki.openstack.org/wiki/Release_Naming
-
-	sudo yum install centos-release-openstack-newton.noarch
-	sudo yum install /home/user/git/janitor/rpmbuild/RPMS/x86_64/janitor-0.0.1-1.x86_64.rpm
-
-To install from latest RPM:
-
-**repo:** https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/
-
-for Fedora:
-
-	sudo dnf copr enable eduardocerqueira/janitor
-
-or if needed get the repo from https://copr.fedorainfracloud.org/coprs/eduardocerqueira/janitor/
-and maybe is needed to disable **gpgcheck=0**
-
-
-	[eduardocerqueira-janitor]
-	name=Copr repo for janitor owned by eduardocerqueira
-	baseurl=https://copr-be.cloud.fedoraproject.org/results/eduardocerqueira/janitor/epel-7-$basearch/
-	type=rpm-md
-	skip_if_unavailable=True
-	gpgcheck=0
-	gpgkey=https://copr-be.cloud.fedoraproject.org/results/eduardocerqueira/janitor/pubkey.gpg
-	repo_gpgcheck=0
-	enabled=1
-	enabled_metadata=1
-
-
-or if links above don't work go to Copr Janitor project for more details how to proceed from here.
-
-INSTALLATION FAQ
-----------------
+### issues 
 
 Running on CentOS7 even having EPEL and centos-release-openstack-newton I got this error in one of my CentOS
 server.
@@ -251,23 +315,3 @@ the latest version I got was 2.11 that still don't satisfacts.
 The trick here was, forcing reinstall requests using pip:
 
 	pip install requests --upgrade
-
-
-## MORE INFO
-
-For others topics listed below, please generate the sphinx doc in your local machine running the command:
-
-	$ make doc
-
-and from a browser access: file:///home/user/git/janitor/docs/build/html/index.html
-
-* Install:
-* Guide:
-* Build:
-* Development:
-
-
- ## How to contribute
-
- Feel free to fork and send me pacthes or messages if you think this tool can be helpful for any other scenario.
-

docs/source/examples.rst

@@ -14,6 +14,9 @@ clean up virtual machines and release floating ips for Openstack keep items decl
     source ~/mytenant-openrc.sh
 	janitor --openstack --whitelist /tmp/whitelist.txt
 
+or passing openrc as argument:
+
+    janitor openstack --openrc /root/openrc.sh --whitelist /var/lib/jenkins/workspace/janitor/janitor_whitelist.txt --keystone v3
 
 listing history for your janitor: