An API interface to Mantl.

Currently, Mantl API allows you to install and uninstall DCOS packages on Mantl. More capabilities are planned for the future.

Table of Contents

• Mantl API
  • Mantl API on Mantl Clusters
  • Building
  • Deploying Manually
    • Options
  • Package Repository
    • Tree Structure
    • Multiple Repositories
    • Configuring Sources
    • Synchronizing Repository Sources
  • Packages
    • Structure
      • package.json
      • config.json
      • mantl.json
      • marathon.json
      • uninstall.json
    • Developing Packages
  • Usage
    • Installing a Package
    • Uninstalling a Package
  • API Reference
    • Endpoints
    • GET /health
    • GET /1/packages
    • GET /1/packages/
    • POST /1/install
    • DELETE /1/install
    • GET /1/frameworks
    • DELETE /1/frameworks/:id
  • Comparison to Other Software
  • Future Enhancement Ideas
  • License

As of the 0.5 release, Mantl API is installed by default on Mantl clusters. It is deployed via Marathon and will be running on one of the worker nodes. Mantl automatically discovers the Mantl API instance and puts it behind Nginx on all control nodes at the /api endpoint. By default, it is secured with SSL and basic authentication. As an example, on a default Mantl install, you can retrieve the list of available packages by running a command like the following:

curl -k -u admin:mantlpw https://mantl-control-01/api/1/packages

You just need to update the command with the correct host name and credentials for your cluster. All of the examples in this document will assume you are working with Mantl API on a Mantl cluster and will use urls underneath /api.

docker build -t mantl-api .

You can run Mantl API on your cluster via Marathon. An example mantl-api.json is included below:

{
  "id": "/mantl-api",
  "container": {
    "type": "DOCKER",
    "docker": {
      "image": "ciscocloud/mantl-api:0.1.0",
      "network": "BRIDGE",
      "portMappings": [
        { "containerPort": 4001, "hostPort": 0 }
      ]
    }
  },
  "instances": 1,
  "cpus": 1.0,
  "mem": 512,
  "constraints": [["hostname", "UNIQUE"]],
  "env": {
    "CONSUL_HTTP_SSL_VERIFY": "false",
    "MANTL_API_LOG_LEVEL": "debug",
    "MANTL_API_CONSUL": "https://consul.service.consul:8500",
    "MANTL_API_MESOS_PRINCIPAL": "mantl-api",
    "MANTL_API_MESOS_SECRET": "secret"
  },
  "healthChecks": [
    {
      "protocol": "HTTP",
      "path": "/health",
      "gracePeriodSeconds": 3,
      "intervalSeconds": 10,
      "portIndex": 0,
      "timeoutSeconds": 10,
      "maxConsecutiveFailures": 3
    }
  ]
}

You will need to replace the MANTL_API_MESOS_PRINCIPAL and MANTL_API_MESOS_SECRET variables with valid Mesos credentials. These can be found in the security.yml file that was generated when you ran security-setup for your Mantl cluster.

All Mantl API configuration can be set with environment variables. See below for the additional configuration options that are available.

To install Mantl API, you can submit the above json to Marathon.

curl -k -u admin:mantlpw -X POST -d @mantl-api.json -H "Content-type: application/json" https://mantl-control-01/marathon/v2/apps

You will need to replace admin:mantlpw with valid Marathon credentials (see marathon_http_credentials in your security.yml). You will also replace mantl-control-01 with the host of one your Mantl control nodes.

After a few moments, Mantl API should be running on your cluster.

When configured with either vault-token or vault-cubbyhole-token, mantl-api will contact Vault to retrieve its secrets. They should be stored at secret/mantl-api. mantl-api will look for the following keys within that secret's Data field: mesos-principal, mesos-secret, marathon-user, and marathon-password. You don't have to store all of your secrets in Vault to take advantage of this feature, mantl-api will only use the ones that are present.

Configuration options:

