6 Important Calamari API Methods for Developers¶

The Calamari API packs a lot of raw power under its hood. But if you're just getting started, the 50 (or so) available API endpoints might be too much information to process at once.
That's where this cheat sheet comes in. It identifies 6 common developer use cases and gives you a quick snapshot of the API endpoint corresponding to each, so you can get up and running quickly. Use it to kickstart your Calamari API client development, or just to get a taster of what Calamari can do for you. Happy coding!

1. Retrieve or update the CRUSH map: /api/v2/cluster/<fsid>/crush_map
CRUSH maps contain rulesets that tell Ceph how data should be replicated across the cluster's storage pools. As such, they're pretty important - which gives this API endpoint instant VIP status on this short list. Use a GET request to retrieve the current CRUSH map for your cluster, or replace the current CRUSH map with a new one by including it in the POST request body. For example, the request below sends a new CRUSH map to the cluster:

POST /api/v2/cluster/xyz/crush_map
# begin crush map
tunable choose_local_tries 0
tunable choose_local_fallback_tries 0
tunable choose_total_tries 50
tunable chooseleaf_descend_once 1
# devices
device 0 osd.0
device 1 device1
device 2 osd.2
# types
type 0 osd
type 1 host
type 2 chassis
type 3 rack
type 4 row
type 5 pdu
type 6 pod
type 7 room
type 8 datacenter
type 9 region
type 10 root
# buckets
host node2 {
        id -2           # do not change unnecessarily
        # weight 0.010
        alg straw
        hash 0  # rjenkins1
        item osd.0 weight 0.010
}
host node3 {
        id -3           # do not change unnecessarily
        # weight 0.010
        alg straw
        hash 0  # rjenkins1
        item osd.2 weight 0.010
}
root default {
        id -1           # do not change unnecessarily
        # weight 0.020
        alg straw
        hash 0  # rjenkins1
        item node2 weight 0.010
        item node3 weight 0.010
}
# rules
rule replicated_ruleset {
        ruleset 0
        type replicated
        min_size 1
        max_size 10
        step take default
        step chooseleaf firstn 0 type host
        step emit
}
# end crush map

2. Get an overview of the cluster: /api/v2/cluster/<fsid>/server
When you have a few hundred OSDs to deal with, you'll appreciate this API endpoint, which gives you a birds-eye view of the servers in a specified cluster, together with their names, IP addresses and list of running services. Simply send a GET request as below, and be prepared to be awed with the amount of data available:

GET /api/v2/cluster/xyz/server

Unfortunately you can't yet filter that output but if what you're really after is a list of hosts running specific services, you can always use /api/v2/cluster/<fsid>/osd to get a list of OSDs or /api/v2/cluster/<fsid>/mon to get a list of monitor nodes.

3. Create new storage pools: /api/v2/cluster/<fsid>/pool
The Calamari API makes it possible to create, delete and manage your pools remotely. Send a GET request to this API endpoint to retrieve a list of available pools, or send a POST request with the pool name and number of placement groups to create a new pool. For example, to create a new pool named 'test' with 64 placement groups, perform a POST request as below:

POST /api/v2/cluster/xyz/pool
{"name": "test", "pg_num": 64, "crush_ruleset": 2}   

4. Repair or scrub OSDs: /api/v2/cluster/<fsid>/osd/<id>/command/<command>
Want to scrub or repair your OSDs? Send a POST request to this API endpoint, remembering to specify the OSD ID and one of the commands 'scrub', 'deep_scrub' or 'repair' to perform the corresponding operation on the OSD. For example, to repair OSD 1, perform a POST request as below:

POST /api/v2/cluster/xyz/osd/1/command/repair

5. Get cluster health and status: /api/v1/cluster/<fsid>/health
Need to quickly check on your cluster's health? Use this API endpoint to get a quick snapshot of whether things are terrible or terrific. The output is equivalent to that of the 'ceph health' command.
Here's an example:

GET /api/v1/cluster/xyz/health

The response includes an 'overall_status' field which reports the current state of the cluster and additional 'summary' fields containing more granular information.

*6. Watch cluster activity in real time: /api/v2/cluster/<fsid>/log
*The larger the cluster, the more there is going on at any given time. Use the API endpoint above to get an ongoing log of cluster events. To see it in action, send a GET request as below:

GET /api/v2/cluster/xyz/log