If you have a running Ceph Object Storage cluster in production, you may need the RESTful API for administration, integration with other systems and monitoring. The RESTful API plugin for the Ceph Manager (ceph-mgr) provides an API for interacting with your Ceph Storage cluster.
In this guide we will show you how to enable the RESTful API access on Ceph Storage cluster and creation of user for any integrations that you’ll need. Before you continue, ensure you have a working Ceph Storage Cluster. Below guides can be used as reference for small setup, not for serious production workloads.
Install Ceph 15 (Octopus) Cluster on CentOS 8
How To Install Ceph Storage Cluster on Ubuntu 18.04
The Ceph REST API allows you 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
- Among many other operations
Step 1: Enable RESTful API MGR Plugin
The Ceph Manager daemon (ceph-mgr) runs alongside monitor daemons, to provide additional monitoring and interfaces to external monitoring and management systems. We will enable the Ceph REST Plugin in MGR.
Login to your Ceph Cluster node with ceph configurations done correctly and run the following command to enable RESTful API plugin.
# ceph mgr module enable restful
To see all available modules status, use the command:
# ceph mgr module ls
From UI:
Step 2: Configure SSL certificate for the API endpoint
The module will accept HTTPS requests on port 8003 on all IPv4 and IPv6 addresses on the host where mgr is running. This is the default setting unless you set it otherwise. Before the API endpoint is available, you will need to configure an SSL certificate.
If you don’t have a valid certificate signed by your company, generate a self-signed certificate with the command:
# ceph restful create-self-signed-cert
The service will be started automatically after the configuration is updated. To confirm it is working fine, use curl command to test on the active MGR node.
# curl -k https://localhost:8003/
{
"api_version": 1,
"auth": "Use "ceph restful create-key " to create a key pair, pass it as HTTP Basic auth to authenticate",
"doc": "See /doc endpoint",
"info": "Ceph Manager RESTful API server"
If you use a firewall, ensure that the 8003 port is enabled on the node with the active ceph-mgr daemon. Confirm with:
# ceph -s
# firewall-cmd --add-port=5000/tcp --permanent
# firewall-cmd --reload
If you have well signed certificates, apply them using the commands:
ceph config-key set mgr/restful/crt -i restful.crt
ceph config-key set mgr/restful/key -i restful.key
Where:
- restful.crt is the name of the certificate to apply
- restful.key is the name of the key used with the certificate
Step 3: Create an API HTTP user with basic authentication
A user is needed for API access. Let’s create an HTTP user and generate a password for HTTP basic authentication.
The command syntax is:
# ceph restful create-key
I’ll create a user called cephadmin
# ceph restful create-key cephadmin
1c4dcb01-587b-4558-8878-1209b525de8c
You can always check the username and key using the following command:
# ceph restful list-keys
{
"cephadmin": "1c4dcb01-587b-4558-8878-1209b525de8c"
}
Once the credentials are generated, you can use curl to validate API access. The command syntax is:
https://:@:/
Here is an example:
# curl -k https://cephadmin:[email protected]:8003/server
[
{
"ceph_version": "ceph version 14.2.7 (3d58626ebeec02d8385a4cefb92c6cbc3a45bfe8) nautilus (stable)",
"hostname": "cephmon01.example.com",
"services": [
{
"id": "cephmon01",
"type": "mgr"
},
{
"id": "cephmon02",
"type": "mon"
},
{
"id": "cephmon03",
"type": "rgw"
}
]
},
..........
# url -k https://cephadmin:[email protected]:8003/config/osd
[
"sortbitwise",
"recovery_deletes",
"purged_snapdirs",
"pglog_hardlimit"
Reference: