Kong deployment on DC/OS cluster

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.

1. 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.

2. 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.

3. 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
   

4. 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
   

5. 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 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
   

6. 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
   

7. 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.

8. Uninstalling Kong

   To uninstall Kong, run the following command:

    $ dcos package uninstall kong
   

9. 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!