Loopback Component Kong Sync

Tested with Loopback JS 3 (https://loopback.io/) and Kong 1.1.2 (https://konghq.com/)

This is a Loopback JS component to synchronize routes to Kong API Gateway.

This component map all Models and Methods from Loopback standardizing it and creating the related routes in Kong.

How it works:

• Read and map all public models
• Read and map all public methods from public models
• Read Service and resources from Kong
• Compare LB resources with Kong Resources based on MD5 checksum stored as tags on Kong
• Create resources if they don't exist and update in case of changes have being made on LB
• Create targets using local IP or the IP list con config file

Setup

Installing using npm: npm install loopback-component-kong-sync --save

After installing it on your project folder you have to input your preferences on component-config.json

component-config.json sessions

The plugin declaration must be inside loopback-component-kong-sync index. You can find a full example of this file in component-config.example.json.

appVersion:

You can use this param as a deploy key. Specifying an index of process.env the value of this environment variable will be used on all checksum to ensure that all resource will be replaced on kong when you release a new API version.

i.e.: APP_VERSION In this case the value of process.env.APP_VERSION now is a part of checksum to determine if the LB resources have being modified and must be replaced on Kong.

adminUrl:

Kong admin URL. As you should keep your admin URL private we recommend you set here an internal IP of your network.

i.e.: http://admin.kong.local:8001

apiHost:

This is your API host address that should be exposed publicity.

i.e.: api.mywebsite.com

service:

This param parses the same object as Kong Service Object (https://docs.konghq.com/1.2.x/admin-api/#service-object)

i.e.:

"service": {
    "name": "SyncService",
    "retries": 5,
    "protocol": "http",
    "host": "SyncUpstream",
    "port": 80,
    "path": "/",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": [
        "SyncService"
    ]
}

upstream:

This param parses the same object as Kong Upstream Object (https://docs.konghq.com/1.2.x/admin-api/#upstream-object)

i.e.:

"upstream": {
    "name": "SyncUpstream",
    "hash_on": "none",
    "hash_fallback": "none",
    "slots": 10000,
    "healthchecks": {
        "active": {
            "https_verify_certificate": false,
            "unhealthy": {
                "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
                "timeouts": 2,
                "http_failures": 2,
                "interval": 100
            },
            "http_path": "/",
            "timeout": 1,
            "healthy": {
                "http_statuses": [200, 301, 302, 307],
                "interval": 5,
                "successes": 2
            },
            "concurrency": 10,
            "type": "http"
        }
    },
    "tags": [
        "SyncUpstream",
        "SyncService"
    ]
}

targets:

This param parses the same object as Kong Target Object (https://docs.konghq.com/1.2.x/admin-api/#target-object)

i.e.:

"targets": [
    {
        "target": "127.0.0.1:3001",
        "weight": 100,
        "tags": [
            "SyncTarget",
            "SyncUpstream",
            "SyncService"
        ]
    },
    {
        "target": null,
        "weight": 100,
        "tags": [
            "SyncTarget",
            "SyncUpstream",
            "SyncService"
        ]
    }
]

plugins:

This param parses the same object as Kong Plugin Object (https://docs.konghq.com/1.2.x/admin-api/#plugin-object)

The plugin object must be inside service or route. You don't have to set service or route fields on plugin object, it will be replaced automatically by the service. In case of you setting plugin into route, this plugin will be settled for all routes of your API, except those one you override on model, see bellow.

This component was developed to work with key-auth plugin, so we recommend you set this plugin on route option.

You can find all bundle Kong plugin here https://docs.konghq.com/hub/.

i.e.:

"plugins": {
    "service": {
        "cors": {
            "name": "cors",
            "service": null,
            "route": null,
            "enabled": true,
            "run_on": "first",
            "protocols": ["http", "https"],
            "tags": [
                "SyncService",
                "cors"
            ],
            "config": {
                "origins": [
                    "https://www.mywebsite.com",
                    "https://mywebsite.com"
                ],
                "methods": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"],
                "headers": [
                    "Origin",
                    "Referer",
                    "Authorization",
                    "Accepts",
                    "Content-Length",
                    "Content-Type",
                    "User-Agent",
                    "Host",
                    "Connection",
                    "Accept-Language",
                    "Accept-Encoding",
                    "Accept-Charset"
                ],
                "exposed_headers": [
                    "User-Agent",
                    "Access-Control-Allow-Origin"
                ],
                "credentials": true,
                "max_age": 3600,
                "preflight_continue": true
            }
        }
    },
    "route": {
        "key-auth": {
            "name": "key-auth",
            "service": null,
            "route": null,
            "enabled": true,
            "run_on": "first",
            "protocols": ["http", "https"],
            "tags": [
                "SyncRoute",
                "key-auth"
            ],
            "config": {
                "key_names": ["authorization","Authorization"],
                "key_in_body": false,
                "hide_credentials": false,
                "anonymous": null,
                "run_on_preflight": false
            }
        }
    }
}

authentication:

Setting the login methods the component will intercept well succeeded logins and create the consumer and the credential automatically on Kong. The same will happens when a logout method is requested, LB component will keep the consumer but will remove the credential.

simultaneousSessions is used to avoid Kong database to be overloaded with unused credentials, so all credentials exceeding the max number of simultaneous sessions will be removed from Kong even if they are still valid.

i.e.:

"authentication": {
    "simultaneousSessions": 5,
    "loginMethods": [
        "/users/login",
        "/users/create",
        "/users/confirm",
        "/users/verify"
    ],
    "logoutMethods": [
        "/users/logout"
    ]
}

Models setup

On model-config.json you can override some default options using the param kong.

Force a method to not be included on Kong even if it's a public method

"MyModel": {
    "dataSource": "mysql",
    "public": true,
    "options": {
        "remoting": {
            "sharedMethods": {
                "*": false,
                "search": true
            }
        }
    },
    "kong": {
        "methods": {
            "search": {
                "disabled": true
            }
        }
    }
},

Force an entire model to not be included on Kong even if it's a public model

"MyModel": {
    "dataSource": "mysql",
    "public": true,
    "options": {
        "remoting": {
            "sharedMethods": {
                "*": false,
                "search": true
            }
        }
    },
    "kong": {
        "disabled": true
    }
},

Disabling plugins on routes

"MyUserModel": {
    "dataSource": "mysql",
    "public": true,
    "options": {
        "remoting": {
            "sharedMethods": {
                "*": false,
                "login": true,
                "logout": true
            }
        }
    },
    "kong": {
        "methods": {
            "login": {
                "plugins": {
                    "key-auth": {
                        "disabled": true
                    }
                }
            },
            "logout": {
                "plugins": {
                    "key-auth": {
                        "disabled": true
                    }
                }
            }
        }
    }
},