Skip to content

Commit

Permalink
Convert to new docs-stack.
Browse files Browse the repository at this point in the history 
closes pulp#5055.
  • Loading branch information
@ggainey
ggainey committed Feb 19, 2024
1 parent 5871268 commit b53f4bf
Show file tree
Hide file tree
Showing 7 changed files with 605 additions and 0 deletions.
1 change: 1 addition & 0 deletions CHANGES/pulp_file/5055.misc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Convert to new docs-stack/layout.
246 changes: 246 additions & 0 deletions pulp_file/staging_docs/admin/guides/01-rbac.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,246 @@
# Role Based Access Control

Role based access control in Pulp File is configured using access policies for the following
`viewset_names`:

- `acs/file/file`
- `content/file/files`
- `distributions/file/file`
- `publications/file/file`
- `remotes/file/file`
- `repositories/file/file`
- `repositories/file/file/versions`

This document describes the default access policies shipped with Pulp File. Each of the above
policies can be modified to achieve a different RBAC behavior. Use the Pulp CLI to follow along
with the examples here.

!!! note
This feature is currently in tech preview and is subject to change in future releases.


!!! note
Customizing the access policy will cause any future changes to the default policies, like
statement changes and bugfixes, to be ignored unless reset to the default policy.


## Default Roles

Pulp File ships with three default roles baked into each viewset, except for File Content and File
Repository Versions, that can be assigned to users for simple RBAC needs. The three roles for each
viewset are Creator, Viewer, and Owner. Roles can be assigned at the model or object level for each
user and group. Roles at the model will give the user/group permissions across all objects the role
covers. Roles at the object level will restrict the permissions to a particular instance of the
object.

### Creator Role

The Creator role contains just the `add` permission for that viewset's object, e.g. File
Repository's Creator role:

=== "Show Creator Role"

```bash
pulp role show --name "file.filerepository_creator"
```

=== "Output"

```json
{
"pulp_href": "/pulp/api/v3/roles/ee3d368e-46da-430a-97bc-fbd5d207ebf3/",
"pulp_created": "2022-03-23T21:13:24.183866Z",
"name": "file.filerepository_creator",
"description": null,
"permissions": [
"file.add_filerepository"
],
"locked": true
}
```

Only users with the `add` permission can create objects for that viewset. This role should always
be used as a model level role as it makes no sense for it to be assigned at the object level. Some
viewset actions will also require the user to have additional permissions for related parameters
on the object's creation. An example would be needing to have the `view` permission for remotes
attached to a repository:

```json
"statements": [
...
{
"action": [
"create"
],
"effect": "allow",
"condition": [
"has_model_perms:file.add_filerepository",
"has_remote_param_model_or_obj_perms:file.view_fileremote"
],
"principal": "authenticated"
},
...
],
```

### Viewer Role

The Viewer role contains just the `view` permission for that viewset's object, e.g. File Remote's
Viewer role:

=== "Show Viewer Role"

```bash
pulp role show --name "file.fileremote_viewer"
```

=== "Output"

```json
{
"pulp_href": "/pulp/api/v3/roles/d3bedaa3-4ffc-46d2-b4a5-6bc205f060dd/",
"pulp_created": "2022-03-23T21:13:24.176520Z",
"name": "file.fileremote_viewer",
"description": null,
"permissions": [
"file.view_fileremote"
],
"locked": true
}
```

Having the `view` permission allows the user to see and read the object when performing list and
show operations on the viewset. Pulp File performs queryset scoping on the viewsets based off this
permission, which limits the objects a user can see and interact with. Users that have this role
at the model level will be able to see all of the viewset's objects in Pulp. Assigning this role
only at the object level allows you to select what the user can see.

```bash
# Allow alice to see every File publication
pulp user role-assignment add --role "file.filepublication_viewer" --username "alice" --object ""
# Allow bob to see just the publication in $PUB_HREF
pulp user role-assignment add --role "file.filepublication_viewer" --username "bob" --object "$PUB_HREF"
# Alternative to previous command, allows for specifying multiple users & groups
pulp file publication role add --role "file.filepublication_viewer" --user "bob" --user "charlie" --group "fighters" --href "$PUB_HREF"
```