--config-file string             The path to a (optional) configuration file
--consul string                  Consul API address (default "http://localhost:8500")
--consul-acl-token string        Consul ACL token for accessing mantl-install/apps path
--consul-no-verify-ssl           Disable Consul SSL verification
--consul-refresh-interval int    The number of seconds after which to check consul for package requests (default 10)
--force-sync                     Force a synchronization of respository all sources at startup
--listen string                  listen for connections on this address (default ":4001")
--log-format string              specify output (text or json) (default "text")
--log-level string               one of debug, info, warn, error, or fatal (default "info")
--marathon string                Marathon API address
--marathon-no-verify-ssl         Disable Marathon SSL verification
--marathon-password string       Marathon API password
--marathon-user string           Marathon API user
--mesos string                   Mesos API address
--mesos-no-verify-ssl            Disable Mesos SSL verification
--mesos-principal string         Mesos principal for framework authentication
--mesos-secret string            Deprecated. Use mesos-secret-path instead
--mesos-secret-path string       Path to a file on host sytem that contains the mesos secret for framework authentication (default "/etc/sysconfig/mantl-api")
--vault-cubbyhole-token string   token for retrieving token from vault
--vault-token string             token for retrieving secrets from vault
--zookeeper string               Comma-delimited list of zookeeper servers

Every option can be set via environment variables prefixed with MANTL_API. For example, you can use MANTL_API_LOG_LEVEL for log-level, MANTL_API_CONSUL for consul, and so on. You can also specify all configuration from a TOML configuration file using the config-file argument.

Mantl API depends on a repository of package definitions stored in the Consul KV store. mantl-universe is the authoritative repository of packages that work out-of-the-box on Mantl today. You can install any of the DCOS packages but you will likely have to customize some of the configuration to work on Mantl. Most of the Mesosphere packages assume that service discovery is provided by Mesos-DNS and need to be converted to work with the Consul DNS interface.

Mantl API is compatible with the package repository structure created for Mesosphere DCOS packages. Each repository contains a directory structure that looks something like this:

repo/packages
├── C
│   ├── cassandra
│   │   ├── 0
│   │   │   ├── config.json
│   │   │   ├── marathon.json
│   │   │   └── package.json
│   │   ├── 1
│   │   │   ├── command.json
│   │   │   ├── config.json
│   │   │   ├── marathon.json
│   │   │   └── package.json
├── H
│   └── hdfs
│       ├── 0
│       │   ├── command.json
│       │   ├── config.json
│       │   ├── marathon.json
│       │   └── package.json
│       ├── 1
│       │   ├── command.json
│       │   ├── config.json
│       │   ├── marathon.json
│       │   └── package.json
|__ ...

For each named package (cassandra and hdfs in the example above), there is a directory of JSON files corresponding to each version.

Mantl API supports the ability to layer repositories. By default, Mantl API is configured with Mantl Universe as the base repository. It is possible to layer additional repositories on top.

The order of the repositories is important. By default, Mantl Universe is configured with index 0. In the Consul KV store, the repositories are stored as follows:

Repositories with higher indexes are prioritized. When Mantl API receives a request to install a particular package, it will use the package definition found in the repository with the highest index. If there are any required files missing, it will look for the corresponding package version in repositories with the lower indexes until it is able to construct a valid, installable package. For example, if mantl-install/repository/1/repo/packages/H/hdfs/1 (Custom Repository) exists but does not have a config.json file, Mantl API will merge in the config.json file from mantl-install/repository/0/repo/packages/H/hdfs/1 (Mantl Universe). This enables the ability to make small package customizations rather than creating an entirely new version of a package.

If you want to use additional or different source repositories, you can specify a configuration file that contains your source definitions using the --config-file argument. Here is an example configuration file that uses 2 sources — one named "mesosphere" from a git repository and the other named "mantl-universe" from the local file system:

[sources]

[sources.mesosphere]
path = "https://github.com/mesosphere/universe.git"
type = "git"
index = 0

[sources.mantl]
path = "/home/ryan/Projects/mantl-universe"
index = 1

The following attributes can be specified for each source:

• path
• type — git or filesystem (default)
• index
• branch — only applicable for the git type

The package repositories are synchronized to the Consul K/V backend. If you want to refresh your repositories, you can run the following command:

mantl-api sync --consul http://consul.service.consul:8500

The goals of the packaging system are:

1. Make it easy to contribute packages to Mantl
2. Rely on the existing DCOS package structure when possible
3. Immutable package versions
4. Ability for users to build customized package versions

