Refactor the RBAC documentation for the plugin #811

lubosmj · 2022-05-31T13:57:44Z

closes #641

mdellweg · 2022-06-02T09:08:26Z

docs/rbac/index.rst

+Role-based Access Control
+=========================
+
+Role-based access control (RBAC) **restricts** access to content based on a user's role within an


Are you talking specifically about "content" here (i think not). Maybe use entities instead. In the context of Pulp, "content" already has quite a distinct meaning.

mdellweg · 2022-06-02T09:11:04Z

docs/rbac/index.rst

+=========================
+
+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


Suggested change

organization. The role consists of one or more permissions. Users having a proper set of roles can

organization. A role consists of one or more permissions. Users having a proper set of roles can

mdellweg · 2022-06-02T09:14:57Z

docs/rbac/index.rst

+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*


I think you are referring to registry pull access here. Maybe something like ... repositories content is accessible via podman pull by anyone...

mdellweg · 2022-06-02T09:19:25Z

docs/rbac/permissions.rst

+A role is defined by one or more permissions. In this section, there are discussed details of
+permissions used within the container plugin.


Suggested change

A role is defined by one or more permissions. In this section, there are discussed details of

permissions used within the container plugin.

A role is defined by one or more permissions. In this section, details of

permissions used within the container plugin are discussed.

mdellweg · 2022-06-02T09:20:10Z

docs/rbac/roles.rst

+Default Roles
+-------------
+
+For each endpoint, there is defined a different set of roles. The roles can be assigned at the model


Suggested change

For each endpoint, there is defined a different set of roles. The roles can be assigned at the model

For each endpoint, a different set of roles is defined. The roles can be assigned at the model

mdellweg · 2022-06-02T09:29:59Z

docs/rbac/roles.rst

+The *Consumer* role contains only the ``view`` and ``pull`` permissions. Below is showcased a list
+of associated permissions for distributions:


Suggested change

The *Consumer* role contains only the ``view`` and ``pull`` permissions. Below is showcased a list

of associated permissions for distributions:

The *Consumer* role contains only the ``view`` and ``pull`` permissions. Below, a list

of associated permissions for distributions is showcased:

mdellweg · 2022-06-02T09:30:34Z

docs/rbac/roles.rst

+    }
+
+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 to select what the


Suggested change

Registry. Assigning this role only at the object level allows administrators to select what the

Registry. Assigning this role only at the object level allows administrators and owners to select what the

mdellweg · 2022-06-02T09:32:15Z

docs/rbac/roles.rst

+~~~~~~~~~~~~~~~~~
+
+The *Collaborator* role represents a set of permissions that a co-worker working within a same user-space
+should have. In comparison to the *Consumer* role, users with the *Collaborator* role are allowed


Suggested change

should have. In comparison to the *Consumer* role, users with the *Collaborator* role are allowed

should have. In addition to the *Consumer* role, users with the *Collaborator* role are allowed

mdellweg · 2022-06-02T09:33:32Z

docs/rbac/roles.rst

+.. 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 ""


Should this be an example about changing the AP?

Of course. I provide an example of how to create, assign, and hook a role.

For the sake of completeness, I will add an example of assigning default permissions to a user in one of the descriptions of the default roles.

I would still consider these two commands as an example to create and use a "custom role". "changing the access policy" to me is the next level of customization. My suggestion: Make this example its own thing, and move the headline for AP below it. Also maybe add an example for changing the statements in the AP.

I divided the section into two parts: Customizing Roles and Customizing Access Policies. It should be now better readable.

sounds good!

docs/tech-preview.rst

mdellweg

One nit-pick if you agree.

mdellweg · 2022-06-22T10:31:16Z

docs/rbac/roles.rst

+Customizing Roles
+-----------------
+
+In Pulp, users are allowed to create or update their roles. To create a role with permissions


Maybe this is admins...

ipanova · 2022-06-23T16:42:00Z

docs/rbac/index.rst

+
+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.


s/content/resources. There is rbac not just for content.

ipanova · 2022-06-23T16:43:54Z

docs/rbac/index.rst

+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.
+


maybe worth adding a section called 'Content and Repository access'

can you also add information about the queryset scoping?

