Ceph

h1. 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":http://calamari.readthedocs.org/en/latest/calamari_rest/resources/resources.html 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:

<pre>

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

</pre>

*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:

<pre>

GET /api/v2/cluster/xyz/server

</pre>

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:

<pre>

POST /api/v2/cluster/xyz/pool

{"name": "test", "pg_num": 64, "crush_ruleset": 2}   

</pre> 

*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:

<pre>

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

</pre>

*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:

<pre>

GET /api/v1/cluster/xyz/health

</pre>

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:

<pre>

GET /api/v2/cluster/xyz/log

</pre>