Interacting with Hydroplane

To get Hydroplane running the first time, follow the quickstart guide.

The Hydroplane API

Hydroplane exposes a REST API over HTTP.

Hydroplane automatically generates detailed API documentation that it serves at

http://<host and port of Hydroplane server>/docs

You should refer to that documentation for the most up-to-date representation of the Hydroplane API.

This is a rough outline of the API’s methods:

  • POST /process - creates a process. The request body should be a JSON-serialized process spec

  • GET /process - retrieves a list of all running processes

  • GET /group/<group name> - retrieves a list of all processes in a particular group

  • DELETE /process/<name of process> - destroys a process, given the process’s name

  • DELETE /group/<group name> - destroys all processes in a group

Command Line Tool (hpctl)

The REST API is useful for programmatically interacting with Hydroplane, but it can be kind of a hassle to use directly. hpctl is a wrapper script that hides those calls behind a simple CLI.

To list the processes that are currently running:

bin/hpctl list

To list only those processes in the group my-group:

bin/hpctl list -g my-group

To start a process using a process spec defined in foo.json:

bin/hpctl start foo.json

To stop a process named foo:

bin/hpctl stop foo

To stop all processes in the group my-group

bin/hpctl stop -g my-group

How does hpctl know which server to talk to?

hpctl looks for the address of the Hydroplane server in the HYDROPLANE_SERVER environment variable. If that environment variable isn’t defined, it falls back to Hydroplane’s default host and port (localhost:8000). You can also specify the server’s address explicitly with the -s/--server flag to hpctl, e.g.:

bin/hpctl -s hydroserver:4040 list