From db7722e777815f9e25d3813e297794cb3ff0226c Mon Sep 17 00:00:00 2001 From: Ville Ojamo <14869000+bluikko@users.noreply.github.com> Date: Wed, 30 Apr 2025 14:37:57 +0700 Subject: [PATCH] doc/radosgw: Improve language, capitalization and use config database Use "RADOS Gateway" instead of "Rados Gateway", "rados gateway" etc. I am aware of the term "Ceph Object Gateway" but this change intends to be an uncontroversial low hanging fruit fix of obviously incorrectly capitalized terms. Use "RGW daemon" instead of "Gateway", "Rados Gateway" etc. Use "RGW instance" instead of "rados gateway" for consistency with exactly similar other instance. If referring obviously clearly to an instance of the daemon with an obviously not preferred term, change it to "RGW daemon"; for example when talking about restarting the RGW. Do not touch other instances that are not 100% clear. The files touched mostly do not use "Ceph Object Gateway" so changing the term to it would create inconsistency, or several more changes would need to be done to update all instances to use this terminology. Use configuration database instead of ceph.conf in d3n_datacache.rst. Improve language in d3n_datacache.rst. Signed-off-by: Ville Ojamo <14869000+bluikko@users.noreply.github.com> --- doc/radosgw/admin.rst | 2 +- doc/radosgw/d3n_datacache.rst | 42 ++++++++++++++++++++--------------- doc/radosgw/layout.rst | 2 +- doc/radosgw/lua-scripting.rst | 2 +- doc/radosgw/rgw-cache.rst | 2 +- 5 files changed, 28 insertions(+), 22 deletions(-) diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst index feb09731721..5c52aef6d5d 100644 --- a/doc/radosgw/admin.rst +++ b/doc/radosgw/admin.rst @@ -862,7 +862,7 @@ all unauthenticated users: .. note:: In a multisite configuration where a realm and a period are present, any changes to the global rate limit must be committed using ``period update - --commit``. If no period is present, the rados gateway(s) must be restarted + --commit``. If no period is present, the RGW instances must be restarted for the changes to take effect. Usage diff --git a/doc/radosgw/d3n_datacache.rst b/doc/radosgw/d3n_datacache.rst index 50871b1231e..477323271aa 100644 --- a/doc/radosgw/d3n_datacache.rst +++ b/doc/radosgw/d3n_datacache.rst @@ -7,7 +7,7 @@ D3N RGW Data Cache Datacenter-Data-Delivery Network (D3N) uses high-speed storage such as NVMe flash or DRAM to cache datasets on the access side. Such caching allows big data jobs to use the compute and fast storage resources available on each -Rados Gateway node at the edge. +RADOS Gateway (RGW) node at the edge. Many datacenters include low-cost, centralized storage repositories, called data lakes, to store and share terabyte and petabyte-scale datasets. @@ -17,7 +17,7 @@ Even with a well-designed datacenter network, cluster-to-data lake bandwidth is than the bandwidth of a solid-state storage located at an edge node. | D3N improves the performance of big-data jobs running in analysis clusters by speeding up recurring reads from the data lake. -| The Rados Gateways act as cache servers for the back-end object store (OSDs), storing data locally for reuse. +| The RADOS Gateways act as cache servers for the back-end object store (OSDs), storing data locally for reuse. Architecture ============ @@ -31,7 +31,7 @@ The layer 1 cache server nearest to the client handles object requests by breaki returning any blocks which are cached locally, and forwarding missed requests to the block home location (as determined by consistent hashing) in the next layer. Cache misses are forwarded to successive logical caching layers until a miss at the top layer is resolved -by a request to the data lake (Rados) +by a request to the data lake (RADOS) :sup:`*` currently only layer 1 cache has been upstreamed. @@ -68,19 +68,23 @@ D3N Environment Setup Running ------- -To enable D3N on an existing RGWs the following configuration entries are required -in each Rados Gateways ceph.conf client section, for example for ``[client.rgw.8000]``:: +To enable D3N on existing RGWs the following configuration entries are required +in the :ref:`ceph-conf-database`, for example for ``client.rgw.8000``: - [client.rgw.8000] - rgw_d3n_l1_local_datacache_enabled = true - rgw_d3n_l1_datacache_persistent_path = "/mnt/nvme0/rgw_datacache/client.rgw.8000/" - rgw_d3n_l1_datacache_size = 10737418240 +.. prompt:: bash # + + ceph config set client.rgw.8000 rgw_d3n_l1_local_datacache_enabled true + ceph config set client.rgw.8000 rgw_d3n_l1_datacache_persistent_path /mnt/nvme0/rgw_datacache/client.rgw.8000/ + ceph config set client.rgw.8000 rgw_d3n_l1_datacache_size 10737418240 The above example assumes that the cache backing-store solid state device is mounted at ``/mnt/nvme0`` and has 10 GB of free space available for the cache. -The persistent path directory has to be created before starting the Gateway. -(``mkdir -p /mnt/nvme0/rgw_datacache/client.rgw.8000/``) +The directory must exist and be writable before starting the RGW daemon: + +.. prompt:: bash # + + mkdir -p /mnt/nvme0/rgw_datacache/client.rgw.8000/ In containerized deployments the cache directory should be mounted as a volume:: @@ -90,15 +94,17 @@ In containerized deployments the cache directory should be mounted as a volume:: (Reference: `Service Management - Mounting Files with Extra Container Arguments`_) -If another Gateway is co-located on the same machine, configure it's persistent path to a discrete directory, -for example in the case of ``[client.rgw.8001]`` configure -``rgw_d3n_l1_datacache_persistent_path = "/mnt/nvme0/rgw_datacache/client.rgw.8001/"`` -in the ``[client.rgw.8001]`` ``ceph.conf`` client section. +If another RADOS Gateway is co-located on the same host, configure its persistent +path to a discrete directory, for example in the case of ``client.rgw.8001``: + +.. prompt:: bash # + + ceph config set client.rgw.8001 rgw_d3n_l1_datacache_persistent_path /mnt/nvme0/rgw_datacache/client.rgw.8001/ -In a multiple co-located Gateways configuration consider assigning clients with different workloads -to each Gateway without a balancer in order to avoid cached data duplication. +In a multiple co-located RADOS Gateways configuration consider assigning clients with different workloads +to each RADOS Gateway without a balancer in order to avoid cached data duplication. -.. note:: Each time the Rados Gateway is restarted the content of the cache directory is purged. +.. note:: Each time the RGW daemon is restarted the content of the cache directory is purged. Logs ---- diff --git a/doc/radosgw/layout.rst b/doc/radosgw/layout.rst index 9d36486300d..4f4a4297eea 100644 --- a/doc/radosgw/layout.rst +++ b/doc/radosgw/layout.rst @@ -1,5 +1,5 @@ =========================== - Rados Gateway Data Layout + RADOS Gateway Data Layout =========================== Although the source code is the ultimate guide, this document helps diff --git a/doc/radosgw/lua-scripting.rst b/doc/radosgw/lua-scripting.rst index 344e17b8866..c9094b9ee10 100644 --- a/doc/radosgw/lua-scripting.rst +++ b/doc/radosgw/lua-scripting.rst @@ -26,7 +26,7 @@ By default, the execution of a Lua script is limited to a maximum runtime of 100 .. warning:: Be cautious when modifying the memory limit. If the current memory usage exceeds the newly set limit, all previously stored data in the background state will be lost. -.. warning:: Disabling the runtime limit may result in unbounded script execution, which can lead to excessive resource consumption and potentially impact the RADOS gateway's availability. +.. warning:: Disabling the runtime limit may result in unbounded script execution, which can lead to excessive resource consumption and potentially impact the RADOS Gateway's availability. By default, all Lua standard libraries are available in the script, however, in order to allow for additional Lua modules to be used in the script, we support adding packages to an allowlist: diff --git a/doc/radosgw/rgw-cache.rst b/doc/radosgw/rgw-cache.rst index fb6486405e8..8fc5b2a8387 100644 --- a/doc/radosgw/rgw-cache.rst +++ b/doc/radosgw/rgw-cache.rst @@ -17,7 +17,7 @@ and caching-out on subsequent GET requests, passing thru transparently PUT,POST, The feature introduces 2 new APIs: Auth and Cache. - NOTE: The `D3N RGW Data Cache`_ is an alternative data caching mechanism implemented natively in the Rados Gateway. + NOTE: The `D3N RGW Data Cache`_ is an alternative data caching mechanism implemented natively in the RADOS Gateway. New APIs ------------------------- -- 2.39.5