### Owner Role

The Owner role contains all of the permissions available for that viewset's objects besides the
`add` permission, e.g. File ACS's Owner role:

=== "Show Owner Role"

```bash
pulp role show --name "file.filealternatecontentsource_owner"
```

=== "Output"

```json
{
"pulp_href": "/pulp/api/v3/roles/7e17ae48-8a9f-49c4-a248-83b397c6a5e6/",
"pulp_created": "2022-03-23T21:13:24.087395Z",
"name": "file.filealternatecontentsource_owner",
"description": null,
"permissions": [
"file.change_filealternatecontentsource",
"file.delete_filealternatecontentsource",
"file.manage_roles_filealternatecontentsource",
"file.refresh_filealternatecontentsource",
"file.view_filealternatecontentsource"
],
"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 will also contain
permissions for any additional action that can be performed on that viewset, for example `sync`
and `modify` permissions for File Repository. Having this role at model level will allow a user
to perform any action on any of the viewset's objects. This role is added by default to a user,
at the object level, upon object creation.

=== "Create a remote and show the added role"

```bash
# alice has creator role for File remote
pulp --username "alice" file remote create --name "foo" --url "$FIXTURE_URL"
# alice now has the owner role for the created remote
pulp file remote role list --name "foo"
```
=== "Output"

```json
{
"roles": [
{
"role": "file.fileremote_owner",
"users": [
"alice"
],
"groups": []
}
]
}
```

### Content and RepositoryVersions Permissions

File Content and RepositoryVersions are unique as they do not have any default roles on their
viewsets. Content's access policy allows any authenticated user to create file content, however
they must specify the repository to upload to since viewing content is scoped by the repositories
the user has permission for. RepositoryVersions' access policy requires the user to have
permissions on the parent repository in order to perform actions on the repository version. Both
objects have CRD permissions in the database that can be assigned to users, but currently their
access policies do not use them for authorization.

## Creating New Roles

The default roles shipped in Pulp File are locked roles. This means they can not be edited or
deleted. If they are not sufficient for your RBAC use cases, you can create custom roles that can
be assigned to users and groups. The example below shows how to create a role allowing one to
view multiple objects:

```bash
pulp role create --name "super_viewer" \
--permission "file.filealternatecontentsource_viewer" \
--permission "file.filedistribution_viewer" \
--permission "file.filepublication_viewer" \
--permission "file.fileremote_viewer" \
--permission "file.filerepository_viewer"

# Assign new role to alice
pulp user role-assignment add --username "alice" --role "super_viewer"
```

!!! note
You can only assigned roles at the object level if the role contains a permission for that
object.


## Editing File Access Policies

Each Pulp File access policy can be edited to be more or less lenient. They can also be customized
on role assignment upon object creation. By default each access policy will assign the default
Owner role upon object creation. See the example below for how to view the File Repository's access
policy and then update it to assign the new role:

```bash
# View File Repository's Access Policy
pulp access-policy show --viewset-name "repositories/file/file"

