Plugin Concepts

Like the Pulp Core itself, all Pulp Plugins are Django Applications, and could be created like any other Django app with django-admin startapp <your_plugin>. However, instead of writing all of the boilerplate yourself, it is recommmended that you start your plugin by utilizing the Plugin Template. This guide will assume that you have used the plugin_template, but if you are interested in the details of what it provides you, please see Plugin Django Application for more information for how plugins are “discovered” and connected to the pulpcore Django app. Additional information is given as inline comments in the template.

Plugin API Usage

Plugin Applications interact with pulpcore with two high level interfaces, subclassing and adding tasks. Additionally, plugins that need to implement dynamic web APIs can optionally provide their own Django views. See our Live APIs page for more information.

Subclassing

Pulp Core and each plugin utilize Django and the Django Rest Framework. Each plugin provides Models, Serializers, and Viewsets. For each object that a plugin writer needs to make, the pulpcore.plugin API provides base classes. These base classes handle most of the boilerplate code, resulting in CRUD for each object out of the box.

• Models
  • Adding Model Fields
  • Uniqueness
  • ForeignKey Gotchas
• Serializers
  • Adding Fields
• Viewsets
  • Endpoint Namespacing
  • Detail Routes (Extra Endpoints)

Tasks

Any action that can run for a long time should be an asynchronous task. Plugin writers do not need to understand the internals of the pulpcore tasking system, workers automatically execute tasks from RQ, including tasks deployed by plugins.

Reservations

The tasking system adds a concept called reservations which ensures that actions that act on the same resources are not run at the same time. To ensure data correctness, any action that alters the content of a repository (thus creating a new version) must be run asynchronously, locking on the repository and any other models which cannot change during the action. For example, sync tasks must be asynchronous and lock on the repository and the remote. Publish should lock on the repository version being published as well as the publisher.

Deploying Tasks

Tasks are deployed from Views or Viewsets, please see Kick off Tasks.

• Adding and Removing Content
  • Repository Versions
  • Synchronizing
• Publish
• Export Task

Sync Pipeline

• Synchronizing Repositories with the async-Pipeline
  • On-demand synchronizing
  • Multiple level discovery

Content Protection

Users can configure a ContentGuard to protect a Distribution on their own, but some plugins want to offer built-in content protection features. For example pulp_docker may only want a user to download docker images they have rights to based on some permissions system pulp_docker could provide.

For more information see the ContentGuard Usage by Plugin Writers documentation.

Plugin Settings

Plugins can define settings by creating a <your plugin>.app.settings module containing settings as you would define in the Django Settings File itself. pulpcore ships the actual settings.py file so settings cannot be added directly as with most Django deployments. Instead as each plugin is loaded, pulpcore looks for the <your plugin>.app.settings module and uses dynaconf to overlay the settings on top of pulpcore’s settings and user provided settings.

Settings are parsed in the following order with later settings overwriting earlier ones:

1. Settings from /etc/pulp/settings.py.

2. Settings from pulpcore.app.settings (the pulpcore provided settings defaults).

3. Plugin settings from <your plugin>.app.settings.

In some cases a setting should not overwrite an existing setting, but instead add to it. For example, consider adding a custom log handler or logger to the LOGGING settings. You don’t want to fully overwrite it, but instead add or overwrite only a sub-portion. dynaconf provides the dynaconf_merge feature which is for merging settings instead of overwriting them. For example, pulp_ansible makes use of this here.