README.md

   1 kong-app
   2 =========
   3
   4 [![Build Status](https://travis-ci.com/fretlink/ansible-kong-app.svg?token=D3nFpUxMu7vStDHwUNy4&branch=master)](https://travis-ci.com/fretlink/ansible-kong-app)
   5
   6 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.
   7
   8 Requirements
   9 ------------
  10
  11 A Kong server which you want to configure.
  12
  13 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.
  14
  15 Role Variables
  16 --------------
  17 * `kong_servers`: an array of kong_server to configure with the following configuration:
  18   * `kong_app_admin_url` the kong admin API url (mandatory).
  19   * `kong_app_admin_apikey` the apikey to use during kong admin api calls. Defaults to `""`
  20   * `services` an array of services to setup. Defaults to `[]`.
  21     * `name` the name of the service to create for this app, **mandatory**
  22     * `url` the url of the backend of the app, **mandatory**. May refer to an upstream by its name (https://upstream_name/path)
  23     * `upstream` if the url reference an upstream a dict with the configuration, optional
  24       * `conf` the configuration as expected by kong for an upstream creation
  25         * `name` mandatory name for the upstream
  26         * `healthchecks` optional healthchecks configuration as expected by kong api
  27       * `targets` an array of dict defining a target for kong
  28         * `target` the host:port to reach the target, **mandatory** if a target is defined
  29         * `weight` the weight of the target, optional
  30     * `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))
  31       * `name`
  32       * `config`
  33     * `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))
  34       * `hosts`
  35       * `paths`
  36       * `protocols`
  37       * `methods`
  38
  39 Dependencies
  40 ------------
  41
  42 None
  43
  44 Example Playbook
  45 ----------------
  46
  47 ```yaml
  48 - hosts: localhost
  49   roles:
  50      - role: kong-app,
  51        kong_servers:
  52          - kong_app_admin_url: http://localhost:8001,
  53            services:
  54              - name: example,
  55                url: http://example.com,
  56                plugins: [],
  57                routes: [ { hosts: [my.kong.example], paths: [/] } ]
  58 ```
  59
  60 Tests
  61 ----
  62
  63 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`).
  64
  65 License
  66 -------
  67
  68 MIT (see LICENSE file for details)
  69
  70 Author Information
  71 ------------------
  72
  73 Developed at [Fretlink](https://tech.fretlink.com)