1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
Restful Module
==============
RESTful module offers the REST API access to the status of the cluster
over an SSL-secured connection.
Enabling
--------
The *restful* module is enabled with::
ceph mgr module enable restful
You will also need to configure an SSL certificate below before the
API endpoint is available. By default the module will accept HTTPS
requests on port ``8003`` on all IPv4 and IPv6 addresses on the host.
Securing
--------
All connections to *restful* are secured with SSL. You can generate a
self-signed certificate with the command::
ceph restful create-self-signed-cert
Note that with a self-signed certificate most clients will need a flag
to allow a connection and/or suppress warning messages. For example,
if the ``ceph-mgr`` daemon is on the same host,::
curl -k https://localhost:8003/
To properly secure a deployment, a certificate that is signed by the
organization's certificate authority should be used. For example, a key pair
can be generated with a command similar to::
openssl req -new -nodes -x509 \
-subj "/O=IT/CN=ceph-mgr-restful" \
-days 3650 -keyout restful.key -out restful.crt -extensions v3_ca
The ``restful.crt`` should then be signed by your organization's CA
(certificate authority). Once that is done, you can set it with::
ceph config-key set mgr/restful/$name/crt -i restful.crt
ceph config-key set mgr/restful/$name/key -i restful.key
where ``$name`` is the name of the ``ceph-mgr`` instance (usually the
hostname). If all manager instances are to share the same certificate,
you can leave off the ``$name`` portion::
ceph config-key set mgr/restful/crt -i restful.crt
ceph config-key set mgr/restful/key -i restful.key
Configuring IP and port
-----------------------
Like any other RESTful API endpoint, *restful* binds to an IP and
port. By default, the currently active ``ceph-mgr`` daemon will bind
to port 8003 and any available IPv4 or IPv6 address on the host.
Since each ``ceph-mgr`` hosts its own instance of *restful*, it may
also be necessary to configure them separately. The IP and port
can be changed via the configuration key facility::
ceph config set mgr mgr/restful/$name/server_addr $IP
ceph config set mgr mgr/restful/$name/server_port $PORT
where ``$name`` is the ID of the ceph-mgr daemon (usually the hostname).
These settings can also be configured cluster-wide and not manager
specific. For example,::
ceph config set mgr mgr/restful/server_addr $IP
ceph config set mgr mgr/restful/server_port $PORT
If the port is not configured, *restful* will bind to port ``8003``.
If the address it not configured, the *restful* will bind to ``::``,
which corresponds to all available IPv4 and IPv6 addresses.
.. _creating-an-api-user:
Creating an API User
-----------------------
To create an API user, please run the following command::
ceph restful create-key <username>
Replace ``<username>`` with the desired name of the user. For example, to create a user named
``api``::
$ ceph restful create-key api
52dffd92-a103-4a10-bfce-5b60f48f764e
The UUID generated from ``ceph restful create-key api`` acts as the key for the user.
To list all of your API keys, please run the following command::
ceph restful list-keys
The ``ceph restful list-keys`` command will output in JSON::
{
"api": "52dffd92-a103-4a10-bfce-5b60f48f764e"
}
You can use ``curl`` in order to test your user with the API. Here is an example::
curl -k https://api:52dffd92-a103-4a10-bfce-5b60f48f764e@<ceph-mgr>:<port>/server
In the case above, we are using ``GET`` to fetch information from the ``server`` endpoint.
Load balancer
-------------
Please note that *restful* will *only* start on the manager which
is active at that moment. Query the Ceph cluster status to see which
manager is active (e.g., ``ceph mgr dump``). In order to make the
API available via a consistent URL regardless of which manager
daemon is currently active, you may want to set up a load balancer
front-end to direct traffic to whichever manager endpoint is
available.
Available methods
-----------------
You can navigate to the ``/doc`` endpoint for full list of available
endpoints and HTTP methods implemented for each endpoint.
For example, if you want to use the PATCH method of the ``/osd/<id>``
endpoint to set the state ``up`` of the OSD id ``1``, you can use the
following curl command::
echo -En '{"up": true}' | curl --request PATCH --data @- --silent --insecure --user <user> 'https://<ceph-mgr>:<port>/osd/1'
or you can use python to do so::
$ python
>> import requests
>> result = requests.patch(
'https://<ceph-mgr>:<port>/osd/1',
json={"up": True},
auth=("<user>", "<password>")
)
>> print result.json()
Some of the other endpoints implemented in the *restful* module include
* ``/config/cluster``: **GET**
* ``/config/osd``: **GET**, **PATCH**
* ``/crush/rule``: **GET**
* ``/mon``: **GET**
* ``/osd``: **GET**
* ``/pool``: **GET**, **POST**
* ``/pool/<arg>``: **DELETE**, **GET**, **PATCH**
* ``/request``: **DELETE**, **GET**, **POST**
* ``/request/<arg>``: **DELETE**, **GET**
* ``/server``: **GET**
The ``/request`` endpoint
-------------------------
You can use the ``/request`` endpoint to poll the state of a request
you scheduled with any **DELETE**, **POST** or **PATCH** method. These
methods are by default asynchronous since it may take longer for them
to finish execution. You can modify this behaviour by appending
``?wait=1`` to the request url. The returned request will then always
be completed.
The **POST** method of the ``/request`` method provides a passthrough
for the ceph mon commands as defined in ``src/mon/MonCommands.h``.
Let's consider the following command::
COMMAND("osd ls " \
"name=epoch,type=CephInt,range=0,req=false", \
"show all OSD ids", "osd", "r", "cli,rest")
The **prefix** is **osd ls**. The optional argument's name is **epoch**
and it is of type ``CephInt``, i.e. ``integer``. This means that you
need to do the following **POST** request to schedule the command::
$ python
>> import requests
>> result = requests.post(
'https://<ceph-mgr>:<port>/request',
json={'prefix': 'osd ls', 'epoch': 0},
auth=("<user>", "<password>")
)
>> print result.json()
|
