From 7e864427fad68854820b7d051e258de7f0dbbfbb Mon Sep 17 00:00:00 2001 From: Ville Ojamo <14869000+bluikko@users.noreply.github.com> Date: Mon, 12 May 2025 16:01:44 +0700 Subject: [PATCH] doc/radosgw: Use ref for hyperlinks, 2nd batch Use validated ":ref:" hyperlinks instead of "external links" in "target definitions" when linking within the Ceph docs: - Add a label at beginning of referenced files if missing. - Remove unused "target definitions". - Updated links targeting files: compression encryption keystone Cleaned hyperlinks usage in kmip.rst: - Some links were using anonymous links (double underscore) unnecessarily. - Some links were not using backticks, add for consistency. - Move anonymous link definition to after the ordered list to avoid unnecessary empty line between list items. Use an already existing label for 2 intra-docs links that used full URLs. Use an already existing label for intra-docs link instead of a file name reference in s3/authentication.rst. The rendered PR should look the same as the old docs, only differing in the source RST. Signed-off-by: Ville Ojamo <14869000+bluikko@users.noreply.github.com> --- doc/radosgw/barbican.rst | 6 ++---- doc/radosgw/compression.rst | 9 ++++----- doc/radosgw/d3n_datacache.rst | 6 ++---- doc/radosgw/encryption.rst | 2 ++ doc/radosgw/keystone.rst | 2 ++ doc/radosgw/kmip.rst | 15 ++++++--------- doc/radosgw/multisite.rst | 2 +- doc/radosgw/s3/authentication.rst | 4 ++-- doc/radosgw/vault.rst | 3 +-- doc/radosgw/zone-features.rst | 7 ++----- 10 files changed, 24 insertions(+), 32 deletions(-) diff --git a/doc/radosgw/barbican.rst b/doc/radosgw/barbican.rst index a90d063fb9705..013294b33f8e9 100644 --- a/doc/radosgw/barbican.rst +++ b/doc/radosgw/barbican.rst @@ -3,7 +3,7 @@ OpenStack Barbican Integration ============================== OpenStack `Barbican`_ can be used as a secure key management service for -`Server-Side Encryption`_. +:ref:`Server-Side Encryption `. .. image:: ../images/rgw-encryption-barbican.png @@ -17,7 +17,7 @@ Configure Keystone Barbican depends on Keystone for authorization and access control of its keys. -See `OpenStack Keystone Integration`_. +See :ref:`OpenStack Keystone Integration `. Create a Keystone user ====================== @@ -115,8 +115,6 @@ When using API version 3:: .. _Barbican: https://wiki.openstack.org/wiki/Barbican -.. _Server-Side Encryption: ../encryption -.. _OpenStack Keystone Integration: ../keystone .. _Manage projects, users, and roles: https://docs.openstack.org/admin-guide/cli-manage-projects-users-and-roles.html#create-a-user .. _How to Create a Secret: https://developer.openstack.org/api-guide/key-manager/secrets.html#how-to-create-a-secret .. _SSE-KMS: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html diff --git a/doc/radosgw/compression.rst b/doc/radosgw/compression.rst index 55617cffdc8da..3a286f032b6f6 100644 --- a/doc/radosgw/compression.rst +++ b/doc/radosgw/compression.rst @@ -1,3 +1,5 @@ +.. _radosgw-compression: + =========== Compression =========== @@ -7,7 +9,7 @@ Compression The Ceph Object Gateway supports server-side compression of uploaded objects. .. note:: The Reef release added a :ref:`feature_compress_encrypted` zonegroup - feature to enable compression with `Server-Side Encryption`_. + feature to enable compression with :ref:`Server-Side Encryption `. Supported compression plugins include the following: @@ -76,7 +78,7 @@ For example: } .. note:: A ``default`` zone is created for you if you have not done any - previous `Multisite Configuration`_. + previous :ref:`Multisite Configuration `. Statistics @@ -113,6 +115,3 @@ uncompressed data. The ``size_utilized`` and ``size_kb_utilized`` fields represent the total size of compressed data, in bytes and kilobytes respectively. - -.. _`Server-Side Encryption`: ../encryption -.. _`Multisite Configuration`: ../multisite diff --git a/doc/radosgw/d3n_datacache.rst b/doc/radosgw/d3n_datacache.rst index 477323271aaef..d02395129fe04 100644 --- a/doc/radosgw/d3n_datacache.rst +++ b/doc/radosgw/d3n_datacache.rst @@ -57,8 +57,8 @@ Requirements Limitations ----------- -- D3N will not cache objects compressed by `Rados Gateway Compression`_ (OSD level compression is supported). -- D3N will not cache objects encrypted by `Rados Gateway Encryption`_. +- D3N will not cache objects compressed by :ref:`RADOS Gateway Compression ` (OSD level compression is supported). +- D3N will not cache objects encrypted by :ref:`RADOS Gateway Encryption `. - D3N will be disabled if the ``rgw_max_chunk_size`` config variable value differs from the ``rgw_obj_stripe_size`` config variable value. @@ -125,7 +125,5 @@ The following D3N related settings can be added to the Ceph configuration file .. _MOC D3N (Datacenter-scale Data Delivery Network): https://massopen.cloud/research-and-development/cloud-research/d3n/ .. _Red Hat Research D3N Cache for Data Centers: https://research.redhat.com/blog/research_project/d3n-multilayer-cache/ -.. _Rados Gateway Compression: ../compression/ -.. _Rados Gateway Encryption: ../encryption/ .. _RGW Data cache and CDN: ../rgw-cache/ .. _Service Management - Mounting Files with Extra Container Arguments: ../cephadm/services/#mounting-files-with-extra-container-arguments diff --git a/doc/radosgw/encryption.rst b/doc/radosgw/encryption.rst index e30fe14687250..e95bfeb05aabd 100644 --- a/doc/radosgw/encryption.rst +++ b/doc/radosgw/encryption.rst @@ -1,3 +1,5 @@ +.. _radosgw-encryption: + ========== Encryption ========== diff --git a/doc/radosgw/keystone.rst b/doc/radosgw/keystone.rst index d1d19c3965bf0..0a6717c55ade4 100644 --- a/doc/radosgw/keystone.rst +++ b/doc/radosgw/keystone.rst @@ -1,3 +1,5 @@ +.. _radosgw-keystone: + ===================================== Integrating with OpenStack Keystone ===================================== diff --git a/doc/radosgw/kmip.rst b/doc/radosgw/kmip.rst index 988897121d216..9192d1e559c54 100644 --- a/doc/radosgw/kmip.rst +++ b/doc/radosgw/kmip.rst @@ -3,7 +3,7 @@ KMIP Integration ================ `KMIP`_ can be used as a secure key management service for -`Server-Side Encryption`_ (SSE-KMS). +:ref:`Server-Side Encryption ` (SSE-KMS). .. ditaa:: @@ -53,15 +53,15 @@ here, 1. `IBM Security Guardium Key Lifecycle Manager (SKLM)`__. This is a well supported commercial product. -__ SKLM_ - -2. PyKMIP_. This is a small python project, suitable for experimental +2. `PyKMIP`_. This is a small python project, suitable for experimental and testing use only. +__ SKLM_ + Using IBM SKLM -------------- -IBM SKLM__ supports client authentication using certificates. +IBM `SKLM`_ supports client authentication using certificates. Certificates may either be self-signed certificates created, for instance, using openssl, or certificates may be created using SKLM. Ceph should then be configured (see below) to @@ -70,8 +70,6 @@ but it will leave an "untrusted client device certificate" in SKLM. This can be then upgraded to a registered client using the web interface to complete the registration process. -__ SKLM_ - Find untrusted clients under ``Advanced Configuration``, ``Client Device Communication Certificates``. Select ``Modify SSL/KMIP Certificates for Clients``, then toggle the flag @@ -80,7 +78,7 @@ Find untrusted clients under ``Advanced Configuration``, Using PyKMIP ------------ -PyKMIP_ has no special registration process, it simply +`PyKMIP`_ has no special registration process, it simply trusts the certificate. However, the certificate has to be issued by a certificate authority that is trusted by pykmip. PyKMIP also prefers that the certificate contain @@ -213,7 +211,6 @@ radosgw would fetch the secret from:: pykmip-mybucketkey -.. _Server-Side Encryption: ../encryption .. _KMIP: http://www.oasis-open.org/committees/kmip/ .. _SKLM: https://www.ibm.com/products/ibm-security-key-lifecycle-manager .. _PyKMIP: https://pykmip.readthedocs.io/en/latest/ diff --git a/doc/radosgw/multisite.rst b/doc/radosgw/multisite.rst index e7dc54301eca7..87e9a32659d41 100644 --- a/doc/radosgw/multisite.rst +++ b/doc/radosgw/multisite.rst @@ -99,7 +99,7 @@ At the bottom of this diagram, we see the data distributed into the Ceph Storage Cluster. For additional details on setting up a cluster, see `Ceph Object Gateway for -Production `__. +Production `_. Functional Changes from Infernalis ================================== diff --git a/doc/radosgw/s3/authentication.rst b/doc/radosgw/s3/authentication.rst index 115d0bbf5ee02..52bb7710d6e1f 100644 --- a/doc/radosgw/s3/authentication.rst +++ b/doc/radosgw/s3/authentication.rst @@ -42,7 +42,7 @@ In a radosgw instance that is configured with authentication against OpenStack Keystone, it is possible to use Keystone as an authoritative source for S3 API authentication. To do so, you must set: -* the ``rgw keystone`` configuration options explained in :doc:`../keystone`, +* the ``rgw keystone`` configuration options explained in :ref:`radosgw-keystone`, * ``rgw s3 auth use keystone = true``. In addition, a user wishing to use the S3 API must obtain an AWS-style @@ -66,7 +66,7 @@ access to radosgw. .. note:: Consider that most production radosgw deployments authenticating against OpenStack Keystone are also set up - for :doc:`../multitenancy`, for which special + for :ref:`rgw-multitenancy`, for which special considerations apply with respect to S3 signed URLs and public read ACLs. diff --git a/doc/radosgw/vault.rst b/doc/radosgw/vault.rst index 26c88c13a7f72..fec7b265b50ca 100644 --- a/doc/radosgw/vault.rst +++ b/doc/radosgw/vault.rst @@ -3,7 +3,7 @@ HashiCorp Vault Integration =========================== HashiCorp `Vault`_ can be used as a secure key management service for -`Server-Side Encryption`_ (SSE-KMS). +:ref:`Server-Side Encryption ` (SSE-KMS). .. ditaa:: @@ -430,7 +430,6 @@ In the transit engine example above, the Object Gateway would encrypt the secret http://vaultserver:8200/v1/transit/mybucketkey -.. _Server-Side Encryption: ../encryption .. _Vault: https://www.vaultproject.io/docs/ .. _Token authentication method: https://www.vaultproject.io/docs/auth/token.html .. _Vault agent: https://www.vaultproject.io/docs/agent/index.html diff --git a/doc/radosgw/zone-features.rst b/doc/radosgw/zone-features.rst index 5b5986527ab68..63862b8299f4b 100644 --- a/doc/radosgw/zone-features.rst +++ b/doc/radosgw/zone-features.rst @@ -41,8 +41,8 @@ of its RGWs and OSDs have upgraded. compress-encrypted ~~~~~~~~~~~~~~~~~~ -This feature enables support for combining `Server-Side Encryption`_ and -`Compression`_ on the same object. Object data gets compressed before encryption. +This feature enables support for combining :ref:`Server-Side Encryption ` and +:ref:`radosgw-compression` on the same object. Object data gets compressed before encryption. Prior to Reef, multisite would not replicate such objects correctly, so all zones must upgrade to Reef or later before enabling. @@ -112,6 +112,3 @@ On any cluster in the realm: radosgw-admin zonegroup modify --rgw-zonegroup={zonegroup-name} --disable-feature={feature-name} radosgw-admin period update --commit - -.. _`Server-Side Encryption`: ../encryption -.. _`Compression`: ../compression -- 2.39.5