Apr 25, 2018
Kaitlin Carter
D2iQ
4 min read
The DC/OS UI is great for checking the cluster state or deploying a demo application. But for production scenarios we need a more programmatic way of deploying and checking the current state of the application or cluster, imagine for example a CI/CD system or a metric dashboard.
This blog post will provide an overview of the DC/OS APIs and how to use them, starting with an overview and a reference, and then bringing it all together with an example that creates tokens and collects metrics.
There are many benefits of using the DC/OS APIs instead of a command line utility or user dashboard. The benefits center around automation, version control, and integration.
DC/OS API Overview
Before we dive into API usage, let's take a look at the various components that enable them. The two main components are the Master Admin Router and Agent Admin Router, often referred to collectively as the Admin Router. The Admin Router is responsible for routing requests to the correct component and ensuring the requester has the correct credentials. Both the DC/OS UI and CLI also use the Admin Router. The Admin Router makes it possible to retrieve static files and retrieve resources from another URL.
In total, DC/OS has twelve available APIs. The APIs allow users to interact with the various components of DC/OS for cluster management and container orchestration.
The available APIs are:
- Marathon
- Apache Mesos
- MesosDNS
- Cluster Link
- Metronome
- DC/OS Logs
- DC/OS Metrics
- DC/OS Systems Health
- Pkpanda
- DC/OS Secrets
- IAM
- CA API
We recommend reviewing the components guide for more information on each API available in DC/OS.
Process Automation & Version Control
First, let's take a look at how the DC/OS APIs can be used for automation and version control as they relate to the common operation of token generation. Tokens are commonly used for API authorization and creating additional security for service accounts. Token generation is a great process to automate and apply version control, because tokens usually have short lifespans. In DC/OS Enterprise, the IAM API allows users to create tokens for individual users, as well as manage the other processes required for token generation. This includes; managing users, groups, and permissions. Below is a cURL example of token generation that could be added to a script:
curl -X POST -H "Content-type: application/json" -d @user_token.json http://${master}/acs/api/v1/auth/login
In the above example we are sending a POST request to the master. The data file user_token.json should contain the user id, password, and token expiration date:
{
"uid": "clark_kent",
"password": "deleteme",
"exp": 3
}
Don't forget to remove any tokens or private information before pushing code to a version control repository.
Software Integration
The second use case, software integration, is frequently implemented when integrating logging and metrics APIs with monitoring software. DC/OS has one specific API for logging and one for metrics. Additionally, many of the other APIs provide logging or metrics for their component. Review individual APIs to learn more about their capabilities.
DC/OS even offers service catalog packages that simplify the process of setting up monitoring software. For example, the Kibana certified package can be used with the Elastic certified package and Logstash to view metrics data for monitoring. Below are two requests that could be added to a Logstash pipeline that retrieves data from a DC/OS cluster, then stores it in an Elasticsearch cluster:
- Logging information for the Marathon component:
curl -X GET -H "Authorization: token=${token}" -H "Accept: text/plain" http://${master}/system/v1/logs/v1/range/?filter="_SYSTEMD_UNIT:dcos-marathon.service"
- Metrics information for the DC/OS Master:
curl -X GET -H "Authorization: token=${token}" http://${master}/system/v1/metrics/v0/node
The first request is for the DC/OS Log API to retrieve log output from the Journal that is specific to the Marathon service component. The second is for the DC/OS Metrics API to request metrics about the master.
Please note that both of the APIs mentioned in this example require proper authorization.
Learn More About DC/OS APIs
Interested in learning more about automating token generation or setting up monitoring software? You can get hands-on experience with both use cases (and more!) in the Using DC/OS APIs course. You can sign-up on our training site for the next available course later this spring. You can also see our entire course offering catalog and sign up for one of our other courses there. Currently, we offer three other courses regularly: Enterprise DC/OS Fundamentals, Day Two Operations, and DC/OS and the Big Data Pipeline.
