Open-Source API Management and Microservice Management

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]https://universe.dcos.io/#/package/kong/version/latest 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 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`	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 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 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 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 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 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: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.

Having Trouble? We're Here to Help!