# Update File Repository's Creation Hooks
pulp access-policy update --href "$REPO_AP_HREF" \
--creation-hooks '[{"function": "add_roles", "parameters": {"roles": "super_viewer"}}]'
```

!!! note
Access polices can be reset to their default using the reset endpoint, e.g:
`pulp access-policy reset --href "$REPO_AP_HREF"`


!!! note
Admin users always bypass any authorization checks.

130 changes: 130 additions & 0 deletions pulp_file/staging_docs/user/guides/01-upload.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# Upload Content

The section shows how to upload content to Pulp.

## Create a Repository `foo`

=== "Create Repository"

```bash
pulp file repository create \
--name foo \
--autopublish
```

=== "Output"

```json
{
"pulp_href": "/pulp/api/v3/repositories/file/file/018db957-1997-78b9-a2db-7754434bdf12/",
"pulp_created": "2024-02-17T23:11:49.656603Z",
"versions_href": "/pulp/api/v3/repositories/file/file/018db957-1997-78b9-a2db-7754434bdf12/versions/",
"pulp_labels": {},
"latest_version_href": "/pulp/api/v3/repositories/file/file/018db957-1997-78b9-a2db-7754434bdf12/versions/0/",
"name": "foo",
"description": null,
"retain_repo_versions": null,
"remote": null,
"autopublish": true,
"manifest": "PULP_MANIFEST"
}
```

## Upload a file into `foo`

=== "Upload file"

```bash
pulp file content upload \
--repository foo \
--file ./testfile.txt \
--relative-path testfile.txt
```

=== "Output"

```bash
Started background task /pulp/api/v3/tasks/018db958-a002-7e7d-89a7-f30b0d4eb436/
.Done.
{
"pulp_href": "/pulp/api/v3/repositories/file/file/018db957-1997-78b9-a2db-7754434bdf12/versions/1/",
"pulp_created": "2024-02-17T23:13:29.787710Z",
"number": 1,
"repository": "/pulp/api/v3/repositories/file/file/018db957-1997-78b9-a2db-7754434bdf12/",
"base_version": null,
"content_summary": {
"added": {
"file.file": {
"count": 1,
"href": "/pulp/api/v3/content/file/files/?repository_version_added=/pulp/api/v3/repositories/file/file/018db957-1997-78b9-a2db-7754434bdf12/versions/1/"
}
},
"removed": {},
"present": {
"file.file": {
"count": 1,
"href": "/pulp/api/v3/content/file/files/?repository_version=/pulp/api/v3/repositories/file/file/018db957-1997-78b9-a2db-7754434bdf12/versions/1/"
}
}
}
}
```

## Create a Distribution for 'foo'

=== "Create Distribution"

```bash
pulp file distribution create \
--name foo_latest \
--repository file:file:foo \
--base-path file/foo
```

=== "Output"

```bash
Started background task /pulp/api/v3/tasks/018db95a-5685-73bb-92f0-b2549483888a/
Done.
{
"pulp_href": "/pulp/api/v3/distributions/file/file/018db95a-57a6-7f31-9d53-43f277664407/",
"pulp_created": "2024-02-17T23:15:22.151052Z",
"base_path": "file/foo",
"base_url": "http://localhost:5001/pulp/content/file/foo/",
"content_guard": null,
"hidden": false,
"pulp_labels": {},
"name": "foo_latest",
"repository": "/pulp/api/v3/repositories/file/file/018db957-1997-78b9-a2db-7754434bdf12/",
"publication": null
}
```

## Check Distribution

=== "Get "

```bash
http http://localhost:5001/pulp/content/file/foo/
```

=== "Output"

```sh
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 501
Content-Type: text/html
Date: Sat, 17 Feb 2024 23:17:45 GMT
Server: nginx/1.22.1

<html>
<head><title>Index of /pulp/content/file/foo/</title></head>
<body bgcolor="white">
<h1>Index of /pulp/content/file/foo/</h1>
<hr><pre><a href="../">../</a>
<a href="PULP_MANIFEST">PULP_MANIFEST</a> 17-Feb-2024 23:13 81 Bytes
<a href="testfile.txt">testfile.txt</a> 17-Feb-2024 23:13 25 Bytes
</pre><hr></body>
</html>
```
0 .../user/guides/alternate-content-sources.md → ...er/guides/02-alternate-content-sources.md
View file
File renamed without changes.
17 changes: 17 additions & 0 deletions pulp_file/staging_docs/user/tutorials/00-overview.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Overview

This is the `pulp_file` Plugin for [Pulp Project
3.0+](https://pypi.org/project/pulpcore/). This plugin replaces the ISO support in the
`pulp_rpm` plugin for Pulp 2.

## Overview

A `pulp_file` repository consists of a list of arbitrary files, along with a `PULP_MANIFEST` file.
The `PULP_MANIFEST` consists of one line per file, each line with the format
`filename,sha256-checksum,size-in-bytes` . Pulp creates a PULP_MANIFEST when you [publish](site:/pulp_file/user/tutorials/02-publish-host.md)
a repository.

If you are setting up a directory that you wish to make available to Pulp to synchronize, it will need
to have its own `PULP_MANIFEST`. You can take advantage of the
[pulp-manifest tool](https://github.com/pulp/pulp-manifest/) to create one for you from an existing directory
of files to be served.
Loading

0 comments on commit b53f4bf

Please sign in to comment.