Mantl Universe packages are based on the DCOS packaging format from Mesosphere. Packages in Mantl Universe are intended to be installed with Mantl API and may depend on the corresponding package version in the Mesosphere Universe.

Each package is made up of several json files:

The package.json file is where package metadata is set. This includes things like the name, version, description, and maintainer of the package.

The config.json file contains the configuration schema and defaults for the package.

The mantl.json overrides configuration defaults from the config.json file (either directly in the package or from the config.json for the corresponding package version in the Mesosphere universe) with values that are known to work on Mantl.

Also, the presence of the mantl.json dictates whether the package is "supported" on Mantl. It can be empty {} if there is no specific changes required to make the package run on Mantl.

mantl.json includes a setting that allows you to control how the application is load balanced on Mantl clusters. Currently, it is a simple toggle that allows you to control whether the application will be load balanced by Traefik in a Mantl cluster. Here is an example mantl.json with no other settings other than the load balancing configuration:

{
  "mantl": {
    "load-balancer": "external|off"
  }
}

If mantl.load-balancer is set to "external", the application will be included in the Traefik load balancer. Any other value will disable load balancing.

The marathon.json file contains the Marathon application json for the package. It is a mustache template that is rendered using data from config.json and mantl.json.

The uninstall.json defines additional behavior when uninstalling a package. The uninstall support is currently limited to removing zookeeper nodes. It is also a mustache template so that variables from config.json and mantl.json can be used in the uninstall definition.

{
  "zookeeper": {
    "delete": [
      {
        "path": "{{kafka.storage}}",
        "always": true
      }
    ]
  }
}

Example uninstall.json that deletes zookeeper nodes with a path based on the kafka.storage variable.

When developing packages, it is easiest to run Mantl API locally and point it to a Mantl cluster. Using a Vagrant Mantl cluster is the simplest and fastest as pointing Mantl API to a remote cluster can be complicated by security settings. However, here is an example configuration file (config.toml) showing how to run Mantl API locally against a remote Mantl cluster.

consul = "https://control-node:8500"
consul-no-verify-ssl = true
marathon = "https://control-node/marathon"
marathon-user = "user"
marathon-password = "password"
marathon-no-verify-ssl = true
mesos-principal = "mesos-principal"
mesos-secret = "mesos-secret"
mesos = "http://control-node:15050"
mesos-no-verify-ssl = true
zookeeper = "control-node:2181"

# global
log-level = "debug"

[sources]

[sources.mantl]
path = "/Users/ryan/Projects/mantl-universe"
index = 0

You will need to update the URLs and credentials as appropriate for your cluster.

Finally, you will need to update firewalls and security groups so that your development machine has access to the above ports.

You can then run Mantl API with a command like the following:

./bin/mantl-api --config-file config.toml

As shown above, you should have a copy of a valid repository on your local file system. The easiest thing to do is clone or fork Mantl. Create or update your package in this local repository. When you want to test it, you first need to synchronize it to the Mantl cluster. You can run a command like the following to synchronize the repository:

./bin/mantl-api --config-file config.toml sync

Then, you should be able to install your package using normal Mantl API calls. For example:

curl -X POST -d "{\"name\": \"mycustompackage\"}" http://localhost:4001/api/1/install

The following example curl commands assume a default Mantl API installation (with a control node called mantl-control-01) on a Mantl cluster with SSL and authentication turned off. You will need to adjust the commands to work with valid URLs and credentials for your cluster.

It is a single API call to install a package. In the example below, we are going to run Cassandra on our Mantl cluster.

curl -X POST -d "{\"name\": \"cassandra\"}" http://mantl-control-01/api/1/install

You can use the Marathon API or UI to find this. You'll also need to make sure that the port is accessible to the machine where you are calling the API from. Adjust the security groups or firewall rules for your platform accordingly.

After about 5 minutes, you should have Cassandra up and running on your Mantl cluster.

Uninstalling is just as easy. Run the command below to uninstall Cassandra:

curl -X DELETE -d "{\"name\": \"cassandra\"}" http://mantl-control-01/api/1/install

After a moment, Cassandra will have been removed from your cluster. This will also remove the Zookeeper state for the Cassandra framework. In the future, we will add more flexibility in being able to control what is uninstalled.

GET /health: returns OK

curl http://mantl-control-01/api/health

OK

