Navigation

API resources

URL summary

URL View Examples GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/cli Cli       Yes    
api/v2/cluster Cluster Example Yes        
api/v2/cluster/<pk> Cluster Example Yes       Yes
api/v2/cluster/<fsid>/config Config Example Yes        
api/v2/cluster/<fsid>/config/<key> Config Example Yes        
api/v2/cluster/<fsid>/crush_rule_set Crush Rule Set Example Yes        
api/v2/cluster/<fsid>/crush_rule Crush Rule Example Yes        
api/v2/server/<fqdn>/debug_job Debug Job       Yes    
api/v2/event Event Example Yes        
api/v2/cluster/<fsid>/event Event Example Yes        
api/v2/server/<fqdn>/event Event Example Yes        
api/v2/info Info Example Yes        
api/v2/cluster/<fsid>/log Log Tail Example Yes        
api/v2/server/<fqdn>/log Log Tail Example Yes        
api/v2/server/<fqdn>/log/<log_path> Log Tail Example Yes        
api/v2/cluster/<fsid>/mon Mon   Yes        
api/v2/cluster/<fsid>/mon/<mon_id> Mon   Yes        
api/v2/cluster/<fsid>/mon/<mon_id>/status Mon   Yes        
api/v2/cluster/<fsid>/osd_config Osd Config   Yes     Yes  
api/v2/cluster/<fsid>/osd Osd Example Yes        
api/v2/cluster/<fsid>/osd/<osd_id> Osd Example Yes     Yes  
api/v2/cluster/<fsid>/osd /command Osd   Yes        
api/v2/cluster/<fsid>/osd/<osd_id>/command Osd   Yes        
api/v2/cluster/<fsid>/osd/<osd_id>/command/<command> Osd   Yes   Yes    
api/v2/cluster/<fsid>/pool Pool Example Yes   Yes    
api/v2/cluster/<fsid>/pool/<pool_id> Pool Example Yes     Yes Yes
api/v2/request/<request_id>/cancel Request       Yes    
api/v2/request/<request_id> Request   Yes        
api/v2/request Request   Yes        
api/v2/cluster/<fsid>/request/<request_id> Request Example Yes        
api/v2/cluster/<fsid>/request Request Example Yes        
api/v2/key Salt Key Example Yes     Yes Yes
api/v2/key/<minion_id> Salt Key Example Yes     Yes Yes
api/v2/cluster/<fsid>/server Server (within cluster) Example Yes        
api/v2/cluster/<fsid>/server/<fqdn> Server (within cluster) Example Yes        
api/v2/server Server Example Yes        
api/v2/server/<fqdn> Server Example Yes       Yes
api/v2/server/<fqdn>/grains Server Example Yes        
api/v2/cluster/<fsid>/sync_object Sync Object Example Yes        
api/v2/cluster/<fsid>/sync_object/<sync_type> Sync Object Example Yes        
api/v2/user User Example Yes   Yes    
api/v2/user/<pk> User Example Yes Yes   Yes Yes
api/v2/grains Grains Example Yes        
api/v2/auth/login Login Example Yes   Yes    
api/v2/auth/logout Logout   Yes   Yes    

API reference

Cli

Access the ceph CLI tool remotely.

To achieve the same result as running “ceph osd dump” at a shell, an API consumer may POST an object in either of the following formats:

{'command': ['osd', 'dump']}

{'command': 'osd dump'}

The response will be a 200 status code if the command executed, regardless of whether it was successful, to check the result of the command itself read the status attribute of the returned data.

The command will be executed on the first available mon server, retrying on subsequent mon servers if no response is received. Due to this retry behaviour, it is possible for the command to be run more than once in rare cases; since most ceph commands are idempotent this is usually not a problem.

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/cli     Yes    

Fields

Name Type Readonly Create Modify Description
out string False     Standard out
err string False     Standard error
status integer False     Exit code

Cluster

A Ceph cluster, uniquely identified by its FSID. All Ceph services such as OSDs and mons are namespaced within a cluster. Servers may host services for more than one cluster, although usually they only hold one.

Note that the name attribute of a Ceph cluster has no uniqueness, code consuming this API should always use the FSID to identify clusters.

Using the DELETE verb on a Ceph cluster will cause the Calamari server to drop its records of the cluster and services within the cluster. However, if the cluster still exists on servers managed by Calamari, it will be immediately redetected: only use DELETE on clusters which really no longer exist.

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster Yes        
api/v2/cluster/<pk> Yes       Yes

Fields

Name Type Readonly Create Modify Description
update_time datetime False     The time at which the last status update from this cluster was received
id field True     The FSID of the cluster, universally unique
name field True     Human readable cluster name, not a unique identifier

