Skip to content

Commit

Permalink
Add MicroCeph tutorial (#478)
Browse files Browse the repository at this point in the history
# Description

We currently do not have a tutorial for new users in the MicroCeph
documentation. The how-to section of our documentation would be useful
for a user who is already familiar with Ceph and is looking to achieve
certain goals with MicroCeph. But, a new user with no prior knowledge of
Ceph would find it difficult to get started with MicroCeph, which is
intended to make their experience as easy as possible.

This is, hopefully, a complete, end-to-end tutorial intended to serve as
an entry point into Ceph for a new user, setting them up for their next
steps, whether it is to use MicroCeph to accomplish certain tasks in
their work (how-to guides), learn more about MicroCeph (explanation) or
make quick references.


## Type of change

- [x] Documentation update (Doc only change)

---------

Signed-off-by: Sharon Koech <[email protected]>
  • Loading branch information
skoech authored Dec 11, 2024
1 parent 332b8ce commit e3f972b
Show file tree
Hide file tree
Showing 4 changed files with 388 additions and 2 deletions.
2 changes: 1 addition & 1 deletion docs/.custom_wordlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ config
IPv
cfg
CFG

LTS
MicroCeph
microceph
OSDs
Expand Down
7 changes: 6 additions & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,11 @@ to Ceph administrators and storage software developers.
In this documentation
---------------------

.. grid:: 1 1 1 1
.. grid:: 1 2 1 2

.. grid-item:: :doc:`Tutorial <tutorial/index>`

**A hands-on introduction** to MicroCeph for new users

.. grid-item:: :doc:`How-to guides <how-to/index>`

Expand Down Expand Up @@ -59,6 +63,7 @@ constructive feedback.
:hidden:
:maxdepth: 2

tutorial/index
how-to/index
reference/index
explanation/index
Expand Down
362 changes: 362 additions & 0 deletions docs/tutorial/get-started.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,362 @@
First steps with MicroCeph
==========================

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
for interacting with MicroCeph RGW, allowing users to access Ceph object storage capabilities using familiar AWS S3 commands.

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

.. LINKS
.. _here: https://ubuntu.com/about/release-cycle

Install MicroCeph
-----------------

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

.. code-block:: none
sudo snap install microceph
- *Disable this feature to prevent MicroCeph from being auto-updated:*

.. code-block:: none
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:*

.. code-block:: none
sudo microceph cluster bootstrap
This process takes 3 to 5 seconds.

- *Check the status of the cluster:*

.. code-block:: none
sudo microceph status
.. terminal::

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, 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.

.. code-block:: none
sudo microceph disk add loop,4G,3
.. terminal::

+-----------+---------+
| PATH | STATUS |
+-----------+---------+
| loop,4G,3 | Success |
+-----------+---------+

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

- *Recheck the status of the cluster:*

.. code-block:: none
sudo microceph status
.. terminal::
MicroCeph deployment summary:
- ubuntu (10.246.114.49)
Services: mds, mgr, mon, osd
Disks: 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:*

.. code-block:: none
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 :file:`--port <port-number>` parameter.


- *Recheck status*

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

.. code-block:: none
sudo microceph status
.. terminal::

MicroCeph deployment summary:
- ubuntu (10.246.114.49)
Services: mds, mgr, mon, rgw, osd
Disks: 3

MicroCeph is packaged with the standard ``radosgw-admin`` tool that manages the ``rgw`` service and users. We
will now use this tool to create a RGW user and set secrets on it.

- *Create a RGW user:*

.. code-block:: none
sudo radosgw-admin user create --uid=user --display-name=user
The output should look something like this:

.. terminal::

{
"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"
}
],
"swift_keys": [],
"caps": [],
"op_mask": "read, write, delete",
"default_placement": "",
"default_storage_class": "",
"placement_tags": [],
"bucket_quota": {
"enabled": false,
"check_on_raw": false,
"max_size": -1,
"max_size_kb": 0,
"max_objects": -1
},
"user_quota": {
"enabled": false,
"check_on_raw": false,
"max_size": -1,
"max_size_kb": 0,
"max_objects": -1
},
"temp_url_keys": [],
"type": "rgw",
"mfa_ids": [],
"account_id": "",
"path": "/",
"create_date": "2024-11-28T13:07:41.561217Z",
"tags": [],
"group_ids": []

- *Set user secrets:*

.. code-block:: none
sudo radosgw-admin key create --uid=user --key-type=s3 --access-key=foo --secret-key=bar
.. terminal::

{
"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"
},
{
"user": "user",
"access_key": "foo",
"secret_key": "bar",
"active": true,
"create_date": "2024-11-28T13:54:36.065214Z"
}
],
"swift_keys": [],
"caps": [],
"op_mask": "read, write, delete",
"default_placement": "",
"default_storage_class": "",
"placement_tags": [],
"bucket_quota": {
"enabled": false,
"check_on_raw": false,
"max_size": -1,
"max_size_kb": 0,
"max_objects": -1
},
"user_quota": {
"enabled": false,
"check_on_raw": false,
"max_size": -1,
"max_size_kb": 0,
"max_objects": -1
},
"temp_url_keys": [],
"type": "rgw",
"mfa_ids": [],
"account_id": "",
"path": "/",
"create_date": "2024-11-28T13:07:41.561217Z",
"tags": [],
"group_ids": []

Consuming the storage
---------------------

Access RGW
~~~~~~~~~~

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

- *Find the IP address of the node running the ``rgw`` service:*

.. code-block:: none
sudo microceph status
.. terminal::

MicroCeph deployment summary:
- ubuntu (10.246.114.49)
Services: mds, mgr, mon, rgw, osd
Disks: 3

- *Run* :command:`curl` *from this node:*

.. code-block:: none
curl http://10.246.114.49
.. terminal::

<?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:

.. code-block:: none
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.

.. terminal::

Bucket 's3://mybucket/' created

Our bucket is successfully created.

- *Let's upload an image into it:*

.. code-block:: none
s3cmd put -P image.jpg s3://mybucket
.. terminal::

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

Great work! 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:

.. code-block:: none
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::

The ``--purge`` option removes all the files associated with the MicroCeph package, and will also skip generating a snapshot of the package's
running state. Skipping the :command:`purge` option is useful if you intend to re-install MicroCeph, or move your configuration to a different system.


.. terminal::

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 :doc:`how-to guides <../how-to/index>`, packed with instructions to help you achieve specific goals with MicroCeph.

Or, explore our :doc:`Explanation <../explanation/index>` and
:doc:`Reference <../reference/index>` sections for additional information and quick references.
Loading

0 comments on commit e3f972b

Please sign in to comment.