From db71e09a82e0f0c2083a2072b0a7eb0117af953d 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 1c171dffdb5..a1cfa7dd175 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 4dd9329fc65..1dd411fdcb0 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 ================ @@ -619,6 +623,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 a90d063fb97..94b0495db8f 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 60c806e879b..b902e7372d2 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 e30fe146872..ef7aa9471a2 100644 --- a/doc/radosgw/encryption.rst +++ b/doc/radosgw/encryption.rst @@ -41,8 +41,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 ====== @@ -57,7 +57,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 ====================== @@ -91,6 +91,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 fa05280f4fa..4c1f3ffdd5a 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 ============= @@ -185,4 +187,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 988897121d2..06e0c15cdb8 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 731923ad64f..67a7b65e66e 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 @@ -1601,5 +1603,3 @@ instance. | | changing this setting. | | | +-------------------------------------+-----------------------------------+---------+-----------------------+ - -.. _`Pools`: ../pools diff --git a/doc/radosgw/notifications.rst b/doc/radosgw/notifications.rst index c665d291a01..dd835bc5dfe 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 bf6b10edfca..dd2399c811f 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 c30a20f32b3..3951acdcedf 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``. @@ -268,4 +268,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 70a5b4cfd66..4ff4ce0ecdc 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 514f17d5cae..2d283bea28a 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 12d6b23ffee..b507d6ee3df 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 5d2889b192d..fca7c30ee0f 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 26c88c13a7f..8fd4cd8b7bc 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 5b5986527ab..5ad3cc0acf6 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