GET /1/packages: returns a JSON representation of packages available to install.

curl http://mantl-control-01/api/1/packages | jq .

[
  {
    "name": "cassandra",
    "description": "Apache Cassandra running on Apache Mesos",
    "framework": true,
    "currentVersion": "0.2.0-1",
    "supported": true,
    "tags": [
      "mesosphere",
      "framework",
      "data",
      "database"
    ],
    "versions": {
      "0.1.0-1": {
        "version": "0.1.0-1",
        "index": "0",
        "supported": true
      },
      "0.2.0-1": {
        "version": "0.2.0-1",
        "index": "1",
        "supported": true
      }
    }
  },
  ...
  {
    "name": "swarm",
    "description": "Swarm is a Docker-native clustering system.",
    "framework": true,
    "currentVersion": "0.4.0",
    "supported": false,
    "tags": [
      "mesosphere",
      "framework",
      "docker"
    ],
    "versions": {
      "0.4.0": {
        "version": "0.4.0",
        "index": "0",
        "supported": false
      }
    }
  }
]

GET /1/packages/<package>: returns a JSON representation of a package.

curl http://mantl-control-01/api/1/packages/cassandra | jq .

{
  "name": "cassandra",
  "description": "Apache Cassandra running on Apache Mesos",
  "framework": true,
  "currentVersion": "0.2.0-1",
  "supported": true,
  "tags": [
    "mesosphere",
    "framework",
    "data",
    "database"
  ],
  "versions": {
    "0.1.0-1": {
      "version": "0.1.0-1",
      "index": "0",
      "supported": true
    },
    "0.2.0-1": {
      "version": "0.2.0-1",
      "index": "1",
      "supported": true
    }
  }
}

POST /1/install: post a JSON representation of a package to install.

curl -X POST -d "{\"name\": \"cassandra\"}" http://mantl-control-01/api/1/install | jq .

{
  "id": "/cassandra/dcos-test",
  "cmd": "$(pwd)/jre*/bin/java $JAVA_OPTS -classpath cassandra-mesos-framework.jar io.mesosphere.mesos.frameworks.cassandra.framework.Main",
  "args": null,
  "user": null,
  "env": {
    "CASSANDRA_ZK_TIMEOUT_MS": "10000",
    "JAVA_OPTS": "-Xms256m -Xmx256m",
    "MESOS_AUTHENTICATE": "true",
    "CASSANDRA_RESOURCE_CPU_CORES": "0.1",
    "CASSANDRA_FAILOVER_TIMEOUT_SECONDS": "604800",
    "DEFAULT_SECRET": "secret",
    "CASSANDRA_BOOTSTRAP_GRACE_TIME_SECONDS": "120",
    "CASSANDRA_DEFAULT_DC": "DC1",
    "CASSANDRA_RESOURCE_MEM_MB": "768",
    "MESOS_ZK": "zk://zookeeper.service.consul:2181/mesos",
    "CASSANDRA_DATA_DIRECTORY": ".",
    "DEFAULT_PRINCIPAL": "mantl-install",
    "CASSANDRA_FRAMEWORK_MESOS_ROLE": "*",
    "CASSANDRA_CLUSTER_NAME": "dcos-test",
    "CASSANDRA_RESOURCE_DISK_MB": "16",
    "CASSANDRA_SEED_COUNT": "2",
    "CASSANDRA_ZK": "zk://zookeeper.service.consul:2181/cassandra-mesos/dcos-test",
    "CASSANDRA_NODE_COUNT": "3",
    "CASSANDRA_DEFAULT_RACK": "RAC1",
    "CASSANDRA_HEALTH_CHECK_INTERVAL_SECONDS": "60"
  },
  "instances": 1,
  "cpus": 0.5,
  "mem": 512,
  "disk": 0,
  "executor": "",
  "constraints": [],
  "uris": [
    "https://downloads.mesosphere.io/cassandra-mesos/artifacts/0.2.0-1/cassandra-mesos-0.2.0-1.tar.gz",
    "https://downloads.mesosphere.io/java/jre-7u76-linux-x64.tar.gz"
  ],
  "storeUrls": [],
  "ports": [
    0
  ],
  "requirePorts": false,
  "backoffFactor": 0,
  "container": null,
  "healthChecks": [
    {
      "path": "/health/cluster",
      "protocol": "HTTP",
      "portIndex": 0,
      "command": null,
      "gracePeriodSeconds": 120,
      "intervalSeconds": 15,
      "timeoutSeconds": 5,
      "maxConsecutiveFailures": 0,
      "ignoreHttp1xx": false
    },
    {
      "path": "/health/process",
      "protocol": "HTTP",
      "portIndex": 0,
      "command": null,
      "gracePeriodSeconds": 120,
      "intervalSeconds": 30,
      "timeoutSeconds": 5,
      "maxConsecutiveFailures": 3,
      "ignoreHttp1xx": false
    }
  ],
  "dependencies": [],
  "upgradeStrategy": {
    "minimumHealthCapacity": 0,
    "maximumOverCapacity": 0
  },
  "labels": {
    "MANTL_PACKAGE_NAME": "cassandra",
    "MANTL_PACKAGE_IS_FRAMEWORK": "true",
    "DCOS_PACKAGE_FRAMEWORK_NAME": "cassandra.dcos-test",
    "MANTL_PACKAGE_FRAMEWORK_NAME": "cassandra.dcos-test",
    "MANTL_PACKAGE_INDEX": "1",
    "MANTL_PACKAGE_VERSION": "0.2.0-1"
  },
  "acceptedResourceRoles": null,
  "version": "2015-09-17T22:19:24.576Z",
  "tasks": [],
  "deployments": [
    {
      "id": "dd113528-388c-4438-a524-9eba45aa2908"
    }
  ],
  "tasksStaged": 0,
  "tasksRunning": 0,
  "tasksHealthy": 0,
  "tasksUnhealthy": 0,
  "backoffSeconds": 0,
  "maxLaunchDelaySeconds": 3600
}

