diff --git a/README.md b/README.md index 9dafb7a58..f8555a683 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,6 @@ Automate scheduling and end-to-end provisioning of servers and networks. * Please use our [Gerrit Review](https://review.gerrithub.io/#/q/project:redhat-performance/quads) to submit patches. * We also have a [Trello board](https://trello.com/b/inFZ2nbD/quads) for tracking development. -![jenkins](/image/jenkins.png?raw=true) - ![quads](/image/quads.jpg?raw=true) * [QUADS (quick and dirty scheduler)](#quads-quick-and-dirty-scheduler) @@ -27,14 +25,17 @@ Automate scheduling and end-to-end provisioning of servers and networks. Cloud](#extending-the-schedule-of-an-existing-cloud) * [Extending the Schedule of Existing Cloud with Differing Active Schedules](#extending-the-schedule-of-existing-cloud-with-differing-active-schedules) - * [Extending Machine Allocation to an existing - Cloud](#extending-machine-allocation-to-an-existing-cloud) + * [Extending Machine Allocation to an existing Cloud](#extending-machine-allocation-to-an-existing-cloud) * [Additional Tools and Commands](#additional-tools-and-commands) + * [Using the QUADS JSON API](#using-the-quads-json-api) + * [API GET Operations](#api-get-operations) + * [API POST Operations](#api-post-operations) * [Contributing](#contributing) ## What does it do? - Create and manage a date/time based YAML schedule for machine allocations - Drive system provisioning and network switch changes based on workload assignment via external commands + - Automated network and provisioning validation prior to delivering sets of machines/networks to users. - Generates instackenv.json for each OpenStack environment. - Automatically generate documentation to illustrate current status, published to a [Wordpress instance](http://python-wordpress-xmlrpc.readthedocs.io/en/latest/examples/posts.html#pages) * Current system details @@ -122,6 +123,7 @@ b02-h01-r620.example.com ``` ## QUADS Usage Documentation + - Note: we will be documenting the switch/network design components at a later date or will be building tools to do this for you. - Initialize the schedule structure ``` @@ -442,6 +444,134 @@ bin/quads.py --host c03-h17-r620.rdu.openstack.example.com --add-schedule --sche * Note: You can run ```bin/find-available-py``` with the ```--cli``` flag to generate QUADS commands for you. +## Using the QUADS JSON API +* We've recently introduced a JSON API into QUADS comprised of a systemd service ```quads-daemon``` and a ```quads-cli``` +* This is an optional local systemd service you can start and interact with and listens on localhost ```TCP/8080``` + +``` +cp systemd/quads-daemon.service /etc/systemd/system/quads-daemon.service +systemctl enable quads-daemon.service +systemctl start quads-daemon.service +``` + + - All of the argparse and normal QUADS sub-commands are supported and will accept http ```GET``` and ```POST``` actions in a JSON response body. + - Example: getting the equivalent of ```quads --ls-hosts``` via curl + +``` +curl -X GET -H 'Content-Type: application/json' http://127.0.0.1:8080/api/v1/lshosts +``` + +You'll then see a JSON response back. +``` +{"hosts": ["b08-h13-r620.rdu.openstack.engineering.example.com", "b08-h14-r620.rdu.openstack.engineering.example.com", "b08-h15-r620.rdu.openstack.engineering.example.com", "b08-h17-r620.rdu.openstack.engineering.example.com", "b08-h18-r620.rdu.openstack.engineering.example.com", "b08-h19-r620.rdu.openstack.engineering.example.com", "b08-h21-r620.rdu.openstack.engineering.example.com"]} +``` + +### API GET Operations +* The following commands can be queried via curl or some other http mechanism to do basic metadata queries: + * ```curl -X GET -H 'Content-Type: application/json' http://127.0.0.1:8080``` + - ```/api/v1/lshosts``` Obtain a list of hosts managed by QUADS + - ```/api/v1/lsclouds``` Obtain list of cloud assignments + - ```/api/v1/lsowner``` Retrieve a list of current system assignment owners + - ```/api/v1/lsccusers``` List the cc-users associated for assignments + - ```/api/v1/lstickets``` Obtain the ticket numbers to assignment mappings + - ```/api/v1/lsqinq``` List the qinq VLAN mode (0|1) per cloud assignment + +### API POST Operations +* The following construct can be used via http ```POST``` to receive more detailed data by providing granular criteria to return JSON body data: + * You can combine one of many POST query types with multiple POST metadata objects. + * There is limited support for data modification via POST as well documented below. + * Valid POST URI queries + - ```/api/v1/lsowner``` + - ```/api/v1/lsccusers``` + - ```/api/v1/lstickets``` + - ```/api/v1/lsqinq``` + - ```/api/v1/host``` Can also be used for defining/updating a host. + - ```/api/v1/cloud``` Can also be used for defining/updating a cloud assignment. + - ```/api/v1/ahs``` AKA _add host schedule_ used for adding a new host schedule. + - ```/api/v1/rhs``` AKA _remove host schedule_ used for removing a host schedule. + - ```/api/v1/mhs``` AKA _modify host schedule_ used for modifying a host schedule. + - ```/api/v1/moves``` Reports what would be moved on a given date. + + * Valid POST object filters: + - ```-d cloud=cloud0X``` + - ```-d cloudonly=cloud0X``` + - ```-d 'date=2018-08-08 22:00'``` + - ```-d statedir=/path/to/quads/datadir``` + - ```-d fullsummary=True/False``` + - ```-d host=c10-h33-r630.rdu.openstack.engineering.example.com``` + +* Constructing an http POST example with multiple metadata objects: + +```curl -X POST -H 'Content-Type: application/json'``` ```-d``` ```quadsvariable=value``` ```-d``` ```quadsvariable=value``` ```http://127.0.0.1:8080/api/v1/object``` + +* Working Examples: + - Query the owners of cloud02 only +``` +curl -X POST -H 'Content-Type: application/json' -d cloudonly=cloud02 http://127.0.0.1:8080/api/v1/lsowners ; echo +``` + +``` +{"owner": ["epresley"]} +``` + - Use the Query Object to Obtain Details +``` +curl -X POST http://localhost:8080/api/v1/query -d host=c01-h01-r620.rdu.openstack.engineering.example.com -d lsschedule=True -H 'Content-Type: application/json' +``` + +``` +{"result": ["Default cloud: cloud01", "Current cloud: cloud01", "Defined schedules:", " 0| start=2016-10-17 00:00,end=2016-12-21 17:00,cloud=cloud04", " 1| start=2016-12-21 17:00,end=2017-0 +08", " 2| start=2017-02-09 05:00,end=2017-03-06 05:00,cloud=cloud02", " 3| start=2017-03-20 05:00,end=2017-04-03 05:00,cloud=cloud03", " 4| start=2017-02-03 19:00,end=2017-02-09 05:00,clou +t=2017-03-06 05:00,end=2017-03-20 05:00,cloud=cloud16", " 6| start=2017-04-03 05:00,end=2017-05-01 05:00,cloud=cloud02", " 7| start=2017-06-18 22:00,end=2017-07-02 22:00,cloud=cloud05", " +:00,end=2017-05-28 22:00,cloud=cloud07"]} +``` + + - Query all of the future move actions on the day and time ```2018-01-01 22:00``` +``` +curl -X POST -H 'Content-Type: application/json' -d 'date=2018-01-01 22:00' -d statedir=/opt/quads/data http://127.0.0.1:8080/api/v1/moves ; echo +``` + +``` +{"result": [{"current": "cloud14", "new": "cloud01", "host": "b08-h13-r620.rdu.openstack.engineering.redhat.com"}, {"current": "cloud14", "new": "cloud01"}]} +``` + +* More Examples with API POST + + - Define a Host via API POST +``` +curl -X POST http://localhost:8080/api/v1/host -d host=c10-h33-r630.rdu.openstack.engineering.redhat.com -d cloud=cloud01 -d force=False -H 'Content-Type: application/json' +``` + + - Add a new Cloud Assignment via API POST +``` +curl -X POST http://localhost:8080/api/v1/cloud -d cloud=cloud03 -d description='Some project' -H 'Content-Type: application/json' +``` + + - Modify a Cloud Assignment via API POST +``` +curl -X POST http://localhost:8080/api/v1/cloud -d cloud=cloud03 -d description='New Updated Description' -d force=True -H 'Content-Type: application/json' +``` + + - Add a new Host Schedule via API POST +``` +curl -X POST http://localhost:8080/api/v1/ahs -d host=c01-h01-r620.rdu.openstack.engineering.redhat.com -d 'start=2017-09-01 22:00' -d 'end=2017-09-30 22:00' -d 'cloud=cloud04' -H 'Content-Type: application/json' +``` + + - Modify a Host Schedule via API POST + - At least one of ```start=``` ```end=``` or ```cloud=``` are required with modifications. +``` +curl -X POST http://localhost:8080/api/v1/mhs -d host=c01-h01-r620.rdu.openstack.engineering.redhat.com -d 'start=2017-09-01 22:00' -d 'end=2017-09-30 22:00' -d 'cloud=cloud04' -H 'Content- Type: application/json' +``` + + - Remove a Host Schedule via API POST + - ```schedule=``` is the numeric value of the target schedule, you can use the ```query``` object to determine this (or ```--ls-schedule``` via cli or ```bin/quads.py``` +``` +curl -X POST http://localhost:8080/api/v1/rhs -d host=c01-h01-r620.rdu.openstack.engineering.redhat.com -d schedule=1 +``` + +* Using quads-cli + - ```bin/quads-cli``` is a front-end to the ```bin/quads-daemon``` JSON API. + - ```bin/quads-cli``` interacts with ```bin/quads-daemon``` exactly like the normal ```bin/quads.py`` so you can utilize the same documentation above. + ## Additional Tools and Commands * You can display the allocation schedule on any given date via the ```--date``` flag. @@ -552,7 +682,11 @@ rnixon git clone https://github.com/redhat-performance/quads ``` -* Setup username/email for git and gerrithub: +* Create a [Github issue](https://github.com/redhat-performance/quads/issues/new) to track your work. + - Provide a meaningful explanation, citing code lines when relevant. + - Explain what you are trying to fix, or what you're trying to contribute. + +* Setup username/email for git and gerrithub (one time only): - Ensure Github and Gerrithub are linked by [signing into Gerrithub via Github](https://review.gerrithub.io/login) - match ```gitreview.username``` to your Github username - match ```user.name``` to your real name or how you want credit for commits to display in Git history. @@ -571,6 +705,8 @@ cd quads vi bin/quads.py ``` * Add a local commit with a meaningful, short title followed by a space and a summary (you can check our commit history for examples). +* Add a line that relates to a new or existing github issue, e.g. ```fixes: https://github.com/redhat-performance/quads/issues/5``` or ```related-to: https://github.com/redhat-performance/quads/issues/25``` + ``` git add bin/quads.py @@ -585,6 +721,7 @@ git review -s ``` * Now submit your patchset with git review (future patches you only need to run ```git review```) + - A Change-ID will be generated when you create your first patchset, make sure this is the last line in the commit message preceded by an empty line. ``` git review diff --git a/image/jenkins.png b/image/jenkins.png deleted file mode 100644 index 0f88ccd98..000000000 Binary files a/image/jenkins.png and /dev/null differ diff --git a/image/quads-visual.png b/image/quads-visual.png index dadf2f20a..b3a7181c8 100644 Binary files a/image/quads-visual.png and b/image/quads-visual.png differ