Config

Configuration settings from a Ceph Cluster.

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/config Yes        
api/v2/cluster/<fsid>/config/<key> Yes        

Fields

Name Type Readonly Create Modify Description
key string False     Name of the configuration setting
value string False     Current value of the setting, as a string

Crush Rule Set

A CRUSH rule is used by Ceph to decide where to locate placement groups on OSDs.

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/crush_rule_set Yes        

Fields

Name Type Readonly Create Modify Description
id integer False      
rules field False      

Crush Rule

A CRUSH ruleset is a collection of CRUSH rules which are applied together to a pool.

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/crush_rule Yes        

Fields

Name Type Readonly Create Modify Description
id integer False      
name string False     Human readable name
ruleset integer False     ID of the CRUSH ruleset of which this rule is a member
type string False     Data redundancy type (one of replicated, erasure)
min_size integer False     If a pool makes more replicas than this number, CRUSH will NOT select this rule
max_size integer False     If a pool makes fewer replicas than this number, CRUSH will NOT select this rule
steps field True     List of operations used to select OSDs
osd_count integer False     Number of OSDs which are used for data placement

Debug Job

For debugging and automated testing only.

URLs

URL GET PUT POST PATCH DELETE
api/v2/server/<fqdn>/debug_job     Yes    

Fields

No field data available

Event

Events generated by Calamari server in response to messages from servers and Ceph clusters. This resource is paginated.

Note that events are not visible synchronously with respect to all other API resources. For example, you might read the OSD map, see an OSD is down, then quickly read the events and find that the event about the OSD going down is not visible yet (though it would appear very soon after).

The severity attribute mainly follows a typical INFO, WARN, ERROR hierarchy. However, we have an additional level between INFO and WARN called RECOVERY. Where something going bad in the system is usually a WARN message, the opposite state transition is usually a RECOVERY message.

This resource supports “more severe than” filtering on the severity attribute. Pass the desired severity threshold as a URL parameter in a GET, such as ?severity=RECOVERY to show everything but INFO.

URLs

URL GET PUT POST PATCH DELETE
api/v2/event Yes        
api/v2/cluster/<fsid>/event Yes        
api/v2/server/<fqdn>/event Yes        

Fields

Name Type Readonly Create Modify Description
when datetime False     Time at which event was generated
severity field True     One of CRITICAL,ERROR,WARNING,RECOVERY,INFO
message string False     One line human readable description

Info

Provides metadata about the installation of Calamari server in use

URLs

URL GET PUT POST PATCH DELETE
api/v2/info Yes        

Fields

Name Type Readonly Create Modify Description
version string False     Calamari server version
license string False     Calamari license metadata
registered string False     Calamari registration metadata
hostname string False     Hostname of Calamari server
fqdn string False     Fully qualified domain name of Calamari server
ipaddr string False     IP address of Calamari server
bootstrap_url string False     URL to minion bootstrap script
bootstrap_rhel string False     Minion bootstrap command line for Red Hat systems
bootstrap_ubuntu string False     Minion bootstrap command line for Ubuntu systems

Log Tail

A primitive remote log viewer.

Logs are retrieved on demand from the Ceph servers, so this resource will return a 503 error if no suitable server is available to get the logs.

GETs take an optional lines parameter for the number of lines to retrieve.

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/log Yes        
api/v2/server/<fqdn>/log Yes        
api/v2/server/<fqdn>/log/<log_path> Yes        

Fields

Name Type Readonly Create Modify Description
lines string False      

Mon

Ceph monitor services.

Note that the ID used to retrieve a specific mon using this API resource is the monitor name as opposed to the monitor rank.

The quorum status reported here is based on the last mon status reported by the Ceph cluster, and also the status of each mon daemon queried by Calamari.

For debugging mons which are failing to join the cluster, it may be useful to show users data from the /status sub-url, which returns the “mon_status” output from the daemon.

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/mon Yes        
api/v2/cluster/<fsid>/mon/<mon_id> Yes        
api/v2/cluster/<fsid>/mon/<mon_id>/status Yes        

Fields

Name Type Readonly Create Modify Description
name string False     Human readable name
rank integer False     Unique of the mon within the cluster
in_quorum boolean False     True if the mon is a member of current quorum
server string False     FQDN of server running the OSD
addr string False     IP address of monitor service

Osd Config

Manage flags in the OsdMap

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/osd_config Yes     Yes  

Fields

