Migrate the documentation to staging

closes pulp#1517

CHANGES/1517.doc

@@ -0,0 +1,2 @@
+Migrated the whole documentation to staging. The documentation should be now consumed from the
+unified docs site.

pyproject.toml

@@ -39,6 +39,7 @@ ignore = [
     "dev_requirements.txt",
     "doc_requirements.txt",
     "docs/**",
+    "staging_docs/**",
     "template_config.yml",
     ".travis/**",
     ".travis.yml",

staging_docs/admin/guides/build-image.md

@@ -0,0 +1,52 @@
+# Build Images
+
+!!! warning
+
+    All container build APIs are in tech preview. Backwards compatibility when upgrading is not
+    guaranteed.
+
+Users can add new images to a container repository by uploading a Containerfile. The syntax for
+Containerfile is the same as for a Dockerfile. The same REST API endpoint also accepts a JSON
+string that maps artifacts in Pulp to a filename. Any artifacts passed in are available inside the
+build container at `/pulp_working_directory`.
+
+## Create a Repository
+
+```bash
+REPO_HREF=$(pulp container repository create --name building | jq -r '.pulp_href')
+```
+
+## Create an Artifact
+
+```bash
+echo 'Hello world!' > example.txt
+
+ARTIFACT_HREF=$(http --form POST http://localhost/pulp/api/v3/artifacts/ \
+    file@./example.txt \
+    | jq -r '.pulp_href')
+```
+
+## Create a Containerfile
+
+```bash
+echo 'FROM centos:7
+
+# Copy a file using COPY statement. Use the relative path specified in the 'artifacts' parameter.
+COPY foo/bar/example.txt /inside-image.txt
+
+# Print the content of the file when the container starts
+CMD ["cat", "/inside-image.txt"]' >> Containerfile
+```
+
+## Build an OCI image
+
+```bash
+TASK_HREF=$(http --form POST :$REPO_HREF'build_image/' containerfile@./Containerfile \
+artifacts="{\"$ARTIFACT_HREF\": \"foo/bar/example.txt\"}"  | jq -r '.task')
+```
+
+!!! warning
+
+    Non-staff users, lacking read access to the `artifacts` endpoint, may encounter restricted
+    functionality as they are prohibited from listing artifacts uploaded to Pulp and utilizing
+    them within the build process.

staging_docs/admin/guides/change-allowed-artifacts.md

@@ -0,0 +1,55 @@
+# Configure Supported OCI Types
+
+By default, the following list of media types is enabled in the Container Registry:
+
+* OCI images
+* Helm
+* Cosign, SBOMs, attestations
+* Source containers
+* Singularity
+* Conftest policies
+* WASM
+
+For any other OCI media type that is not supported by default, you can add them to the
+`ADDITIONAL_OCI_ARTIFACT_TYPES` setting using the following format:
+
+```
+ADDITIONAL_OCI_ARTIFACT_TYPES = {
+   "<oci config type 1>": [
+       "<oci layer type A>",
+       "<oci layer type B>",
+   ],
+   "<oci config type 2>": [
+       "<oci layer type C>",
+       "<oci layer type D>",
+   ],
+}
+```
+
+For example, you can add support for custom defined mediatype by adding the following to your
+`ADDITIONAL_OCI_ARTIFACT_TYPES` setting:
+
+```
+ADDITIONAL_OCI_ARTIFACT_TYPES = {
+   "<oci config type 1>": [
+       "<oci layer type A>",
+       "<oci layer type B>",
+   ],
+   "<oci config type 2>": [
+       "<oci layer type C>",
+       "<oci layer type D>",
+   ],
+   "application/vnd.guardians.groot.config.v1+json": [
+       "text/plain",
+       "application/vnd.guardians.groot.docs.layer.v1+tar",
+   ],
+}
+
+```
+
+!!! note
+
+    When adding OCI media types that are not configured by default, it is necessary then to manually add
+    the `Default oci types<default-oci-types>` to the list.
+    The OCI image-spec types are supported by default, they are built-in and cannot be disabled, it is
+    not necessary to add them manually to the list.

staging_docs/admin/guides/customize-access-policy.md

@@ -0,0 +1,20 @@
+# Customize Access Policies
+
+The plugin is shipped with default access policies that can be modified to achieve different RBAC
+behaviour. Administrators can update creation hooks accordingly:
+
+```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.
+
+Visit [Role-based Access Control](site:pulp_container/docs/admin/learn/rbac) to learn more about
+access policies.

staging_docs/admin/guides/customize-roles.md

@@ -0,0 +1,17 @@
+# Customize 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:
+
+```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 ""
+```
+
+Visit [Role-based Access Control](site:pulp_container/docs/admin/learn/rbac) to learn more about roles.

staging_docs/admin/guides/import-export.md

@@ -0,0 +1,70 @@
+# Export and Import Images
+
+When maintaining an **air-gapped** environment, one can benefit from using the import/export
+machinery. A common workflow usually resembles the following steps:
+
+1. **An administrator exports Pulp's content on a system with the internet connectivity.** The
+   system runs a Pulp instance that syncs content from remote repositories.
+2. **The exported content (tarball) is moved to another (air-gapped) system.** The transfer can
+   be made through the intranet or via an external hard drive.
+3. **The administrator imports the exported content by initiating an import task.** The
+   procedure takes care of importing the content to another Pulp instance running in the air-gapped
+   environment.
+
+## Exporting a Repository
+
+To export a repository, run the following set of commands:
+
+```bash
+podman pull ghcr.io/pulp/test-fixture-1:manifest_a
+
+# push a tagged image to the registry
+podman login ${REGISTRY_ADDR} -u admin -p password --tls-verify=false
+podman tag ghcr.io/pulp/test-fixture-1:manifest_a \
+  ${REGISTRY_ADDR}/test/fixture:manifest_a
+podman push ${REGISTRY_ADDR}/test/fixture:manifest_a --tls-verify=false
+
+# a repository of the push type is automatically created
+REPOSITORY_HREF=$(pulp container repository -t push show \
+  --name "test/fixture" | jq -r ".pulp_href")
+
+# export the repository to the directory '/tmp/exports/test-fixture'
+EXPORTER_HREF=$(http ${BASE_ADDR}/pulp/api/v3/exporters/core/pulp/ \
+  name=both repositories:="[\"${REPOSITORY_HREF}\"]" \
+  path=/tmp/exports/test-fixture | jq -r ".pulp_href")
+```
+
+If the exported content is no longer needed to be managed on the system, delete it:
+
+```bash
+pulp container distribution destroy --name "test/fixture"
+pulp orphan cleanup --protection-time 0
+```
+
+## Importing the Repository
+
+Import the exported content by running the next commands and monitor the task:
+
+```bash
+http ${BASE_ADDR}/pulp/api/v3/repositories/container/container/ \
+  name="test/fixture" | jq -r ".pulp_href"
+
+# import the exported repository stored in '/tmp/exports/test-fixture'
+IMPORTER_HREF=$(http ${BASE_ADDR}/pulp/api/v3/importers/core/pulp/ \
+  name="test/fixture" | jq -r ".pulp_href")
+EXPORTED_REPO_PATH=$(find "/tmp/exports/test-fixture" -type f -name \
+  "*.tar.gz" | head -n 1)
+GROUP_HREF=$(http ${BASE_ADDR}${IMPORTER_HREF}imports/ \
+  path=${EXPORTED_REPO_PATH} | jq -r ".task_group")
+```
+
+!!! note
+
+    Pass `create_repositories=True` to the `http POST ${BASE_ADDR}${IMPORTER_HREF}imports/`
+    request to tell Pulp to create missing repositories during the import procedure on the fly.
+    Otherwise, the repositories need to be created ahead of the import.
+
+
+!!! warning
+
+    Repositories of the push type are automatically converted to sync repositories at import time.

staging_docs/admin/guides/migrate-permissions.md

@@ -0,0 +1,43 @@
+# Migrate from Permissions to Roles
+
+As of release 2.11.0, the plugin started to support roles instead of separate groups and
+permissions. Default 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:
+
+```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`:
+
+```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.
+
+!!! note
+
+    As of release 2.13.0, administrators should use the `pulpcore-manager dump-permissions`
+    command to list deprecated permissions not yet translated into roles.

staging_docs/admin/guides/pull-through-caching.md

@@ -0,0 +1,49 @@
+# Configure Pull-Through Caching
+
+!!! warning
+
+    This feature is provided as a tech preview and could change in backwards incompatible
+    ways in the future.
+
+The Pull-Through Caching feature offers an alternative way to host content by leveraging a **remote
+registry** as the source of truth. This eliminates the need for in-advance repository
+synchronization because Pulp acts as a **caching proxy** and stores images, after they have been
+pulled by an end client, in a local repository.
+
+## Configuring the caching:
+
+```
+# initialize a pull-through remote (the concept of upstream-name is not applicable here)
+REMOTE_HREF=$(http ${BASE_ADDR}/pulp/api/v3/remotes/container/pull-through/ name=docker-cache url=https://registry-1.docker.io | jq -r ".pulp_href")
+
+# create a pull-through distribution linked to the initialized remote
+http ${BASE_ADDR}/pulp/api/v3/distributions/container/pull-through/ remote=${REMOTE_HREF} name=docker-cache base_path=docker-cache
+```
+
+Pulling content:
+
+```
+podman pull localhost:24817/docker-cache/library/busybox
+```
+
+In the example above, the image "busybox" is pulled from *DockerHub* through the "docker-cache"
+distribution, acting as a transparent caching layer.
+
+By incorporating the Pull-Through Caching feature into standard workflows, users **do not need** to
+pre-configure a new repository and sync it to facilitate the retrieval of the actual content. This
+speeds up the whole process of shipping containers from its early management stages to distribution.
+Similarly to on-demand syncing, the feature also **reduces external network dependencies**, and
+ensures a more reliable container deployment system in production environments.
+
+!!! note
+
+    During the pull-through operation, Pulp creates a local repository that maintains a single
+    version for pulled images. For instance, when pulling an image like "debian:10," a local
+    repository named "debian" with the tag "10" is created. Subsequent pulls, such as "debian:11,"
+    generate a new repository version that incorporates both the "10" and "11" tags, automatically
+    removing the previous version. Repositories and their content remain manageable through standard
+    Pulp API endpoints. The repositories are read-only and public by default.
+
+A registry may contain several repositories which hold collections of multiple images. Each
+repository is identified by its unique name. The list of names of all distributed repositories
+is made available through the `_catalog` endpoint.