Get started

This tutorial will guide you through your first steps with MicroCeph. You will use MicroCeph to deploy a Ceph cluster on a single node and to store a JPEG image, in a simple storage service (S3) bucket.

To do this, you will use the S3-compatible Ceph Object Gateway, or RADOS Gateway (RGW), to help you interact with your cluster, and s3cmd, a command line tool and client for uploading, retrieving and managing data in AWS S3 compatible storage systems.

Along the way, you will also interact with your cluster in other ways, such as checking the health status of your cluster, adding disks to it and, of course, enabling RGW on the cluster.

By the end of this tutorial, after having successfully used MicroCeph to store a graphical image, you will have a basic idea of how MicroCeph works, and you will be ready to start exploring more advanced use cases.

Requirements

You will need the following:

  • The latest Ubuntu LTS version. Find Ubuntu release information here.

  • 2 CPU cores

  • 4 GiB RAM

  • 12GiB disk space

  • An Internet connection

Install MicroCeph

First, install MicroCeph as a snap package from the Snap Store:

sudo snap install microceph

Disable the default automatic Snap upgrades to prevent MicroCeph from being auto-updated:

sudo snap refresh --hold microceph

Caution

Failing to set this option may lead undesired upgrades which can be fatal to your deployed cluster.

All subsequent MicroCeph upgrades must, then, be done manually.

Initialise your cluster

Next, bootstrap your new Ceph storage cluster:

sudo microceph cluster bootstrap

This process takes 3 to 5 seconds.

Check the status of the cluster:

sudo microceph status
MicroCeph deployment summary:- ubuntu (10.246.114.49) Services: mds, mgr, mon    Disks: 0

Your cluster deployment summary will include your node’s hostname, i.e. ubuntu and IP address, i.e. 10.246.114.49, along with information about the services running and storage available. Notice that we have a healthy cluster with one node and three services running, but no storage allocated yet.

Add storage

Let’s add storage disk devices to the node.

We will use loop files, which are file-backed object storage daemons (OSDs) convenient for setting up small test and development clusters. Three OSDs are required to form a minimal Ceph cluster.

sudo microceph disk add loop,4G,3
+-----------+---------+|   PATH    | STATUS  |+-----------+---------+| loop,4G,3 | Success |+-----------+---------+

Success! You have added three OSDs with 4GiB storage to your node.

Recheck the status of the cluster:

sudo microceph status
MicroCeph deployment summary:- ubuntu (10.246.114.49)Services: mds, mgr, mon, osdDisks: 3

You have successfully deployed a Ceph cluster on a single node. Remember that we had three services running upon bootstrapping the cluster. Note that we now have four services running, including a new osd service.

Enable RGW

As mentioned before, we will use the Ceph Object Gateway as a way to interact with the object storage cluster we just deployed.

Enable the RGW daemon on your node

sudo microceph enable rgw

Note

By default, the rgw service uses port 80, which is not always available. If you don’t have port 80 free, you can set an alternative port number, say 8080, by adding the --port <port-number> parameter.

Another status check will show the rgw service reflected in the status output.

sudo microceph status
MicroCeph deployment summary:- ubuntu (10.246.114.49)Services: mds, mgr, mon, rgw, osdDisks: 3

Create an RGW user

MicroCeph is packaged with the standard radosgw-admin tool that manages the rgw service and users. We will now use this tool to create an RGW user called user, with the display name user.

sudo radosgw-admin user create --uid=user --display-name=user

The output should include user details as shown below, with auto-generated access and secret keys.

{"user_id": "user","display_name": "user","email": "","suspended": 0,"max_buckets": 1000,"subusers": [],"keys": [    {        "user": "user",        "access_key": "NJ7YZ3LYI45M4Q1A08OS",        "secret_key": "H7OTclVbZIwhd2o0NLPu0D7Ass8ouSKmtSewuYwK",        "active": true,        "create_date": "2024-11-28T13:07:41.561437Z"    }],...

Set user secrets

Let’s set some secrets the user created, giving access_key the value foo, and --secret-key the value bar.

sudo radosgw-admin key create --uid=user --key-type=s3 --access-key=foo --secret-key=bar
... [     {         "user": "user",         "access_key": "NJ7YZ3LYI45M4Q1A08OS",         "secret_key": "H7OTclVbZIwhd2o0NLPu0D7Ass8ouSKmtSewuYwK",         "active": true,         "create_date": "2024-11-28T13:07:41.561437Z"     },     {         "user": "user",         "access_key": "foo",         "secret_key": "bar",         "active": true,         "create_date": "2024-11-28T13:54:36.065214Z"     } ],...

Consuming the storage

Access RGW

Before attempting to consume the object storage in the cluster, validate that you can access RGW by running curl on your node.

Find the IP address of the node running the rgw service:

sudo microceph status
MicroCeph deployment summary:- ubuntu (10.246.114.49)Services: mds, mgr, mon, rgw, osdDisks: 3

Then, run curl from this node.

curl http://10.246.114.49
<?xml version="1.0" encoding="UTF-8"?><ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Owner><ID>anonymous</ID></Owner><Buckets></Bucket

Create an S3 bucket

You have verified that your cluster is accessible via RGW. Now, let’s create a bucket using the s3cmd tool:

s3cmd mb -P s3://mybucket

Note

The -P flag ensures that the bucket is publicly visible, enabling you to access stored objects easily via a public URL.

Bucket 's3://mybucket/' created

Our bucket is successfully created.

Upload an image into the bucket

s3cmd put -P image.jpg s3://mybucket
upload: 'image.jpg' -> 's3://mybucket/image.jpg'  [1 of 1]66565 of 66565   100% in    0s     4.52 MB/s  donePublic URL of the object is: http://ubuntu/mybucket/image.jpg

You have stored your image in a publicly visible S3 bucket. You may now click on the public object URL given in the output to view it in your browser.

Cleaning up resources

In case, for any reason, you want to get rid of MicroCeph, you can purge the snap from your machine this way:

sudo snap remove microceph --purge

This command stops all the services running, and removes the MicroCeph snap along with your cluster and all the resources contained in it.

Note

Note: the --purge flag will remove all MicroCeph persistent state, .

The --purge flag will remove all the files associated with the MicroCeph package, i.e. it will remove the MicroCeph snap without saving a snapshot of its data. Running the command without this flag will not remove MicroCeph completely - the persistent state will still be there.

Tip

Skipping the purge option is useful if you intend to re-install MicroCeph, or move your configuration to a different system.

2024-11-28T19:44:29+03:00 INFO Waiting for "snap.microceph.rgw.service" to stop.2024-11-28T19:45:00+03:00 INFO Waiting for "snap.microceph.mds.service" to stop.microceph removed

Next steps

You have deployed a healthy Ceph cluster on a single-node and enabled RGW on it. Even better, you have consumed the storage in that cluster by creating a bucket and storing an object in it. Curious to see what else you can do with MicroCeph?

See our how-to guides, packed with instructions to help you achieve specific goals with MicroCeph.

Or, explore our Explanation and Reference sections for additional information and quick references.