Refactor the RBAC documentation for the plugin

closes pulp#641

docs/authentication.rst

@@ -4,7 +4,7 @@ Authentication
 ==============
 
 The Pulp Registry supports `token authentication <https://docs.docker.com/registry/spec/auth/token/>`_.
-The token authentication is enabled by default and does not come pre-configured out of the box. See
+The token authentication is enabled by default and **does not** come pre-configured out of the box. See
 the section :ref:`token-authentication-label` for more details.
 
 The token authentication can be disabled via the pulp settings by declaring ``TOKEN_AUTH_DISABLED=True``.

docs/index.rst

@@ -1,7 +1,7 @@
 Pulp Container Plugin
 =====================
 
-You can use the ``pulp_container`` plugin to extend Pulp so that you can host your own container registry and distribute containers in an on-prem environment.
+You can use the ``pulp_container`` plugin to extend Pulp so that you can host your container registry and distribute containers in an on-premises environment.
 You can synchronize from a range of Docker Registry HTTP API V2-compatible registries.
 Depending on your needs, you can perform whole or partial syncs from these remote repositories, blend content from different sources, and distribute them throughout your organization using Pulp.
 You can also build OCI-compatible images with Pulp Container and push them to a repository in Pulp so you can distribute private containers.
@@ -60,9 +60,9 @@ Container Workflows
 
    installation
    workflows/index
+   rbac/index
    restapi/index
    authentication
-   role-based-access-control
    tech-preview
    changes
    contributing

docs/rbac/index.rst

@@ -0,0 +1,25 @@
+.. _rbac-index:
+
+Role-based Access Control
+=========================
+
+Role-based access control (RBAC) **restricts** access to content based on a user's role within an
+organization. The role consists of one or more permissions. Users having a proper set of roles can
+view, modify, or delete content hosted on different endpoints.
+
+By default, all container repositories are accessible by anyone, unless the opposite is *explicitly*
+specified. A private repository can be created via the REST API for container distributions. An
+existing distribution can be updated with the parameter ``private=True``.
+
+.. note::
+
+    Users logged in as administrators (staff) always bypass any authorization checks.
+
+Visit the following sections to understand how the plugin implements RBAC:
+
+.. toctree::
+   :maxdepth: 2
+
+   roles
+   permissions
+   migrating-perms-to-roles

docs/rbac/migrating-perms-to-roles.rst

@@ -0,0 +1,41 @@
+.. _migrating-perms-to-roles:
+
+Migrating Permissions
+=====================
+
+As of release 2.11.0, the plugin started to support roles instead of separate groups and
+permissions. Permission classes provided by Pulp are **automatically** migrated when upgrading
+from older releases. But, custom permissions created before release 2.11.0 require additional
+**post-upgrade steps** to preserve the initial behaviour.
+
+Usually, administrators define permissions for two types of operations:
+
+1. **pull** - Pulling content from all or a number of specific repositories
+2. **push** - Pushing content to all or concrete repositories
+
+During the upgrade, the custom permissions need to be manually revised and assigned. To do so, one
+can proceed as follows:
+
+1. Make all repositories private:
+
+.. code-block:: bash
+
+    for name in $(pulp container distribution list | jq -re '.[].name')
+    do
+        pulp container distribution update --name $name --private
+    done
+
+2. Start assigning Pulp-provided/adjusted roles to a particular user. For instance, use the role
+   ``container.containerdistribution_consumer`` to enable user ``alice`` to consume content from
+   distributions ``dist1``, ``dist2``, ``dist3``:
+
+.. code-block:: bash
+
+    for distribution in "dist1" "dist2" "dist3"
+    do
+        DISTRIBUTION_HREF=$(pulp container distribution show --name $distribution | jq -r ".pulp_href")
+        pulp user role-assignment add --username "alice" --role "container.containerdistribution_consumer" --object $DISTRIBUTION_HREF
+    done
+
+Similarly, execute an adjusted script for other repository objects that were asserted under
+the permissions' scope.

docs/role-based-access-control.rst → docs/rbac/permissions.rst

@@ -1,25 +1,16 @@
-Role Based Access Control
-=========================
+.. _permissions:
 
-Role based access control in Pulp Container is configured using Access Policies for the following
-``viewset_names``:
+Permissions
+===========
 
-* ``pulp_container/namespaces``
-* ``distributions/container/container``
-* ``repositories/container/container-push``
-* ``remotes/container/container``
-* ``repositories/container/container``
-* ``repositories/container/container-push/versions``
-* ``repositories/container/container/versions``
-* ``content/container/blobs``
-* ``content/container/manifests``
-* ``content/container/tags``
+A role is defined by one or more permissions. In this section, there are discussed details of
+permissions used within the container plugin.
 
-This document describes the default access policies shipped with Pulp Container. Each of the above
-policies can be modified to achieve a different RBAC behavior.
+.. warning::
 
-Repositories that are created using ``podman push`` or ``docker push`` are considered public and anyone
-can ``pull`` the images from them. See below about creating private repositories.
+    The concept of managing granular permissions is obsolete. As of release 2.11.0, the plugin uses
+    :ref:`roles` instead of separate permission classes. To migrate the customized permission
+    classes to roles, follow the instructions shown at :ref:`migrating-perms-to-roles`.
 
 Namespaces
 ----------
@@ -172,10 +163,6 @@ public, then anyone can ``pull`` from the repository associated with the Distrib
 Private Repositories
 --------------------
 
-A private repository can be created using Pulp's API for Container Distributions. A distribution
-can be created before pushing to the repository or an existing distribution can be updated with
-``private=True``.
-
 Users wishing to ``pull`` from a Container Distribution with ``private=True``
 will require the following object level permission on the Distribution::