Merge pull request #22 from paulrbr-fl/improve-doc

Prepare to open-source this role

4 files changed, 41 insertions, 21 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..9be8747
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,7 @@
+Copyright (c) 2020 Fretlink S.A.S
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ No newline at end of file
diff --git a/README.md b/README.md
index 8db9391..e02203f 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,34 @@
 kong-app
 =========
 
-This role aims at creating on a remote kong the service, routes and plugins needed by an app
+This role aims at creating, on a remote kong, a list of services, routes and plugins needed by an app. The API calls are made from the ansible target host. If you use `hosts: localhost` as a target from within your playbook then all API calls will be done from your local machine.
 
 Requirements
 ------------
 
-None at the moment
+A Kong server which you want to configure.
+
+If you want to configure this role with [Dhall](https://dhall-lang.org/) instead of YAML, the role publishes dhall bindings defined in the `dhall/package.dhall` file. These bindings will need Dhall version `1.29.0` or higher.
 
 Role Variables
 --------------
-* `kong_servers`: an array of kong\_server to configure with followin configuration:
-  * `kong_app_admin_url` the kong admin url (mandatory).
-  * `kong_app_admin_apikey` the apikey to use kong admin api. Default to ""
-  * `services` an array of services to setup (default to [])
-    * `name` the name of the service to create for this app, mandatory
-    * `url` the url of the backend of the app, mandatory. May refer to an upstream by its name (https://upstream\_name/path)
+* `kong_servers`: an array of kong_server to configure with the following configuration:
+  * `kong_app_admin_url` the kong admin API url (mandatory).
+  * `kong_app_admin_apikey` the apikey to use during kong admin api calls. Defaults to `""`
+  * `services` an array of services to setup. Defaults to `[]`.
+    * `name` the name of the service to create for this app, **mandatory**
+    * `url` the url of the backend of the app, **mandatory**. May refer to an upstream by its name (https://upstream_name/path)
     * `upstream` if the url reference an upstream a dict with the configuration, optional
       * `conf` the configuration as expected by kong for an upstream creation
         * `name` mandatory name for the upstream
         * `healthchecks` optional healthchecks configuration as expected by kong api
       * `targets` an array of dict defining a target for kong
-        * `target` the host:port to reach the target (mandatory)
-        * `weight` the weight of the target (optional)
-    * `plugins` An array of plugins to activate with their name and config in a dict
+        * `target` the host:port to reach the target, **mandatory** if a target is defined
+        * `weight` the weight of the target, optional
+    * `plugins` An array of plugins to activate with their name and config in a dict. (Plugin objects are defined in the [Kong API documentation](https://docs.konghq.com/2.1.x/admin-api/#plugin-object))
       * `name`
       * `config`
-    * `routes` An array of routes to create for this service.
+    * `routes` An array of routes to create for this service. (Route objects are defined in the [Kong API documentation](https://docs.konghq.com/2.1.x/admin-api/#route-object))
       * `hosts`
       * `paths`
       * `protocols`
@@ -35,26 +37,34 @@ Role Variables
 Dependencies
 ------------
 
-
+None
 
 Example Playbook
 ----------------
 
     - hosts: localhost
       roles:
-         - { role: kong-app, kong_servers: [ kong_app_admin_url: http://localhost:8001,
-             services: [ name:example,
-             url: http://example.com,
-             plugins: [],
-             routes: [ { hosts: [my.kong.example], paths: [/] } ]]]
+         - { role: kong-app,
+             kong_servers:
+               - kong_app_admin_url: http://localhost:8001,
+                 services:
+                   - name: example,
+                     url: http://example.com,
+                     plugins: [],
+                     routes: [ { hosts: [my.kong.example], paths: [/] } ]
            }
 
+Tests
+----
+
+The role is tested with automated continuous integration tests on Travis (see `tests/` directory). The test playbook targets a fake Kong server (visible in `tests/kong.py`).
+
 License
 -------
 
-TBD
+MIT (see LICENSE file for details)
 
 Author Information
 ------------------
 
-FretLink Team
+Developed at [Fretlink](https://tech.fretlink.com)
diff --git a/tests/kong.py b/tests/kong.py
index 4e2df28..a1f9cec 100755
--- a/tests/kong.py
+++ b/tests/kong.py
@@ -13,7 +13,7 @@ class SimpleHTTPRequestHandler(CGIHTTPRequestHandler):
         self.wfile.write(b'{ "data": [] }')
 
     def do_POST(self):
-        self.send_response(200)
+        self.send_response(201)
         self.end_headers()
         self.wfile.write(b'Hello, world!')
 
diff --git a/tests/test.yml b/tests/test.yml
index 36c81a2..cbe858f 100644
--- a/tests/test.yml
+++ b/tests/test.yml
@@ -10,3 +10,6 @@
             services:
               - url: http://example.com
                 name: test
+                routes:
+                  - hosts: [my.kong.example]
+                    paths: [/]