Not sure how the information about the queryset scoping will be useful to users. It tells plugin-writers that Pulp restricts access to objects based on users' permissions (which is generally known and expected): https://github.com/pulp/pulpcore/blob/8ab3fdfba539b81fa25b67876dde7327992a6ce4/docs/plugins/plugin-writer/concepts/rbac/queryset_scoping.rst

ipanova · 2022-06-23T16:44:22Z

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

+=====================
+
+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


Default permissions classes

ipanova · 2022-06-23T16:48:34Z

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

+    done
+
+Similarly, execute an adjusted script for other repository objects that were asserted under
+the permissions' scope.


Can you mention the dump-permission management command Matthias has added?
Also please add a note that with pulp-container 2.13 this would be the only way to process unmigrated permissions because of removed django-guardian form the stack.

I added a note about the version and the dump-permission command.

closes pulp#641

lubosmj marked this pull request as ready for review May 31, 2022 13:57

lubosmj force-pushed the rbac-up-docs-641 branch from ce4a634 to 4d015ed Compare May 31, 2022 14:01

mdellweg reviewed Jun 2, 2022

View reviewed changes

lubosmj force-pushed the rbac-up-docs-641 branch 2 times, most recently from 38d9d9e to f3a0e24 Compare June 7, 2022 12:57

ipanova requested review from ipanova and mdellweg June 16, 2022 15:25

lubosmj force-pushed the rbac-up-docs-641 branch from f3a0e24 to 82fe503 Compare June 21, 2022 19:31

mdellweg approved these changes Jun 22, 2022

View reviewed changes

lubosmj force-pushed the rbac-up-docs-641 branch from 82fe503 to d358452 Compare June 22, 2022 11:30

ipanova reviewed Jun 23, 2022

View reviewed changes

ipanova self-requested a review June 23, 2022 17:03

Refactor the RBAC documentation for the plugin

781a1a0

closes pulp#641

lubosmj force-pushed the rbac-up-docs-641 branch from d358452 to 781a1a0 Compare June 24, 2022 09:07

ipanova approved these changes Jun 24, 2022

View reviewed changes

ipanova merged commit ab9d72f into pulp:main Jun 24, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor the RBAC documentation for the plugin #811

Refactor the RBAC documentation for the plugin #811

lubosmj commented May 31, 2022

mdellweg Jun 2, 2022

mdellweg Jun 2, 2022

mdellweg Jun 2, 2022

mdellweg Jun 2, 2022

mdellweg Jun 2, 2022

mdellweg Jun 2, 2022

mdellweg Jun 2, 2022

mdellweg Jun 2, 2022

mdellweg Jun 2, 2022

lubosmj Jun 3, 2022

mdellweg Jun 17, 2022 •

edited

Loading

lubosmj Jun 21, 2022

mdellweg Jun 22, 2022

mdellweg left a comment

mdellweg Jun 22, 2022

ipanova Jun 23, 2022

ipanova Jun 23, 2022 •

edited

Loading

ipanova Jun 23, 2022

lubosmj Jun 24, 2022 •

edited

Loading

ipanova Jun 23, 2022

ipanova Jun 23, 2022

lubosmj Jun 24, 2022

	organization. The role consists of one or more permissions. Users having a proper set of roles can
	organization. A role consists of one or more permissions. Users having a proper set of roles can

		A role is defined by one or more permissions. In this section, there are discussed details of
		permissions used within the container plugin.

	For each endpoint, there is defined a different set of roles. The roles can be assigned at the model
	For each endpoint, a different set of roles is defined. The roles can be assigned at the model

		The Consumer role contains only the ``view`` and ``pull`` permissions. Below is showcased a list
		of associated permissions for distributions:

	Registry. Assigning this role only at the object level allows administrators to select what the
	Registry. Assigning this role only at the object level allows administrators and owners to select what the

	should have. In comparison to the Consumer role, users with the Collaborator role are allowed
	should have. In addition to the Consumer role, users with the Collaborator role are allowed

Refactor the RBAC documentation for the plugin #811

Refactor the RBAC documentation for the plugin #811

Conversation

lubosmj commented May 31, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdellweg Jun 17, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdellweg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ipanova Jun 23, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lubosmj Jun 24, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdellweg Jun 17, 2022 •

edited

Loading

ipanova Jun 23, 2022 •

edited

Loading

lubosmj Jun 24, 2022 •

edited

Loading