Documentation for ceph-rest-api

dmsimard

I learned that there was a Ceph REST API and I experimented with it a bit.

I said the documentation was lacking and I take that back, I didn’t catch on that the API documentation was built into the application. I opened a pull request to make the documentation a bit more explicit about that: https://github.com/ceph/ceph/pull/1026

Here’s what the API documentation currently looks like:

Possible commandsMethodDescription
auth/add?entity=entity()&caps={c
aps() […]}PUTadd auth info forfrom input file, or random key if no input given, and/or any caps specified in the command
auth/caps?entity=entity()&caps=c
aps() […]PUTupdate caps forfrom caps specified in the command
auth/del?entity=entity()PUTdelete all caps for
auth/export?entity={entity()}GETwrite keyring for requested entity, or master keyring if none given
auth/get?entity=entity()GETwrite keyring file with requested key
auth/get-key?entity=entity()GETdisplay requested key
auth/get-or-create?entity=entity(<string
>)&caps={caps() […]}PUTadd auth info forfrom input file, or random key if no input given, and/or any caps specified in the command
auth/get-or-create-key?entity=entity(<st
ring>)&caps={caps()
[…]}PUTget, or add, key forfrom system/caps pairs specified in the command. If key already exists, any given caps must match the existing caps for that key.
auth/importPUTauth import: read keyring file from -i
auth/listGETlist authentication state
auth/print-key?entity=entity()GETdisplay requested key
auth/print_key?entity=entity()GETdisplay requested key
tell//bench?count={count(
)}&size={size()}PUTOSD benchmark: write-byte objects, (default 1G size 4MB). Results in log.
compactPUTcause compaction of monitor's leveldb storage
config-key/del?key=key()PUTdelete
config-key/exists?key=key()GETcheck for's existence
config-key/get?key=key()GETget
config-key/listGETlist keys
config-key/put?key=key()&val={va
l()}PUTput, value
tell/<osdid-or-
pgid>/cpu_profiler?arg=arg(statusflush)PUT
tell//debug/kick_recovery
_wq?delay=delay(<int[0-]>)PUTset osd_recovery_delay_start to
tell//debug_dump_missing?
filename=filename()GETdump missing objects to a named file
df?detail={detail}GETshow cluster free space stats
tell/<osdid-or-
pgid>/dump_pg_recovery_statsGETdump pg recovery statistics
tell//flush_pg_statsPUTflush pg stats
fsidGETshow cluster FSID/UUID
health?detail={detail}GETshow cluster health
tell//heap?heapcmd=heapcm
d(dumpstart_profilerstop_profiler
asestats)PUT
heap?heapcmd=heapcmd(dumpstart_profiler
stop_profilerreleasestats)
tell//injectargs?injected
_args=injected_args()
[…]PUTinject configuration arguments into running OSD
injectargs?injected_args=injected_args(<
string>) […]PUTinject config arguments into monitor
tell//list_missing?offset
={offset()}GETlist missing objects on this pg, perhaps starting at an offset given in JSON
tell//list_missing?offset
={offset()}PUTlist missing objects on this pg, perhaps starting at an offset given in JSON
log?logtext=logtext()
[…]PUTlog supplied text to the monitor log
tell/<osdid-or-
pgid>/mark_unfound_lost?mulcmd=revertPUTmark all unfound objects in this pg as lost, either removing or reverting to a prior version if one is available
tell//mark_unfound_lost/r
evert?mulcmd=revertPUTmark all unfound objects in this pg as lost, either removing or reverting to a prior version if one is available
mds/add_data_pool?pool=pool()PUTadd data pool
mds/cluster_downPUTtake MDS cluster down
mds/cluster_upPUTbring MDS cluster up
mds/compat/rm_compat?feature=feature(<in
t[0-]>)PUTremove compatible feature
mds/compat/rm_incompat?feature=feature(<
int[0-]>)PUTremove incompatible feature
mds/compat/showGETshow mds compatibility settings
mds/deactivate?who=who()PUTstop mds
mds/dump?epoch={epoch(<int[0-]>)}GETdump info, optionally from epoch
mds/fail?who=who()PUTforce mds to status failed
mds/getmap?epoch={epoch(<int[0-]>)}GETget MDS map, optionally from epoch
mds/newfs?metadata=metadata(<int[0-]>)&d
ata=data(<int[0-]>)&sure={—yes-i
-really-mean-it}PUTmake new filesystom using poolsand
mds/remove_data_pool?pool=pool()PUTremove data pool
mds/rm?gid=gid(<int[0-]>)&who=who(<name
(type.id)>)PUTremove nonactive mds
mds/rmfailed?who=who(<int[0-]>)PUTremove failed mds
mds/set?key=allow_new_snaps&sure={sure(<
string>)}Unknownset
mds/set_max_mds?maxmds=maxmds(<int[0-]>)PUTset max MDS index
mds/set_state?gid=gid(<int[0-]>)&state=s
tate(<int[0-20]>)PUTset mds state ofto
mds/setmap?epoch=epoch(<int[0-]>)PUTset mds map; must supply correct epoch number
mds/statGETshow MDS status
mds/stop?who=who()PUTstop mds
mds/tell?who=who()&args=args(<st
ring>) […]PUTsend command to particular mds
mds/unset?key=allow_new_snaps&sure={sure
()}Unknownunset
mon/add?name=name()&addr=addr(<I
Paddr[:port]>)PUTadd new monitor namedat
mon/dump?epoch={epoch(<int[0-]>)}GETdump formatted monmap (optionally from epoch)
mon/getmap?epoch={epoch(<int[0-]>)}GETget monmap
mon/remove?name=name()PUTremove monitor named
mon/statGETsummarize monitor status
mon_statusGETreport status of monitors
osd/blacklist?blacklistop=blacklistop(ad
drm)&addr=addr()&expire={ex
pire(<float[0.0-]>)}PUTadd (optionally untilseconds from now) or removefrom blacklist
osd/blacklist/lsGETshow blacklisted clients
osd/create?uuid={uuid()}PUTcreate new osd (with optional UUID)
osd/crush/add?id=id(<osdname (idosd.id)
>)&weight=weight(<float[0.0-]>)&args=arg
s(<string(goodchars [A-Za-z0-9-_.=])>)
[<string(goodchars [A-Za-z0-9-_.=])>…]PUTadd or update crushmap position and weight forwithand location
osd/crush/add-
bucket?name=name(<string(goodchars
[A-Za-z0-9-_.])>)&type=type()PUTadd no-parent (probably root) crush bucketof type
osd/crush/create-or-move?id=id(<osdname
(idosd.id)>)&weight=weight(<float[0.0-]
>)&args=args(<string(goodchars
[A-Za-z0-9-_.=])>) [<string(goodchars
[A-Za-z0-9-_.=])>…]PUTcreate entry or move existing entry forat/to location
osd/crush/dumpGETdump crush map
osd/crush/link?name=name()&args=
args(<string(goodchars
[A-Za-z0-9-_.=])>) [<string(goodchars
[A-Za-z0-9-_.=])>…]PUTlink existing entry forunder location
osd/crush/move?name=name(<string(goodcha
rs [A-Za-z0-9-_.])>)&args=args(<string(g
oodchars [A-Za-z0-9-_.=])>)
[<string(goodchars [A-Za-z0-9-_.=])>…]PUTmove existing entry forto location
osd/crush/remove?name=name(<string(goodc
hars [A-Za-z0-9-_.])>)&ancestor={ancesto
r(<string(goodchars [A-Za-z0-9-_.])>)}PUTremovefrom crush map (everywhere, or just at
osd/crush/reweight?name=name(<string(goo
dchars [A-Za-z0-9-_.])>)&weight=weight(<
float[0.0-]>)PUTchange's weight toin crush map
osd/crush/rm?name=name(<string(goodchars
[A-Za-z0-9-_.])>)&ancestor={ancestor(<st
ring(goodchars [A-Za-z0-9-_.])>)}PUTremovefrom crush map (everywhere, or just at
osd/crush/rule/create-
simple?name=name(<string(goodchars [A-Za
-z0-9-_.])>)&root=root(<string(goodchars
[A-Za-z0-9-_.])>)&type=type(<string(good
chars [A-Za-z0-9-_.])>)PUTcreate crush ruleinof type
osd/crush/rule/dumpGETdump crush rules
osd/crush/rule/listGETlist crush rules
osd/crush/rule/lsGETlist crush rules
osd/crush/rule/rm?name=name(<string(good
chars [A-Za-z0-9-_.])>)PUTremove crush rule
osd/crush/setPUTset crush map from input file
osd/crush/set?id=id(<osdname (idosd.id)
>)&weight=weight(<float[0.0-]>)&args=arg
s(<string(goodchars [A-Za-z0-9-_.=])>)
[<string(goodchars [A-Za-z0-9-_.=])>…]PUTupdate crushmap position and weight fortowith location
osd/crush/tunables?profile=profile(legac
yargonautbobtail
osd/crush/unlink?name=name(<string(goodc
hars [A-Za-z0-9-_.])>)&ancestor={ancesto
r(<string(goodchars [A-Za-z0-9-_.])>)}PUTunlinkfrom crush map (everywhere, or just at
osd/deep-scrub?who=who()PUTinitiate deep scrub on osd
osd/down?ids=ids() […]PUTset osd(s)[…] down
osd/dump?epoch={epoch(<int[0-]>)}GETprint summary of OSD map
osd/find?id=id(<int[0-]>)GETfind osdin the CRUSH map and show its location
osd/getcrushmap?epoch={epoch(<int[0-]>)}GETget CRUSH map
osd/getmap?epoch={epoch(<int[0-]>)}GETget OSD map
osd/getmaxosdGETshow largest OSD id
osd/in?ids=ids() […]PUTset osd(s)[…] in
osd/lost?id=id(<int[0-]>)&sure={—yes-i
-really-mean-it}PUTmark osd as permanently lost. THIS DESTROYS DATA IF NO MORE REPLICAS EXIST, BE CAREFUL
osd/ls?epoch={epoch(<int[0-]>)}GETshow all OSD ids
osd/lspools?auid={auid()}GETlist pools
osd/map?pool=pool()&object=obj
ect()GETfind pg for in
osd/out?ids=ids() […]PUTset osd(s)[…] out
osd/pausePUTpause osd
osd/perfGETprint dump of OSD perf summary stats
osd/pool/create?pool=pool()&pg
_num=pg_num(<int[0-]>)&pgp_num={pgp_num(
<int[0-]>)}&properties={properties(<stri
ng(goodchars [A-Za-z0-9-_.=])>)
[<string(goodchars
[A-Za-z0-9-_.=])>…]}PUTcreate pool
osd/pool/delete?pool=pool()&po
ol2={pool2()}&sure={—yes-i
-really-really-mean-it}PUTdelete pool
osd/pool/get?pool=pool()&var=v
ar(sizemin_sizecrash_replay_interval
g_numpgp_numcrush_ruleset)
osd/pool/mksnap?pool=pool()&sn
ap=snap()PUTmake snapshotin
osd/pool/rename?srcpool=srcpool(<poolnam
e>)&destpool=destpool()PUTrenameto
osd/pool/rmsnap?pool=pool()&sn
ap=snap()PUTremove snapshotfrom
osd/pool/set?pool=pool()&var=v
ar(sizemin_sizecrash_replay_interval
g_numpgp_numcrush_ruleset
val=val()PUTset pool parameter to
osd/pool/set-quota?pool=pool()
&field=field(max_objectsmax_bytes)&val=
val()PUTset object or byte limit on pool
osd/pool/stats?name={name()}GETobtain stats from all pools, or from specified pool
osd/repair?who=who()PUTinitiate repair on osd
osd/reweight?id=id(<int[0-]>)&weight=wei
ght(<float[0.0-1.0]>)PUTreweight osd to 0.0 << 1.0
osd/reweight-by-
utilization?oload={oload(<int[100-]>)}PUTreweight OSDs by utilization [overload-percentage-for-consideration, default 120]
osd/rm?ids=ids() […]PUTremove osd(s)[…] in
osd/scrub?who=who()PUTinitiate scrub on osd
osd/set?key=key(pausenoupnodown
noinnobackfillnorecover
nodeep-scrub)PUTset
osd/setcrushmapPUTset crush map from input file
osd/setmaxosd?newmax=newmax(<int[0-]>)PUTset new maximum osd value
osd/statGETprint summary of OSD map
osd/thrash?num_epochs=num_epochs(<int[0-
]>)PUTthrash OSDs for <num_epochs>
osd/tier/add?pool=pool()&tierp
ool=tierpool()PUTadd the tierto base pool
osd/tier/cache-mode?pool=pool(
)&mode=mode(nonewritebackinvalidate+fo
rwardreadonly)PUT
osd/tier/remove?pool=pool()&ti
erpool=tierpool()PUTremove the tierfrom base pool
osd/tier/remove-
overlay?pool=pool()PUTremove the overlay pool for base pool
osd/tier/set-overlay?pool=pool(<poolname
>)&overlaypool=overlaypool()PUTset the overlay pool for base poolto be
osd/tree?epoch={epoch(<int[0-]>)}GETprint OSD tree
osd/unpausePUTunpause osd
osd/unset?key=key(pausenoupnodown
tnoinnobackfill
nodeep-scrub)PUTunset
pg/debug?debugop=debugop(unfound_objects
_existdegraded_pgs_exist)GET
pg/deep-scrub?pgid=pgid()PUTstart deep-scrub on
pg/dump?dumpcontents={dumpcontents(alls
ummarysumdelta
f) [allsummarysum
pgs_brief…]}GETshow human-readable versions of pg map (only 'all' valid with plain)
pg/dump_json?dumpcontents={dumpcontents(
allsummarysum
[allsummarysum
pg/dump_pools_jsonGETshow pg pools info in json only
pg/dump_stuck?stuckops={stuckops(inactiv
euncleanstale) [inactive
…]}&threshold={threshold()}GETshow information about stuck pgs
pg/force_create_pg?pgid=pgid()PUTforce creation of pg
pg/getmapGETget binary pg map to -o/stdout
pg/map?pgid=pgid()GETshow mapping of pg to osds
pg/repair?pgid=pgid()PUTstart repair on
pg/scrub?pgid=pgid()PUTstart scrub on
pg/send_pg_createsPUTtrigger pg creates to be issued
pg/set_full_ratio?ratio=ratio(<float[0.0
-1.0]>)PUTset ratio at which pgs are considered full
pg/set_nearfull_ratio?ratio=ratio(<float
[0.0-1.0]>)PUTset ratio at which pgs are considered nearly full
pg/statGETshow placement group status.
tell//queryGETshow details of a specific pg
tell//queryGETshow details of a specific pg
quorum?quorumcmd=quorumcmd(enterexit)PUT
quorum_statusGETreport status of monitor quorum
report?tags={tags()
[…]}GETreport full status of cluster, optional title tag strings
tell/<osdid-or-
pgid>/reset_pg_recovery_statsPUTreset pg recovery statistics
scrubPUTscrub the monitor stores
statusGETshow cluster status
sync/force?validate1={—yes-i-really-
mean-it}&validate2={—i-know-what-i-am-
doing}PUTforce sync of and clear monitor store
tell?target=target(<name
(type.id)>)&args=args()
[…]PUTsend a command to a specific daemon
tell//versionGETreport version of OSD

Enjoy !