From b193f7503842ed803e0bcedfbbfc45d1b6b7d9c0 Mon Sep 17 00:00:00 2001 From: Paul Bonaud Date: Mon, 12 Oct 2020 16:00:06 +0200 Subject: Improve README documentation, add a LICENSE file and add test case --- LICENSE | 7 +++++++ README.md | 50 ++++++++++++++++++++++++++++++-------------------- tests/kong.py | 2 +- tests/test.yml | 3 +++ 4 files changed, 41 insertions(+), 21 deletions(-) create mode 100644 LICENSE 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: [/] -- cgit v1.2.3