What is Mantl API?

When developing applications, one to the first obstacles we encountered was around installing applications and frameworks. To address this complicated ecosystem, we developed a service framework and API. The Mantl API is a feature built in to Mantl that helps you find and install applications and Mesos frameworks. Think of the effort involved to build a multi-node Elasticsearch, HDFS, or Cassandra cluster using traditional configuration management tools. With Mantl, Mantl API, and the underlying Mesos platform, you can launch any of the above (and several others) with a single API call.

It can be complicated to install applications and frameworks on Mesos. Each framework has it’s own specific configuration options. And there is no conventions or standards for common options. The configuration mechanisms vary as well. Command line arguments, environment variables, and configuration files in varying formats are all common ways to configure frameworks. It often takes someone who has deep knowledge of the underlying application and the Mesos platform (and all of its dependencies) to figure out how to install and configure any given framework.

Mantl API and its packaging system allow you to install a number of frameworks and applications that are pre-configured to work with Marathon, Mesos, Zookeeper, Consul, Traefik, and other Mantl components. Most packages will work without any additional configuration but you do have the ability to customize the deployment to meet your needs. Things like how much CPU and memory to allocate, the number of instances to run (for multi-node applications), and other framework-specific options can be specified in a single JSON file when deploying.

At the time of this writing, the following packages are available:

Arangodb

Cassandra

Chronos

Elasticsearch

Elasticsearch-client

HDFS

Kafka

Kibana

Kibana-mesos

Memsql

Spark

Using Mantl API

Let’s take a look at how you can use Mantl API.

Mantl API is available at /api on your control nodes. By default, it is protected with SSL and basic authentication. I will be using curl and the invaluable jq utility in the following examples.

Listing Packages

The actual list of packages shown above can be obtained using the Mantl API /packages endpoint. This is the API request used:

curl -sku admin:password https://mantl-control-01/api/1/packages | jq -r ‘.[].name’

This issues an authenticated GET request to the /packages endpoint which returns a JSON representation of the all packages and associated metadata. I use the jq command to extract just the name from each package. The result is the list of available packages that you see above.

Of course, you will need to change the username, password, and host name to values appropriate for your Mantl cluster if you are following along.

Installing a Package

Installing packages is really easy. For example, let’s install Elasticsearch.

curl -sku admin:password -d “{\”name\”: \”elasticsearch\”}” https://mantl-control-01/api/1/packages

This sends a POST request to the /packages endpoint with a JSON object that contains the name of the package we want to install. It will return the JSON representation of the application running in Marathon. After a few minutes, you will have 3-node Elasticsearch cluster up and running.

Uninstalling a Package

Uninstalling a package is simple too — you simply issue a request using the DELETE method to the /packages endpoint with the same data you would use if you were installing the package:

curl -sku admin:password -XDELETE -d “{\”name\”: \”elasticsearch\”}” https://mantl-control-01/api/1/packages

Customizing a Package

Let’s look at a slightly more complicated example. We want to deploy a 5-node Cassandra ring. First, create a JSON file (called cassandra.json for example) with the desired configuration:

{
“name”: “cassandra”,
“config”: {
“cassandra”: {
“node-count”: 5,
“seed-count”: 3
}
}
}

This indicates that we want to run a total of 5 Cassandra nodes with 3 being seed nodes. Now, we can install Cassandra with a familiar command:

curl -sku admin:password -d @cassandra.json https://mantl-control-01/api/1/packages

The only difference from the Elasticsearch install example is that we are telling curl to POST the JSON data from a file in the current directory. It will take several minutes for the Cassandra ring to bootstrap and become healthy.

Note: you will need to have a Mantl cluster with sufficient nodes and resources to run the above example.

Custom Packages

Besides the packages that are available in the Mantl repository, it is possible to use Mantl API to install your own custom packages. Maybe you want to run a framework that is not currently packaged or maybe you want to package your custom application so that your QA team can easily deploy multiple versions on-demand for testing purposes. Mantl API supports multiple repositories which are stored in the Consul K/V store. Consult the documentation for more information on building Mantl-compatible packages.

Other Functionality and the Future

Besides letting you discover, deploy, and remove packages, Mantl API let’s you inspect the metadata of a specific package. And, it also provides an easy interface to view (and remove) Mesos frameworks. We plan to continue to add packages to the repository and welcome contributions (both the Spark and the ArangoDB packages were contributed by the community). We have a lot more ideas for Mantl API in the future. Let us know what you would like to see!

Thanks to Asteris and specifically Ryan Eschinger for contributing the details of the Mantl API for this blog post.

If you are at the OpenStack Summit event this week, come by the Cisco Booth C11 to talk to the Mantl team.