From 02a55d3b7f36d2a05de39575f30d2838873d4f78 Mon Sep 17 00:00:00 2001 From: Sage Weil Date: Tue, 11 Jul 2017 14:37:04 -0400 Subject: [PATCH] doc/mgr/restful: update Signed-off-by: Sage Weil --- doc/mgr/restful.rst | 88 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 76 insertions(+), 12 deletions(-) diff --git a/doc/mgr/restful.rst b/doc/mgr/restful.rst index 846c98840de..4dc33d723bb 100644 --- a/doc/mgr/restful.rst +++ b/doc/mgr/restful.rst @@ -1,25 +1,89 @@ restful plugin ============== -RESTful plugin offers the REST API access to the status of the cluster. RESTful -plugin enables you to secure the API endpoints via SSL. If you don't have a -security certificate and key already, you need to create them first:: +RESTful plugin 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 $PKEY -out $CERT -extensions v3_ca + -days 3650 -keyout restful.key -out restful.crt -extensions v3_ca -where ``$PKEY`` and ``$CERT`` are the paths to the private key and the -certificate. And then you need to import the keystore to the cluster using the -configuration key facility, so RESTful plugin can read them at startup:: +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 put mgr/restful/$name/crt -i $CERT - ceph config-key put mgr/restful/$name/key -i $PKEY + ceph config-key put mgr/restful/$name/crt -i restful.crt + ceph config-key put mgr/restful/$name/key -i restful.key -Also, like other web applications, RESTful plugin is bound to the a hostname and -a port:: +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 put mgr/restful/crt -i restful.crt + ceph config-key put 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-key put mgr/restful/$name/server_addr $IP ceph config-key put mgr/restful/$name/server_port $PORT -If not specified, the plugin uses ``127.0.0.1:8003`` by default. +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-key put mgr/restful/server_addr $IP + ceph config-key put 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. + +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. -- 2.39.5