diff --git a/docs/index.rst b/docs/index.rst index 3124efd4..884b7340 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,7 +24,7 @@ In this documentation .. grid:: 1 2 1 2 - .. grid-item:: :doc:`Tutorial ` + .. grid-item:: :doc:`Get Started ` **A hands-on introduction** to MicroCeph for new users diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 674bf77f..e3e83bfc 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -1,5 +1,5 @@ -Tutorial --------- +Get Started 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. @@ -13,7 +13,356 @@ 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 ` 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:: + + anonymous '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. +======= .. toctree:: :maxdepth: 1 - get-started \ No newline at end of file + get-started + \ No newline at end of file