Name Type Readonly Create Modify Description
pause boolean False   Allowed Disable IO requests to all OSDs in cluster
noup boolean False   Allowed Prevent OSDs from automatically getting marked as Up by the monitors. This setting is useful for troubleshooting
nodown boolean False   Allowed Prevent OSDs from automatically getting marked as Down by the monitors. This setting is useful for troubleshooting
noout boolean False   Allowed Prevent Down OSDs from being marked as out
noin boolean False   Allowed Prevent OSDs from booting OSDs from being marked as IN. Will cause cluster health to be set to WARNING
nobackfill boolean False   Allowed Disable backfill operations on cluster
norecover boolean False   Allowed Disable replication of Placement Groups
noscrub boolean False   Allowed Disables automatic periodic scrub operations on OSDs. May still be initiated on demand
nodeep-scrub boolean False   Allowed Disables automatic periodic deep scrub operations on OSDs. May still be initiated on demand

Osd

Manage Ceph OSDs.

Apply ceph commands to an OSD by doing a POST with no data to api/v2/cluster/<fsid>/osd/<osd_id>/command/<command> where <command> is one of (“scrub”, “deep-scrub”, “repair”)

e.g. Initiate a scrub on OSD 0 by POSTing {} to api/v2/cluster/<fsid>/osd/0/command/scrub

Filtering is available on this resource:

# Pass a ``pool`` URL parameter set to a pool ID to filter by pool, like this:
/api/v2/cluster/<fsid>/osd?pool=1

# Pass a series of ``id__in[]`` parameters to specify a list of OSD IDs
# that you wish to receive.
/api/v2/cluster/<fsid>/osd?id__in[]=2&id__in[]=3

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/osd Yes        
api/v2/cluster/<fsid>/osd/<osd_id> Yes     Yes  
api/v2/cluster/<fsid>/osd /command Yes        
api/v2/cluster/<fsid>/osd/<osd_id>/command Yes        
api/v2/cluster/<fsid>/osd/<osd_id>/command/<command> Yes   Yes    

Fields

Name Type Readonly Create Modify Description
uuid uuid string True     Globally unique ID for this OSD
up boolean False   Allowed Whether the OSD is running from the point of view of the rest of the cluster
in boolean False   Allowed Whether the OSD is ‘in’ the set of OSDs which will be used to store data
id integer True     ID of this OSD within this cluster
reweight float False   Allowed CRUSH weight factor
server string True     FQDN of server this OSD was last running on
pools field True     List of pool IDs which use this OSD for storage
valid_commands string True     List of commands that can be applied to this OSD
public_addr string True     Public/frontend IP address
cluster_addr string True     Cluster/backend IP address

Pool

Manage Ceph storage pools.

To get the default values which will be used for any fields omitted from a POST, do a GET with the ?defaults argument. The returned pool object will contain all attributes, but those without static defaults will be set to null.

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/pool Yes   Yes    
api/v2/cluster/<fsid>/pool/<pool_id> Yes     Yes Yes

Fields

Name Type Readonly Create Modify Description
name string False Required Allowed Human readable name of the pool, maychange over the pools lifetime at user request.
id string False     Unique numeric ID
size integer False Allowed Allowed Replication factor
pg_num integer False Required Allowed Number of placement groups in this pool
crush_ruleset integer False Allowed Allowed CRUSH ruleset in use
min_size integer False Allowed Allowed Minimum number of replicas required for I/O
crash_replay_interval integer False Allowed Allowed Number of seconds to allow clients to replay acknowledged, but uncommitted requests
pgp_num integer False Allowed Allowed Effective number of placement groups to use when calculating data placement
hashpspool boolean False Allowed Allowed Enable HASHPSPOOL flag
full boolean False     True if the pool is full
quota_max_objects integer False Allowed Allowed Quota limit on object count (0 is unlimited)
quota_max_bytes integer False Allowed Allowed Quota limit on usage in bytes (0 is unlimited)

Request

Calamari server requests, tracking long-running operations on the Calamari server. Some API resources return a 202 ACCEPTED response with a request ID, which you can use with this resource to learn about progress and completion of an operation. This resource is paginated.

May optionally filter by state by passing a ?state=<state> GET parameter, where state is one of ‘complete’, ‘submitted’.

The returned records are ordered by the ‘requested_at’ attribute, in descending order (i.e. the first page of results contains the most recent requests).

To cancel a request while it is running, send an empty POST to request/<request id>/cancel.

URLs

URL GET PUT POST PATCH DELETE
api/v2/request/<request_id>/cancel     Yes    
api/v2/request/<request_id> Yes        
api/v2/request Yes        
api/v2/cluster/<fsid>/request/<request_id> Yes        
api/v2/cluster/<fsid>/request Yes        

Fields

