From d3584524eea246c5f847bfc35fc6bfc85c63b34e Mon Sep 17 00:00:00 2001 From: Lubos Mjachky Date: Mon, 23 May 2022 18:53:21 +0200 Subject: [PATCH] Refactor the RBAC documentation for the plugin closes #641 --- CHANGES/641.doc | 2 + docs/authentication.rst | 2 +- docs/index.rst | 4 +- docs/rbac/index.rst | 26 ++ docs/rbac/migrating-perms-to-roles.rst | 41 +++ .../permissions.rst} | 31 +- docs/rbac/roles.rst | 285 ++++++++++++++++++ docs/tech-preview.rst | 2 +- 8 files changed, 367 insertions(+), 26 deletions(-) create mode 100644 CHANGES/641.doc create mode 100644 docs/rbac/index.rst create mode 100644 docs/rbac/migrating-perms-to-roles.rst rename docs/{role-based-access-control.rst => rbac/permissions.rst} (86%) create mode 100644 docs/rbac/roles.rst diff --git a/CHANGES/641.doc b/CHANGES/641.doc new file mode 100644 index 000000000..0adba2498 --- /dev/null +++ b/CHANGES/641.doc @@ -0,0 +1,2 @@ +Improved the documentation for RBAC by adding a new section for roles and a new section for +migrating from permissions to roles. diff --git a/docs/authentication.rst b/docs/authentication.rst index 0e77bfcd4..8a793bedb 100644 --- a/docs/authentication.rst +++ b/docs/authentication.rst @@ -4,7 +4,7 @@ Authentication ============== The Pulp Registry supports `token authentication `_. -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``. diff --git a/docs/index.rst b/docs/index.rst index 602b8743f..53e1a1e2c 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/rbac/index.rst b/docs/rbac/index.rst new file mode 100644 index 000000000..d75d4a2b9 --- /dev/null +++ b/docs/rbac/index.rst @@ -0,0 +1,26 @@ +.. _rbac-index: + +Role-based Access Control +========================= + +Role-based access control (RBAC) **restricts** access to entities based on a user's role within an +organization. A 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, container repositories' content is accessible via ``podman`` or ``docker`` pull +commands, 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 diff --git a/docs/rbac/migrating-perms-to-roles.rst b/docs/rbac/migrating-perms-to-roles.rst new file mode 100644 index 000000000..e548552b0 --- /dev/null +++ b/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. diff --git a/docs/role-based-access-control.rst b/docs/rbac/permissions.rst similarity index 86% rename from docs/role-based-access-control.rst rename to docs/rbac/permissions.rst index 9c867003b..c536f2da3 100644 --- a/docs/role-based-access-control.rst +++ b/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, details of permissions used within +the container plugin are discussed. -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:: diff --git a/docs/rbac/roles.rst b/docs/rbac/roles.rst new file mode 100644 index 000000000..a004ae5be --- /dev/null +++ b/docs/rbac/roles.rst @@ -0,0 +1,285 @@ +.. _roles: + +Roles +===== + +Role based access control (RBAC) is configured using access policies for the following endpoints: + +* ``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`` + + +Default Roles +------------- + +For each endpoint, a different set of roles is defined. The roles can be assigned at the model +or object level for every user or group. In the following sections, the *Creator*, *Owner*, +*Consumer*, and *Collaborator* roles are introduced. The *Consumer* and *Collaborator* roles are +defined only for namespaces and distributions (i.e., container repositories served by the Pulp Registry). + +Creator Role +~~~~~~~~~~~~ + +The *Creator* role contains the ``add`` permission for objects present on a particular endpoint. +For the distributions endpoint, only users with the ``container.add_containerdistribution`` +permission can create objects: + +.. code-block:: bash + + pulp role show --name "container.containerdistribution_creator" + +:: + + { + "pulp_href": "/pulp/api/v3/roles/1a8555c8-3bfc-4688-81e3-5bf6fa38b9d7/", + "pulp_created": "2022-05-26T12:02:28.872667Z", + "name": "container.containerdistribution_creator", + "description": null, + "permissions": [ + "container.add_containerdistribution" + ], + "locked": true + } + +To perform operations on an endpoint (aka ViewSet actions), a user may need to have additional +permissions. One of the following *conditions* need to be satisfied to create a new distribution: + +.. code-block:: bash + + pulp access-policy show --viewset-name "distributions/container/container" | jq -r '.statements[] | select(.action[] | contains("create"))' + +:: + + { + "action": [ + "create" + ], + "effect": "allow", + "condition": "has_namespace_model_perms", + "principal": "authenticated" + } + { + "action": [ + "create" + ], + "effect": "allow", + "condition": "has_namespace_perms:container.add_containerdistribution", + "principal": "authenticated" + } + { + "action": [ + "create" + ], + "effect": "allow", + "condition": "namespace_is_username", + "principal": "authenticated" + } + +.. note:: + + A user with the *Creator* role for namespaces does not need to have any additional roles to + create distributions within the given namespaces. Similarly, the user is allowed to create + distributions within the owning username namespace (e.g., user ``alice`` can create container + repositories like ``alice/repo1``). + + +Owner Role +~~~~~~~~~~ + +The *Owner* role contains all of the permissions available for the associated ViewSet apart from +the ``add`` permission. For the ViewSet hosting namespaces, the set of permissions reads: + +.. code-block:: bash + + pulp role show --name "container.containernamespace_owner" + +:: + + { + "pulp_href": "/pulp/api/v3/roles/1f5519f5-5b2d-47cc-b081-2f38f256740e/", + "pulp_created": "2022-05-26T12:02:28.999330Z", + "name": "container.containernamespace_owner", + "description": null, + "permissions": [ + "container.delete_containernamespace", + "container.manage_roles_containernamespace", + "container.namespace_add_containerdistribution", + "container.namespace_change_containerdistribution", + "container.namespace_change_containerpushrepository", + "container.namespace_delete_containerdistribution", + "container.namespace_modify_content_containerpushrepository", + "container.namespace_pull_containerdistribution", + "container.namespace_push_containerdistribution", + "container.namespace_view_containerdistribution", + "container.namespace_view_containerpushrepository", + "container.view_containernamespace" + ], + "locked": true + } + +Besides the permissions for *Read*, *Update*, and *Delete* actions, the *Owner* role has the +``mange_roles`` permission that allows the user to call the ViewSet's ``add_role`` and +``remove_role`` endpoints for easy management of roles around that ViewSet's object. + +The *Owner* role for namespaces contains permissions for any additional action that can be performed +on the related endpoints. The endpoints serving content for container clients permit access to +container distributions/repositories based on the presence of ``pull_containerdistribution`` and +``push_containerdistributuion`` permissions. + +.. note:: + + Repositories of the push type created with container clients (e.g., by running ``podman push``) + are considered public and anyone can ``pull`` the images from them. + + +Consumer Role +~~~~~~~~~~~~~ + +The *Consumer* role contains only the ``view`` and ``pull`` permissions. Below, a list of associated +permissions for distributions is showcased: + +.. code-block:: bash + + pulp role show --name "container.containerdistribution_consumer" + +:: + + { + "pulp_href": "/pulp/api/v3/roles/7b97928a-5d33-454f-982e-41cfe102b273/", + "pulp_created": "2022-05-26T12:02:28.945828Z", + "name": "container.containerdistribution_consumer", + "description": null, + "permissions": [ + "container.pull_containerdistribution", + "container.view_containerdistribution" + ], + "locked": true + } + +Having the ``view`` and ``pull`` permissions allows a user to see and pull content from the Pulp +Registry. Assigning this role only at the object level allows administrators and owners to select +what the user can see. + +.. code-block:: bash + + pulp container distribution create --name "foo" --base-path "bar" + pulp user create --username "consumer" + pulp container distribution role add --name "foo" --user "consumer" --role "container.containerdistribution_consumer" + pulp user role-assignment list --username "consumer" + +:: + + [ + { + "pulp_href": "/pulp/api/v3/users/44/roles/6e58251d-7656-4c0d-9630-ea51ed7c29b5/", + "pulp_created": "2022-05-27T15:27:00.623004Z", + "role": "container.containerdistribution_consumer", + "content_object": "/pulp/api/v3/distributions/container/container/5b8ec13c-d578-4b3a-9b99-80986e5e00b6/" + } + ] + +Also, it is possible to assign the role in the following manner: + +.. code-block:: bash + + PULP_HREF=$(pulp container distribution show --name "foo" | jq -r ".pulp_href") + pulp user role-assignment add --object ${PULP_HREF} --username "consumer" --role "container.containerdistribution_consumer" + + +Collaborator Role +~~~~~~~~~~~~~~~~~ + +The *Collaborator* role represents a set of permissions that a co-worker working within a same user-space +should have. In addition to the *Consumer* role, users with the *Collaborator* role are allowed +to add (push) and modify content. The following set of permissions is evaluated for the *Collaborator* +role for distributions: + +.. code-block:: bash + + pulp role show --name "container.containerdistribution_collaborator" + +:: + + { + "pulp_href": "/pulp/api/v3/roles/933e0376-8945-489a-93a6-cafb6753f4bb/", + "pulp_created": "2022-05-26T12:02:28.924330Z", + "name": "container.containerdistribution_collaborator", + "description": null, + "permissions": [ + "container.pull_containerdistribution", + "container.push_containerdistribution", + "container.view_containerdistribution" + ], + "locked": true + } + + +.. code-block:: bash + + pulp role show --name "container.containernamespace_collaborator" + +:: + + { + "pulp_href": "/pulp/api/v3/roles/1466e614-73a7-4a58-ab36-ced0ab1a1809/", + "pulp_created": "2022-05-26T12:02:29.058226Z", + "name": "container.containernamespace_collaborator", + "description": null, + "permissions": [ + "container.namespace_add_containerdistribution", + "container.namespace_change_containerdistribution", + "container.namespace_change_containerpushrepository", + "container.namespace_delete_containerdistribution", + "container.namespace_modify_content_containerpushrepository", + "container.namespace_pull_containerdistribution", + "container.namespace_push_containerdistribution", + "container.namespace_view_containerdistribution", + "container.namespace_view_containerpushrepository", + "container.view_containernamespace" + ], + "locked": true + } + +Customizing Roles +----------------- + +In Pulp, administrators are allowed to create or update roles. To create a role with permissions +required only for syncing content, one can do the following: + +.. code-block:: bash + + pulp role create --name "container.containerrepository_syncer" \ + --permission "container.view_containerrepository" \ + --permission "container.view_containerremote" \ + --permission "container.change_containerrepository" \ + --permission "container.modify_content_containerrepository" \ + --permission "container.sync_containerrepository" + + pulp user role-assignment add --username "alice" --role "container.containerrepository_syncer" object "" + +Customizing Access Policies +--------------------------- + +The plugin is shipped with default access policies that can be modified to achieve different RBAC +behaviour. For instance, update creation hooks accordingly: + +.. code-block:: bash + + pulp access-policy update --viewset-name "repositories/container/container" --creation-hooks '[{"function": "add_roles_for_object_creator", "parameters": {"roles": "container.containerrepository_syncer"}}]' + +.. note:: + + Access polices can be reset to their defaults using the ``pulp access-policy reset`` command. + +.. note:: + + Customizing the access policy will cause any future changes to the default policies, like + statement changes and bug fixes, to be ignored unless reset to the default policy. diff --git a/docs/tech-preview.rst b/docs/tech-preview.rst index b1e70e0d8..3e6d988d5 100644 --- a/docs/tech-preview.rst +++ b/docs/tech-preview.rst @@ -1,7 +1,7 @@ Tech previews ============= -The following features are currently being released as part of a tech preview. +The following features are currently being released as part of a tech preview: * Build an OCI image from a Containerfile * Import/Export with synced container repositories