Merge pull request #27 from gaetanfl/fix_upstream_creation_return_code

[github/fretlink/ansible-kong-app.git] / README.md

diff --git a/README.md b/README.md
index 074e830e9a890dff39e2fba4a4c1905c309ac542..080a320e3469096f8efa5e22a0399f49dc741bc6 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,53 +1,73 @@
 kong-app
 =========
 
-This role aims at creating on a remote kong the service, routes and plugins needed by an app
+[![Build Status](https://travis-ci.com/fretlink/ansible-kong-app.svg?token=D3nFpUxMu7vStDHwUNy4&branch=master)](https://travis-ci.com/fretlink/ansible-kong-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_app_admin_url` the kong admin url (mandatory).
-* `kong_app_admin_apikey` the apikey to use kong admin api. Default to ""
-* `kong_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
-  * `plugins` An array of plugins to activate with their name and config in a dict
-    * `name`
-    * `config`
-  * `routes` An array of routes to create for this service.
-    * `hosts`
-    * `paths`
-    * `protocols`
-    * `methods`
+* `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** 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. (Route objects are defined in the [Kong API documentation](https://docs.konghq.com/2.1.x/admin-api/#route-object))
+      * `hosts`
+      * `paths`
+      * `protocols`
+      * `methods`
 
 Dependencies
 ------------
 
-
+None
 
 Example Playbook
 ----------------
 
-    - hosts: localhost
-      roles:
-         - { role: kong-app, kong_app_admin_url: http://localhost:8001,
-             kong_app_services: [ name:example,
-             url: http://example.com,
-             plugins: [],
-             routes: [ { hosts: [my.kong.example], paths: [/] } ]]
-           }
+```yaml
+- 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: [/] } ]
+```
+
+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)