Name Type Readonly Create Modify Description
id string False     A globally unique ID for this request
state string False     One of ‘complete’, ‘submitted’
error boolean False     True if the request completed unsuccessfully
error_message string False     Human readable string describing failure if error is True
headline string False     Single sentence human readable description of the request
status string False     Single sentence human readable description of the request’s current activity, if it has more than one stage. May be null.
requested_at datetime False     Time at which the request was received by calamari server
completed_at datetime False     Time at which the request completed, may be null.

Salt Key

Ceph servers authentication with the Calamari using a key pair. Before Calamari accepts messages from a server, the server’s key must be accepted.

URLs

URL GET PUT POST PATCH DELETE
api/v2/key Yes     Yes Yes
api/v2/key/<minion_id> Yes     Yes Yes

Fields

Name Type Readonly Create Modify Description
id string False     The minion ID, usually equal to a host’s FQDN
status string False   Allowed One of ‘accepted’, ‘rejected’ or ‘pre’

Server (within cluster)

View of servers within a particular cluster.

Use the global server view for DELETE operations (there is no concept of deleting a server from a cluster, only deleting all record of it from any/all clusters).

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/server Yes        
api/v2/cluster/<fsid>/server/<fqdn> Yes        

Fields

Name Type Readonly Create Modify Description
fqdn string False     Fully qualified domain name
hostname string False     Unqualified hostname
services field False     List of Ceph services seenon this server
frontend_addr string False      
backend_addr string False      
frontend_iface string False      
backend_iface string False      
managed boolean False     True if this server is under Calamari server’s control, falseif the server’s existence was inferred via Ceph cluster maps.
last_contact datetime False     The time at which this server last communicated with the Calamariserver. This is always null for unmanaged servers
boot_time datetime False     The time at which this server booted. This is always null for unmanaged servers
ceph_version string False     The version of Ceph installed. This is always null for unmanaged servers.

Server

Servers which are in communication with Calamari server, or which have been inferred from the OSD map. If a server is in communication with the Calamari server then it is considered managed.

If a server is only known via the OSD map, then the FQDN attribute will be set to the hostname. This server is later added as a managed server then the FQDN will be modified to its correct value.

URLs

URL GET PUT POST PATCH DELETE
api/v2/server Yes        
api/v2/server/<fqdn> Yes       Yes
api/v2/server/<fqdn>/grains Yes        

Fields

Name Type Readonly Create Modify Description
fqdn string False     Fully qualified domain name
hostname string False     Unqualified hostname
managed boolean False     True if this server is under Calamari server’s control, falseif the server’s existence was inferred via Ceph cluster maps.
last_contact datetime False     The time at which this server last communicated with the Calamariserver. This is always null for unmanaged servers
boot_time datetime False     The time at which this server booted. This is always null for unmanaged servers
ceph_version string False     The version of Ceph installed. This is always null for unmanaged servers.
services field False     List of Ceph services seenon this server

Sync Object

These objects are the raw data received by the Calamari server from the Ceph cluster, such as the cluster maps

URLs

URL GET PUT POST PATCH DELETE
api/v2/cluster/<fsid>/sync_object Yes        
api/v2/cluster/<fsid>/sync_object/<sync_type> Yes        

Fields

No field data available

User

The Calamari UI/API user account information.

You may pass ‘me’ as the user ID to refer to the currently logged in user, otherwise the user ID is a numeric ID.

Because all users are superusers, everybody can see each others accounts using this resource. However, users can only modify their own account (i.e. the user being modified must be the user associated with the current login session).

URLs

URL GET PUT POST PATCH DELETE
api/v2/user Yes   Yes    
api/v2/user/<pk> Yes Yes   Yes Yes

Fields

Name Type Readonly Create Modify Description
id integer True      
username string False     Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ characters
password string False      
email email False      

Grains

The salt grains for the host running Calamari server. These are variables from Saltstack that tell us useful properties of the host.

The fields in this resource are passed through verbatim from SaltStack, see the examples for which fields are available.

URLs

URL GET PUT POST PATCH DELETE
api/v2/grains Yes        

Fields

No field data available

Login

This resource is used to authenticate with the REST API by POSTing a message as follows:

{
    "username": "<username>",
    "password": "<password>"
}

If authentication is successful, 200 is returned, if it is unsuccessful then 401 is returend.

URLs

URL GET PUT POST PATCH DELETE
api/v2/auth/login Yes   Yes    

Fields

No field data available

Logout

The resource is used to terminate an authenticated session by POSTing an empty request.

URLs

URL GET PUT POST PATCH DELETE
api/v2/auth/logout Yes   Yes    

Fields

No field data available

Table Of Contents

Previous topic

Conventions

Next topic

Examples for api/v2/cluster/<fsid>/derived_object/<derived_type>

This Page

Navigation

© Copyright 2014, Red Hat Inc.. Created using Sphinx 1.1.3.