Name	Name	Last commit message	Last commit date
parent directory ..
img	img
README.md	README.md

KONG

Kong is a scalable, open source API Layer (also known as an API Gateway, or API Middleware). Kong runs in front of any RESTful API and is extended through Plugins, which provide extra functionality and services beyond the core platform.

Estimated time for completion: 15 minutes
Target audience: Anyone who wants to deploy an API Gateway on DC/OS.
This package requires an intermediate/advanced DC/OS skill set.

Scope:

Configure and launch the DC/OS cluster that will run the Kong instances.
Configure and launch the Marathon-LB package.
Configure and launch the Kong supported database or run Kong in DB-less mode.
Configure and launch the Kong package.

How to use Kong package on DC/OS

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 assumes you have basic knowledge of DC/OS, Marathon, VIPs, and Marathon-LB.

Initial setup

Download or clone the following repo:
```
$ git clone [email protected]:Mashape/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 Marathon-LB for load balancing external traffic to cluster and VIPs for load balancing internal traffic. Using the package marathon-lb deploy the Marathon-LB:
```
$ dcos package install marathon-lb
```

Deploy a Kong-supported database

Kong can run in a DB-less mode or with a database.

To run Kong in DB-less mode, uncheck configurations.database.migration, configurations.database.use-postgres and configurations.database.use-cassandra

For DB mode, you need to provision a Cassandra or a 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 following option:

{
  "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:

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.

After saving the above option to postgres.json run the following command to install postgresql package:

$ dcos package install postgresql --options=postgres.json

Deploy Kong

Now we have an external load balancer and Kong supported datastore running. Using the kong package from Universe repo, deploy Kong with following option:

{
  "service": {
    "name": "kong",
    "instances": 1,
    "cpus": 1,
    "mem": 512,
    "role": "*"
  },
  "configurations": {
    "log-level": "notice",
    "database": {
      "migrations": true,
      "use-cassandra": false,
      "use-postgres": true
    },
    "postgres": {
      "host": "postgresql.marathon.l4lb.thisdcos.directory",
      "port": 5432,
      "database": "kong",
      "user": "kong",
      "password": "kong"
    },
    "cassandra": {
      "contact-points": "node.cassandra.l4lb.thisdcos.directory",
      "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 `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 database.
`configurations.database.use-postgres`	If `true`, Postgres is used as the Kong database.
`configurations.database.migration`	If `true`, Kong will run migrations during start.
`configurations.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`	A comma-separated list of Cassandra contact points.
`configurations.cassandra.port`	Port on which Cassandra listening for query.
`configurations.cassandra.keyspace`	Keyspace to use in Cassandra. Will be created if doesn't exist.
`networking.proxy.external-access`	If `true`, allows external access to Kong's proxy port.
`networking.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 set.
`networking.proxy.service-port`	Port number to be used for reaching Kong's proxy port from outside of 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 port.
`networking.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 set.
`networking.admin.service-port`	Port number to be used for reaching Kong's admin port from outside of 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.

After saving the option to a file kong.json run the following command to install Kong package:

$ dcos package install kong --options=kong.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

Kong in the DC/OS UI

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
Date: Fri, 03 Nov 2017 18:35:58 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.11.1
..

{..}

Proxy

$ curl -i -X GET http://marathon-lb.marathon.mesos:10201
HTTP/1.1 404 Not Found
Date: Fri, 03 Nov 2017 18:41:23 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Server: kong/0.11.1

{"message":"no API found with those values"}

VHOST

In this example, public DNS name used is mesos-tes-PublicSl-1TJB5U5K35XXT-591175086.us-east-1.elb.amazonaws.com for exposing the Kong's proxy port.

Note: Kong returning 404 on proxy port is a valid response as no API registered yet with Kong.

You can quickly learn how to use Kong with the 5-minute Quickstart.

Uninstalling Kong

To uninstall Kong, run following command:
```
$ dcos package uninstall kong
```

Example

For this demo, we created an app which returns Hello world on port 8080. Using the my_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:10202/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:10201 \
--header "Host:myapp.com"
HTTP/1.1 200 OK
...

Hello world

Quickly learn how to use Kong with the 5-minute Quickstart.

Enterprise Support

Support, Demo, Training, API Certifications and Consulting available at http://getkong.org/enterprise.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

1.9

1.9

README.md

KONG

How to use Kong package on DC/OS

Enterprise Support

Files

1.9

Directory actions

More options

Directory actions

More options

Latest commit

History

1.9

Folders and files

parent directory

README.md

KONG

How to use Kong package on DC/OS

Enterprise Support