]>
Commit | Line | Data |
---|---|---|
31f18b77 FG |
1 | restful plugin |
2 | ============== | |
3 | ||
224ce89b WB |
4 | RESTful plugin offers the REST API access to the status of the cluster |
5 | over an SSL-secured connection. | |
6 | ||
7 | Enabling | |
8 | -------- | |
9 | ||
10 | The *restful* module is enabled with:: | |
11 | ||
12 | ceph mgr module enable restful | |
13 | ||
14 | You will also need to configure an SSL certificate below before the | |
15 | API endpoint is available. By default the module will accept HTTPS | |
16 | requests on port ``8003`` on all IPv4 and IPv6 addresses on the host. | |
17 | ||
18 | Securing | |
19 | -------- | |
20 | ||
21 | All connections to *restful* are secured with SSL. You can generate a | |
22 | self-signed certificate with the command:: | |
23 | ||
24 | ceph restful create-self-signed-cert | |
25 | ||
26 | Note that with a self-signed certificate most clients will need a flag | |
27 | to allow a connection and/or suppress warning messages. For example, | |
28 | if the ``ceph-mgr`` daemon is on the same host,:: | |
29 | ||
30 | curl -k https://localhost:8003/ | |
31 | ||
32 | To properly secure a deployment, a certificate that is signed by the | |
33 | organization's certificate authority should be used. For example, a key pair | |
34 | can be generated with a command similar to:: | |
31f18b77 FG |
35 | |
36 | openssl req -new -nodes -x509 \ | |
37 | -subj "/O=IT/CN=ceph-mgr-restful" \ | |
224ce89b | 38 | -days 3650 -keyout restful.key -out restful.crt -extensions v3_ca |
31f18b77 | 39 | |
224ce89b WB |
40 | The ``restful.crt`` should then be signed by your organization's CA |
41 | (certificate authority). Once that is done, you can set it with:: | |
31f18b77 | 42 | |
224ce89b WB |
43 | ceph config-key put mgr/restful/$name/crt -i restful.crt |
44 | ceph config-key put mgr/restful/$name/key -i restful.key | |
31f18b77 | 45 | |
224ce89b WB |
46 | where ``$name`` is the name of the ``ceph-mgr`` instance (usually the |
47 | hostname). If all manager instances are to share the same certificate, | |
48 | you can leave off the ``$name`` portion:: | |
49 | ||
50 | ceph config-key put mgr/restful/crt -i restful.crt | |
51 | ceph config-key put mgr/restful/key -i restful.key | |
52 | ||
53 | ||
54 | Configuring IP and port | |
55 | ----------------------- | |
56 | ||
57 | Like any other RESTful API endpoint, *restful* binds to an IP and | |
58 | port. By default, the currently active ``ceph-mgr`` daemon will bind | |
59 | to port 8003 and any available IPv4 or IPv6 address on the host. | |
60 | ||
61 | Since each ``ceph-mgr`` hosts its own instance of *restful*, it may | |
62 | also be necessary to configure them separately. The IP and port | |
63 | can be changed via the configuration key facility:: | |
31f18b77 FG |
64 | |
65 | ceph config-key put mgr/restful/$name/server_addr $IP | |
66 | ceph config-key put mgr/restful/$name/server_port $PORT | |
67 | ||
224ce89b WB |
68 | where ``$name`` is the ID of the ceph-mgr daemon (usually the hostname). |
69 | ||
70 | These settings can also be configured cluster-wide and not manager | |
71 | specific. For example,:: | |
72 | ||
73 | ceph config-key put mgr/restful/server_addr $IP | |
74 | ceph config-key put mgr/restful/server_port $PORT | |
75 | ||
76 | If the port is not configured, *restful* will bind to port ``8003``. | |
77 | If the address it not configured, the *restful* will bind to ``::``, | |
78 | which corresponds to all available IPv4 and IPv6 addresses. | |
79 | ||
80 | Load balancer | |
81 | ------------- | |
82 | ||
83 | Please note that *restful* will *only* start on the manager which | |
84 | is active at that moment. Query the Ceph cluster status to see which | |
85 | manager is active (e.g., ``ceph mgr dump``). In order to make the | |
86 | API available via a consistent URL regardless of which manager | |
87 | daemon is currently active, you may want to set up a load balancer | |
88 | front-end to direct traffic to whichever manager endpoint is | |
89 | available. |