binder-deploy-kubernetes

A binder-deploy implementation that launches containers on a Kubernetes cluster

The deploy API defines how Binder templates can be launched on any container management system. In our production environment, all templates are launched on a Kubernetes cluster using this module.

By default, containers are transient and are culled after one hour of inactivity.

When containers are first deployed (through POSTing to /applications/<template name>), they are assigned an id but not a location. Once the location has been assigned (generally 5-10s after the container has been scheduled), the client can redirect to that location. After the initial deployment command, the location can be determined by polling the /applications/<template name>/<id> endpoint.

install

The simplest way to run the binder-build server is through the binder-control module, which manages the server's lifecycle and service (the database and logging system) dependencies. Additionally, binder-control uses the PM2 process manager to monitor/restart the server in the event of failures. In binder-control, the deploy server can be started with with custom configuration parameters through

binder-control deploy-kubernetes start --api-key=<key> --config=/path/to/config

It will also be started with reasonable defaults through

binder-control start-all

If you'd prefer to use binder-build in standalone mode:

git clone [email protected]:binder-project/binder-deploy-kubernetes
cd binder-deploy-kubernetes
npm i && npm start

api

The deploy portion of the Binder API consists of the following endpoints:

Get the status of a single deployed template with a given ID

GET /applications/binder-project-example-requirements/84b8f9e8d573e73016fa2c14bad86a4d HTTP 1.1

returns

{
  "id": "84b8f9e8d573e73016fa2c14bad86a4d",
  "template-name": "binder-project-example-requirements",
  "location": "104.197.56.211/user/84b8f9e8d573e73016fa2c14bad86a4d",
  "status": "deleted"
}

Get the status of all deployed templates for a template name

GET /applications/binder-project-example-requirements HTTP 1.1
Authorization: 880df8bbabdf4b48f412208938c220fe

returns

[
  {
    "id": "74156d847a6bc8e07c64a43aaed53514",
    "template-name": "binder-project-example-requirements",
    "location": "104.197.56.211/user/74156d847a6bc8e07c64a43aaed53514",
    "status": "deleted"
  },
  ...
  {
    "id": "880aa1c3798c32ad6fc120267e3ae610",
    "template-name": "binder-project-example-requirements",
    "location": "104.197.56.211/user/880aa1c3798c32ad6fc120267e3ae610",
    "status": "deleted"
  }
]

Launch a new instance of a template

POST /applications/binder-project-example-requirements
Content-Type: application/json

returns

{
  "id": "a16653059942e2ef2b1c7b458d6a2463"
}

usage

The best way to interact with the deploy server is through the binder-client. Once the client has been installed, all endpoints are accessible either programmatically or through the CLI. For example:

From JS

var binder = require('binder-client')
binder.deploy.status(<deployment options>, function (err, status) {
  ...
})

From the CLI

binder deploy status <image-name> --api-key=<key> --host=<host> --port=<port>