Chapter 1. RESTful Plug-in

1.1. What is the RESTful Plug-in?

The RESTful plug-in for the Ceph Manager (ceph-mgr) provides an API for interacting with a Red Hat Ceph Storage cluster.

You can use the API to:

  • Show the information about Monitors and OSDs
  • Create or edit pools
  • View and start scheduled processes on OSDs
  • Show configuration options for the cluster, Monitor, and OSDs

1.2. Enabling and Securing the RESTful plug-in

The RESTful plug-in offers the REST API access to the status of the cluster over an SSL-secured connection. This section describes how to enable the plug-in and secure it.

Prerequisites

  • Ensure that you have at least one ceph-mgr daemon active. See the Installing a Red Hat Ceph Storage section in the Installation Guide for Red Hat Enterprise Linux or Ubuntu.
  • If you use a firewall, ensure that the 8003 port is enabled on the node with the active ceph-mgr daemon.

Procedure

Use the following commands on a node with the administration keyring.

  1. Enable the RESTful plug-in. 

    [root@admin ~]# ceph mgr module enable restful

  2. Configure an SSL certificate.

    1. If your organization’s certificate authority provides a certificate, set the certificate: 

      ceph config-key set mgr/restful/<hostname>/crt -i <certificate>
ceph config-key set mgr/restful/<hostname>/key -i <key>

      Replace <hostname> with the host name of the host where the active ceph-mgr instance is running, <certificate> with the path to the certificate file, and <key> with the path to the key file, for example: 

      [root@admin ~]# ceph config-key set mgr/restful/node1/crt -i restful.crt
[root@admin ~]# ceph config-key set mgr/restful/node1/key -i restful.key

      If you want to use the certificate on all ceph-mgr instances, omit the <hostname> part, for example: 

      [root@admin ~]# ceph config-key set mgr/restful/crt -i restful.crt
[root@admin ~]# ceph config-key set mgr/restful/key -i restful.key

    2. Alternatively, generate a self-signed certificate. However, using a self-signed certificate does not provide full security benefits of the HTTPS protocol. 

      [root@admin ~]# ceph restful create-self-signed-cert

  3. Create an HTTP user and generate a password for HTTP basic authentication. 

    ceph restful create-key <username>

    Replace <username> with name of the user. For example, to create a user named admin: 

    [root@admin ~]# ceph restful create-key admin
3ce361b7-97fb-4820-8edc-1090841f078e

  4. Connect to the RESTful plug-in web page. Open a web browser and enter the following URL: 

    https://<ceph-mgr>:8003

    Replace <ceph-mgr> with the IP address or host name of the node with the active ceph-mgr daemon: 

    https://node1:8003

    If you used a self-signed certificate, confirm a security exception.

  5. Optional. If you want to use a static IP address for the RESTful plug-in, configure a load balancer.

Additional Resources

  • The ceph restful --help command
  • The https://<ceph-mgr>:8003/doc page, where <ceph-mgr> is the IP address or host name of the node with the running ceph-mgr instance
  • The Using OpenSSL chapter in the Security Guide for Red Hat Enterprise Linux 7