From c89f8a06c10714d6fe2d398bac3d4bba8cd5c17a Mon Sep 17 00:00:00 2001 From: Ville Ojamo <14869000+bluikko@users.noreply.github.com> Date: Fri, 16 Jan 2026 15:55:27 +0700 Subject: [PATCH] doc/radosgw: change all intra-docs links to use ref (1 of 6) Part 1 of 6 to make backporting easier. Many of the following parts depend on this. Use the the ref role for all remaining links in doc/radosgw/ with the exception of config-ref.rst which will depend on changes to rgw.yaml.in. The external link definitions syntax being removed is intended for linking to external websites and not for intra-docs links. Validity of ref links will be checked during the docs build process. Add labels for links targets if necessary. Remove unused external link definitions in the modified files. Use confval instead of literal text for 2 configuration keys in vault.rst. Use Ceph Object Gateway consistently in multisite.rst. Signed-off-by: Ville Ojamo <14869000+bluikko@users.noreply.github.com> --- doc/man/8/radosgw-admin.rst | 2 ++ doc/radosgw/admin.rst | 6 ++++++ doc/radosgw/barbican.rst | 2 ++ doc/radosgw/elastic-sync-module.rst | 2 ++ doc/radosgw/encryption.rst | 9 +++------ doc/radosgw/iam.rst | 5 +++-- doc/radosgw/kmip.rst | 2 ++ doc/radosgw/multisite.rst | 14 +++++++------- doc/radosgw/notifications.rst | 2 ++ doc/radosgw/orphans.rst | 2 -- doc/radosgw/placement.rst | 3 +-- doc/radosgw/pools.rst | 2 ++ doc/radosgw/role.rst | 2 ++ doc/radosgw/swift/auth.rst | 4 +--- doc/radosgw/swift/tutorial.rst | 9 +++------ doc/radosgw/vault.rst | 6 ++++-- doc/radosgw/zone-features.rst | 2 ++ 17 files changed, 44 insertions(+), 30 deletions(-) diff --git a/doc/man/8/radosgw-admin.rst b/doc/man/8/radosgw-admin.rst index ae317aef7dfb5..3860f02081908 100644 --- a/doc/man/8/radosgw-admin.rst +++ b/doc/man/8/radosgw-admin.rst @@ -1,5 +1,7 @@ :orphan: +.. _man-radosgw-admin: + ================================================================= radosgw-admin -- rados REST gateway user administration utility ================================================================= diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst index 93c78e05973c3..c04ce3b5a50b8 100644 --- a/doc/radosgw/admin.rst +++ b/doc/radosgw/admin.rst @@ -1,3 +1,5 @@ +.. _radosgw-admin-guide: + ============= Admin Guide ============= @@ -432,6 +434,8 @@ To remove the admin flag from an existing user: radosgw-admin user modify --uid={username} --admin=0 +.. _radosgw-quota-management: + Quota Management ================ @@ -618,6 +622,8 @@ commands, as in the following examples: be restarted for the changes to take effect. +.. _radosgw-rate-limit-management: + Rate Limit Management ===================== diff --git a/doc/radosgw/barbican.rst b/doc/radosgw/barbican.rst index 013294b33f8e9..ac3fdc7eb87ae 100644 --- a/doc/radosgw/barbican.rst +++ b/doc/radosgw/barbican.rst @@ -1,3 +1,5 @@ +.. _radosgw-barbican: + ============================== OpenStack Barbican Integration ============================== diff --git a/doc/radosgw/elastic-sync-module.rst b/doc/radosgw/elastic-sync-module.rst index 60c806e879b0a..b902e7372d2cd 100644 --- a/doc/radosgw/elastic-sync-module.rst +++ b/doc/radosgw/elastic-sync-module.rst @@ -1,3 +1,5 @@ +.. _radosgw-elastic-sync-module: + ========================= ElasticSearch Sync Module ========================= diff --git a/doc/radosgw/encryption.rst b/doc/radosgw/encryption.rst index e95bfeb05aabd..64e8b63dc3a33 100644 --- a/doc/radosgw/encryption.rst +++ b/doc/radosgw/encryption.rst @@ -43,8 +43,8 @@ This is implemented in S3 according to the `Amazon SSE-KMS`_ specification. In principle, any key management service could be used here. Currently integration with `Barbican`_, `Vault`_, and `KMIP`_ are implemented. -See `OpenStack Barbican Integration`_, `HashiCorp Vault Integration`_, -and `KMIP Integration`_. +See :ref:`radosgw-barbican`, :ref:`radosgw-vault`, +and :ref:`radosgw-kmip`. SSE-S3 ====== @@ -59,7 +59,7 @@ This is implemented in S3 according to the `Amazon SSE-S3`_ specification. In principle, any key management service could be used here. Currently only integration with `Vault`_, is implemented. -See `HashiCorp Vault Integration`_. +See :ref:`radosgw-vault`. Bucket Encryption APIs ====================== @@ -93,6 +93,3 @@ The configuration expects a base64-encoded 256 bit key. For example:: .. _PutBucketEncryption: https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketEncryption.html .. _GetBucketEncryption: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketEncryption.html .. _DeleteBucketEncryption: https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketEncryption.html -.. _OpenStack Barbican Integration: ../barbican -.. _HashiCorp Vault Integration: ../vault -.. _KMIP Integration: ../kmip diff --git a/doc/radosgw/iam.rst b/doc/radosgw/iam.rst index 444edea87eb5e..c123aee0ea560 100644 --- a/doc/radosgw/iam.rst +++ b/doc/radosgw/iam.rst @@ -1,3 +1,5 @@ +.. _radosgw-iam: + ============================= Ceph Object Gateway IAM API ============================= @@ -8,7 +10,7 @@ The Ceph Object Gateway supports a subset of the `Amazon IAM API`_ for the RESTful management of account users, roles, and associated policies. This REST API is served by the same HTTP endpoint as the -`Ceph Object Gateway S3 API`_. +:ref:`radosgw s3`. Authorization ============= @@ -194,4 +196,3 @@ AmazonS3ReadOnlyAccess .. _Amazon IAM API: https://docs.aws.amazon.com/IAM/latest/APIReference/welcome.html -.. _Ceph Object Gateway S3 API: ../s3/ diff --git a/doc/radosgw/kmip.rst b/doc/radosgw/kmip.rst index 25677b268a021..2943ede8ddce5 100644 --- a/doc/radosgw/kmip.rst +++ b/doc/radosgw/kmip.rst @@ -1,3 +1,5 @@ +.. _radosgw-kmip: + ================ KMIP Integration ================ diff --git a/doc/radosgw/multisite.rst b/doc/radosgw/multisite.rst index 87e9a32659d41..3b62b0e4f4f4e 100644 --- a/doc/radosgw/multisite.rst +++ b/doc/radosgw/multisite.rst @@ -121,12 +121,12 @@ Requirements and Assumptions ============================ A multi-site configuration requires at least two Ceph storage clusters. The -multi-site configuration must have at least two Ceph object gateway instances +multi-site configuration must have at least two Ceph Object Gateway instances (one for each Ceph storage cluster). This guide assumes that at least two Ceph storage clusters are in geographically separate locations; however, the configuration can work on the -same site. This guide also assumes two Ceph object gateway servers named +same site. This guide also assumes two Ceph Object Gateway servers named ``rgw1`` and ``rgw2``. .. important:: Running a single geographically-distributed Ceph storage cluster @@ -140,8 +140,8 @@ In this guide, the ``rgw1`` host will serve as the master zone of the master zonegroup; and, the ``rgw2`` host will serve as the secondary zone of the master zonegroup. -See `Pools`_ for instructions on creating and tuning pools for Ceph Object -Storage. +See :ref:`radosgw-pools` for instructions on creating and tuning pools for the +Ceph Object Gateway. See :ref:`Sync Policy Config ` for instructions on defining fine-grained bucket sync policy rules. @@ -1381,7 +1381,9 @@ Zones ----- A zone defines a logical group that consists of one or more Ceph Object Gateway -instances. All Ceph Object Gateways in a given zone serve S3 objects that are backed by RADOS objects that are stored in the same set of pools in the same cluster. Ceph Object Gateway supports zones. +instances. All Ceph Object Gateways in a given zone serve S3 objects that are +backed by RADOS objects that are stored in the same set of pools in the same +cluster. Ceph Object Gateway supports zones. The procedure for configuring zones differs from typical configuration procedures, because not all of the settings end up in a Ceph configuration @@ -1600,5 +1602,3 @@ instance. | | changing this setting. | | | +-------------------------------------+-----------------------------------+---------+-----------------------+ - -.. _`Pools`: ../pools diff --git a/doc/radosgw/notifications.rst b/doc/radosgw/notifications.rst index 645ed7f4e920d..35e088c53e45b 100644 --- a/doc/radosgw/notifications.rst +++ b/doc/radosgw/notifications.rst @@ -1,3 +1,5 @@ +.. _radosgw-notifications: + ==================== Bucket Notifications ==================== diff --git a/doc/radosgw/orphans.rst b/doc/radosgw/orphans.rst index bf6b10edfca0f..dd2399c811f59 100644 --- a/doc/radosgw/orphans.rst +++ b/doc/radosgw/orphans.rst @@ -113,5 +113,3 @@ RGW. When larger objects are copied from bucket to bucket, only the shared. Those shared objects will contain the marker of the original bucket. -.. _Data Layout in RADOS : ../layout -.. _Pool Placement and Storage Classes : ../placement diff --git a/doc/radosgw/placement.rst b/doc/radosgw/placement.rst index 384accbea81d5..80b5ad304c186 100644 --- a/doc/radosgw/placement.rst +++ b/doc/radosgw/placement.rst @@ -9,7 +9,7 @@ Placement Targets .. versionadded:: Jewel -Placement targets control which `Pools`_ are associated with a particular +Placement targets control which :ref:`radosgw-pools` are associated with a particular bucket. A bucket's placement target is selected on creation, and cannot be modified. The ``radosgw-admin bucket stats`` command will display its ``placement_rule``. @@ -271,4 +271,3 @@ names be used with Ceph, including ``INTELLIGENT-TIERING``, ``STANDARD_IA``, ``CHEAPNDEEP`` are accepted by Ceph but might not be by some clients and libraries. -.. _`Pools`: ../pools diff --git a/doc/radosgw/pools.rst b/doc/radosgw/pools.rst index 2bca23fa924bb..e54866813d364 100644 --- a/doc/radosgw/pools.rst +++ b/doc/radosgw/pools.rst @@ -1,3 +1,5 @@ +.. _radosgw-pools: + ===== Pools ===== diff --git a/doc/radosgw/role.rst b/doc/radosgw/role.rst index 514f17d5caecc..2d283bea28a67 100644 --- a/doc/radosgw/role.rst +++ b/doc/radosgw/role.rst @@ -1,3 +1,5 @@ +.. _radosgw-role: + ====== Role ====== diff --git a/doc/radosgw/swift/auth.rst b/doc/radosgw/swift/auth.rst index 12d6b23ffee54..b507d6ee3df26 100644 --- a/doc/radosgw/swift/auth.rst +++ b/doc/radosgw/swift/auth.rst @@ -10,9 +10,7 @@ To obtain a token from RADOS Gateway, you must create a user. For example:: sudo radosgw-admin user create --subuser="{username}:{subusername}" --uid="{username}" --display-name="{Display Name}" --key-type=swift --secret="{password}" --access=full -For details on RADOS Gateway administration, see `radosgw-admin`_. - -.. _radosgw-admin: ../../../man/8/radosgw-admin/ +For details on RADOS Gateway administration, see :ref:`man-radosgw-admin`. .. note:: For those used to the Swift API this is implementing the Swift auth v1.0 API, as such diff --git a/doc/radosgw/swift/tutorial.rst b/doc/radosgw/swift/tutorial.rst index 5d2889b192d20..fca7c30ee0f83 100644 --- a/doc/radosgw/swift/tutorial.rst +++ b/doc/radosgw/swift/tutorial.rst @@ -8,9 +8,9 @@ client and the RADOS Gateway server. Then, you may follow a natural container and object lifecycle, including adding and retrieving object metadata. See example code for the following languages: -- `Java`_ -- `Python`_ -- `Ruby`_ +- :ref:`Java ` +- :ref:`Python ` +- :ref:`Ruby ` .. ditaa:: @@ -57,6 +57,3 @@ metadata. See example code for the following languages: | | | | +----------------------------+ +-----------------------------+ -.. _Java: ../java -.. _Python: ../python -.. _Ruby: ../ruby diff --git a/doc/radosgw/vault.rst b/doc/radosgw/vault.rst index 9db28272c1cb4..afda0e040b8b1 100644 --- a/doc/radosgw/vault.rst +++ b/doc/radosgw/vault.rst @@ -1,3 +1,5 @@ +.. _radosgw-vault: + =========================== HashiCorp Vault Integration =========================== @@ -157,9 +159,9 @@ Vault instances, or you could use either separately mounted transit instances, or different branches under a common transit point. If you are not using separate Vault instances, you can use these to point SSE-KMS and SSE-S3 to separate containers: -``rgw_crypt_vault_prefix`` +:confval:`rgw_crypt_vault_prefix` and/or -``rgw_crypt_sse_s3_vault_prefix``. +:confval:`rgw_crypt_sse_s3_vault_prefix`. When granting Vault permissions to SSE-KMS bucket owners, you should not give them permission to muck around with SSE-S3 keys; only Ceph itself should be doing that. diff --git a/doc/radosgw/zone-features.rst b/doc/radosgw/zone-features.rst index 63862b8299f4b..194a06f09d065 100644 --- a/doc/radosgw/zone-features.rst +++ b/doc/radosgw/zone-features.rst @@ -1,3 +1,5 @@ +.. _radosgw-zone-features: + ============= Zone Features ============= -- 2.47.3