doc/rgw: document s3control apis for PublicAccessBlock

Signed-off-by: Casey Bodley <cbodley@redhat.com>

diff --git a/PendingReleaseNotes b/PendingReleaseNotes
index a3ec1db9ec6ec97e429ddfb5c1b768814db80d9d..95477590e019f4c21e1b03c8f49abe2baccecccd 100644 (file)
--- a/PendingReleaseNotes
+++ b/PendingReleaseNotes
@@ -9,6 +9,7 @@
   restore status in listing responses. Restore status is stored in the bucket
   index, so only objects written or restored after this upgrade will populate
   the field. Existing objects are unaffected.
+* RGW: New S3 Control APIs to apply PublicAccessBlock configuration to User Accounts.
 * ceph-volume: Raw BlueStore OSD preparation now pre-formats NVMe devices and
   skips the slower BlueStore discard phase,reducing mkfs time on
   very large namespaces.

diff --git a/doc/radosgw/s3.rst b/doc/radosgw/s3.rst
index 55c39142915a4f6622701e2086fb5aec8f904098..c8f103466a50e636ab246daffb45a1d3fac5df24 100644 (file)
--- a/doc/radosgw/s3.rst
+++ b/doc/radosgw/s3.rst
@@ -88,6 +88,8 @@ The following table describes the support status for current Amazon S3 functiona
 +---------------------------------+-----------------+--------------------------------------------------+
 | **Bucket PublicAccessBlock**    | Supported       |                                                  |
 +---------------------------------+-----------------+--------------------------------------------------+
+| **Account PublicAccessBlock**   | Supported       | See :ref:`radosgw-s3control`                     |
++---------------------------------+-----------------+--------------------------------------------------+
 
 Unsupported Header Fields
 -------------------------

diff --git a/doc/radosgw/s3/s3control.rst b/doc/radosgw/s3/s3control.rst
new file mode 100644 (file)
index 0000000..f47344d
--- /dev/null
+++ b/doc/radosgw/s3/s3control.rst
@@ -0,0 +1,52 @@
+.. _radosgw-s3control:
+
+==========
+S3 Control
+==========
+
+.. versionadded:: Umbrella
+
+The Ceph Object Gateway supports a subset of the `AWS S3 Control API`_ for
+``PublicAccessBlock`` configuration on :ref:`User Accounts <radosgw-account>`,
+similar to the S3 API's ``PublicAccessBlock`` configuration for buckets. This
+account-level configuration applies to all buckets owned by the account. When
+configured at both account- and bucket-level, precedence goes to whichever is
+more restrictive.
+
+Configuration
+-------------
+
+Support for this feature is controlled by :confval:`rgw_enable_apis`, where
+``s3control`` is enabled by default.
+
+Wildcard DNS
+~~~~~~~~~~~~
+
+When issuing S3 Control requests, `awscli`_ and some AWS SDKs add the account
+id to the hostname like ``rgw69573912842483864.s3.example.com``, so expect a
+DNS configuration that allows a wildcard subdomain. If the
+:ref:`HTTP Frontend <rgw_frontends>` is configured for SSL, its certificate
+must also match this wildcard subdomain.
+
+Because this behavior is not documented in the AWS API reference (and the
+account id is already supplied in the ``x-amz-account-id`` request header),
+Ceph Object Gateway does not require the account to be part of the hostname
+and will ignore it when given.
+
+Operations
+----------
+
+The following table describes the currently supported S3 Control actions.
+
++------------------------------+---------------------------------------------+
+| Action                       | Remarks                                     |
++==============================+=============================================+
+| **PutPublicAccessBlock**     |                                             |
++------------------------------+---------------------------------------------+
+| **GetPublicAccessBlock**     |                                             |
++------------------------------+---------------------------------------------+
+| **DeletePublicAccessBlock**  |                                             |
++------------------------------+---------------------------------------------+
+
+.. _AWS S3 Control API: https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_AWS_S3_Control.html
+.. _awscli: https://aws.amazon.com/cli/