Kong can be provisioned on a Mesosphere DC/OS cluster using following steps:
The following steps use AWS for provisioning the DC/OS cluster and assume you have basic knowledge of DC/OS, Marathon, VIPs, and Marathon-LB.
-
Initial setup
Download or clone the following repo:
$ git clone git@github.com:Kong/kong-dist-dcos.git $ cd kong-dist-dcos
Skip to step 3 if you have already provisioned a DC/OS cluster.
-
Deploy a DC/OS cluster
Following the DC/OS AWS documentation, deploy a DC/OS cluster on which Kong will be provisioned
Once your cluster is ready, Kong can be deployed using the DC/OS CLI or the DC/OS GUI.
-
Deploy Marathon-LB
We will use the
marathon-lb
package to deploy Marathon-LB for load balancing external traffic to cluster and VIPs for load balancing internal traffic:$ dcos package install marathon-lb
-
Deploy a Kong-supported database
Before deploying Kong, you need to provision a Cassandra or PostgreSQL instance.
For Cassandra, use the
cassandra
package to deploy 3 nodes of Cassandra in the DC/OS cluster:$ dcos package install cassandra
For PostgreSQL, use the
postgresql
package with the following options:{ "service": { "name": "postgresql" }, "postgresql": { "cpus": 0.3, "mem": 512 }, "database": { "username": "kong", "password": "kong", "dbname": "kong" }, "storage": { "host_volume": "/tmp", "pgdata": "pgdata", "persistence": { "enable": true, "volume_size": 512, "external": { "enable": false, "volume_name": "postgresql", "provider": "dvdi", "driver": "rexray" } } }, "networking": { "port": 5432, "host_mode": false, "external_access": { "enable": false, "external_access_port": 15432 } } }
It configures PostgreSQL as follows:
Config Description username
This parameter configures the username for the Kong database password
This parameter configures the password for the Kong database dbname
This parameter configures the name of the kong database persistence
This parameter enables persistent volumes for PostgreSQL Install PostgreSQL using
postgres.json
file from the repo:$ dcos package install postgresql --options=postgres.json
-
Deploy Kong
Now we have an external load balancer and Kong-supported database running. Using the kong package from Universe repo, deploy Kong with the following options:
{ "service": { "name": "kong", "instances": 1, "cpus": 1, "mem": 512, "role": "*" }, "configurations": { "log-level": "notice", "database": { "migrations": true, "use-cassandra": false }, "postgres": { "host": "postgresql.marathon.l4lb.thisdcos.directory", "port": 5432, "database": "kong", "user": "kong", "password": "kong" }, "cassandra": { "contact-points": "node-0.cassandra.mesos, node-1.cassandra.mesos, node-2.cassandra.mesos", "port": 9042, "keyspace": "kong" } }, "networking": { "proxy": { "external-access": true, "vip-port": 8000, "vip-port-ssl": 8443, "virtual-host": "<vhost>", "https-redirect": true, "service-port": 10201 }, "admin": { "external-access": true, "vip-port": 8001, "vip-port-ssl": 8444, "https-redirect": false, "service-port": 10202 } } }
It configures Kong as follows:
Config Description configurations.log_level
Sets the Kong’s log_level configuration configurations.custom-envs
A space-separated list of Kong configurations configurations.database.use-cassandra
If true
, Cassandra is used as the Kong databaseconfigurations.database.migration
If true
, Kong will run migrations during startconfigurations.postgres.host
PostgreSQL host name configurations.postgres.port
PostgreSQL port configurations.postgres.database
PostgreSQL database name configurations.postgres.user
PostgreSQL username configurations.postgres.password
PostgreSQL password configurations.cassandra.contact-points
Comma-delimited list of Cassandra contact points configurations.cassandra.port
Port on which Cassandra is listening for queries configurations.cassandra.keyspace
Keyspace to use in Cassandra. Will be created if it doesn’t exist networking.proxy.external-access
If true
, allows external access to Kong’s proxy portnetworking.proxy.virtual-host
The virtual host address to integrate Kong proxy port with Marathon-lb networking.proxy.https-redirect
If true
, Marathon-lb redirects HTTP traffic to HTTPS. This requires ‘virtual-host’ to be setnetworking.proxy.service-port
Port number to be used for reaching Kong’s proxy port from outside of the cluster networking.proxy.vip-port
Port number to be used for communication internally to the Proxy API. Default is 8000 networking.proxy.vip-port-ssl
Port number to be used for secure communication internally to the Proxy API. Default is 8443 networking.admin.external-access
If true
, allows external access to Kong’s admin portnetworking.admin.virtual-host
The virtual host address to integrate Kong admin port with Marathon-lb networking.admin.https-redirect
If true
, Marathon-lb redirects HTTP traffic to HTTPS. This requires ‘virtual-host’ to be setnetworking.admin.service-port
Port number to be used for reaching Kong’s admin port from outside of the cluster networking.admin.vip-port
Port number to be used for communication internally to the Admin API. Default is 8001 networking.admin.vip-port-ssl
Port number to be used for secure communication internally to the Admin API. Default is 8444 Note: Tweak the above configuration based on you datastore choice.
Run the following command to install Kong package:
$ dcos package install kong --options=kong_postgres.json
-
Verify your deployments
To verify that our Kong instance is up and running, we can use
dcos task
command:$ dcos task NAME HOST USER STATE ID kong 10.0.1.8 root R kong.af46c916-3b55-11e7-844e-52921ef4378d marathon-lb 10.0.4.42 root R marathon-lb.d65c3cc3-3b54-11e7-844e-52921ef4378d postgres 10.0.1.8 root R postgres.5b0a2635-3b55-11e7-844e-52921ef4378d
-
Using Kong
Now that Kong is installed, to test the configuration, SSH into one of the instances in the cluster (such as a master), and try curl-ing the endpoints:
Admin
$ curl -i -X GET http://marathon-lb.marathon.mesos:10202 HTTP/1.1 200 OK .. {..}
Proxy
$ curl -i -X GET http://marathon-lb.marathon.mesos:10201 HTTP/1.1 404 Not Found .. {"message":"no API found with those values"}
VHOST
In this example, the public DNS name used is
mesos-tes-PublicSl-1TJB5U5K35XXT-591175086.us-east-1.elb.amazonaws.com
for exposing Kong’s proxy port.Note: Kong returning 404 on proxy port is a valid response as no API was registered yet.
-
Uninstalling Kong
To uninstall Kong, run the following command:
$ dcos package uninstall kong
-
Example
For this demo, we created an app which returns
Hello world
on port8080
. Using themy_app.json
file from the kong-dist-dcos repo, deploy the app in the cluster which will act as a backend server to process requests received from Kong:$ dcos marathon app add my_app.json
Create an API on Kong:
$ curl -i -X POST marathon-lb.marathon.mesos:10002/apis \ --data "name=myapp" \ --data "hosts=myapp.com" \ --data "upstream_url=http://myapp.marathon.l4lb.thisdcos.directory:8080" HTTP/1.1 201 Created ...
Make a request to the API:
$ curl -i -X GET marathon-lb.marathon.mesos:10001 \ --header "Host:myapp.com" HTTP/1.1 200 OK ... Hello world
Quickly learn how to use Kong with the 5-minute Quickstart.
Follow Up:
Get future release notes emailed to you.