DELETE /1/install: post a JSON representation of package specific uninstall options.

curl -X DELETE -d "{\"name\": \"cassandra\"}" http://mantl-control-01/api/1/install

GET /1/frameworks: returns a JSON representation of mesos frameworks.

Append a query string of ?completed to list completed frameworks.

curl -s http://mantl-control-01/api/1/frameworks

[
  {
    "name": "elasticsearch",
    "id": "e8569827-307e-416c-8186-47e3d08555b2-0001",
    "active": true,
    "hostname": "mi-worker-001.novalocal",
    "user": "root",
    "registeredTime": "2016-01-30T17:30:44-05:00",
    "reregisteredTime": "0001-01-01T00:00:00Z",
    "activeTasks": 1
  },
  {
    "name": "chronos",
    "id": "8e1863a6-3664-4f93-9f13-44a187a7fca8-0000",
    "active": true,
    "hostname": "mi-control-01.novalocal",
    "user": "root",
    "registeredTime": "2016-01-30T13:57:25-05:00",
    "reregisteredTime": "0001-01-01T00:00:00Z",
    "activeTasks": 0
  },
  {
    "name": "marathon",
    "id": "90e1b7ed-9369-4ec8-b50c-331a47e28468-0000",
    "active": true,
    "hostname": "mi-control-01.node.consul",
    "user": "root",
    "registeredTime": "2016-01-30T13:57:24-05:00",
    "reregisteredTime": "2016-01-31T23:39:52-05:00",
    "activeTasks": 7
  }
]

DELETE /1/frameworks/<mesos-framework-id>: Shutdown the mesos framework with the specified ID.

curl -X DELETE http://mantl-control-01/api/1/frameworks/a1c0c9da-f554-4140-8e04-bb92ac9d2a39-0000

Mantl API takes advantage of the Mesosphere DCOS packaging format and provides capabilities similar to the package command in the DCOS CLI. The goal is to provide a simple, API-driven way to install and uninstall pre-built packages on Mantl clusters. In the future, mantl-api will contain additional functionality for maintaining and operating Mantl clusters.

1. Discover running packages (in progress) so that they can automatically be added to UI when applicable.
2. Operational tasks. Ability to see and manage Mesos frameworks, Marathon tasks, health checks, logs, etc.
3. Addons / Optional components. Turn on and off optional components.
4. Cluster management. Scale cluster up and down.
5. Other ideas?

mantl-api is released under the Apache 2.0 license (see LICENSE)