Enable and create Domains¶
Warning
This feature requires plugin support to work correctly.
Warning
This feature is provided as a tech preview and could change in backwards incompatible ways in the future.
Overview¶
Domains are an optional feature that enables one sort of multi-tenancy in Pulp. Enabling domains allows multiple tenants to use the same Pulp instance in a safe and isolated manner, without worry that other users can modify or interfere with your workflows. Each domain acts as a unique namespace for that user and their Pulp objects, completely isolated from the other domains. To this end each domain can be customized to use their own storage backend to store their artifacts and content, ensuring each user has complete control over the content they manage in Pulp.
Domains are meant for Pulp admins that need more multi-tenancy abilities than are provided through current RBAC features. Domains help greatly when multiple, but distinctly separate tenants are sharing the same Pulp instance without having to resort to creating multiple Pulp instances. See RBAC Overview for Pulp's RBAC capabilities if you are unsure what Pulp's RBAC can currently do. However domains are not necessarily a replacement for RBAC.
Enabling Domains¶
Domains are off by default and can be enabled by setting DOMAIN_ENABLED = True
in your settings file and restarting Pulp.
In order to enable domains, each installed plugin needs to be domain compatible.
If an installed plugin is not compatible Pulp will fail to start.
See list below for current list of plugins with domain compatibility.
Once domains are enabled all current objects in Pulp will be found under the default
domain.
Warning
Before turning on domains in an existing system, you should completely drain the task queue of all running or waiting tasks.
Creating Domains¶
Domains have three important fields:
a unique name
, the backend storage class
and the storage settings
for the storage backend.
See Storage documentation to see available storage backends and settings.
The domain name must be unique and is used in the URL path after the API_ROOT
, e.g. /pulp/my_domain_name/api/v3/
.
You can also customize the content app behavior for your domain through the fields redirect_to_object_storage
and hide_guarded_distributions
.
See settings for more details on these.
pulp domain create \
--name <domain_name> \
--storage-class <storage_class> \
--storage-settings <storage_settings>
Specific examples for different storage backends:
pulp domain create \
--name foo \
--description foo \
--storage-class pulpcore.app.models.storage.FileSystem \
--storage-settings "{\"MEDIA_ROOT\": \"/var/lib/pulp/media/\"}"
pulp domain create \
--name mydomain \
--storage-class storages.backends.s3boto3.S3Boto3Storage \
--storage-settings "{\"access_key\": \"AcVDppUlVkA6\", \"secret_key\": \"SFviCmMfRT6N\", \"bucket_name\": \"my-unique-bucket-name\", \"region_name\": \"us-east-1\", \"default_acl\": \"private\"}"
Note
default
, content
, and api
are reserved names that can not be used during creation or update.
The default
domain can not be updated or deleted.
Note
To delete a domain all objects within that domain must be deleted first, including artifacts and orphaned content.
Note
The AWS access key must be authorized to perform the s3:ListBucket
and s3:PutObject
operations.
Warning
Changing the storage-class
or storage-settings
of an in-use domain is dangerous and can result in a broken domain.
TODO Migration feature
Using Domains¶
Once domains are enabled all URLs in Pulp will require the domain name in the path after the API_ROOT
for the Pulp API,
e.g. /pulp/my_domain_name/api/v3/
, or after the CONTENT_PATH_PREFIX
for the Content App, e.g. /pulp/content/my_domain_name/
.
Objects present in Pulp before enabling domains will now be present under the default
domain.
To work in a domain you must specify the domain's name in the URL.
# List repositories in 'test' domain
pulp --domain test repository list
# Create a File Repository 'foo' in 'foo' domain
pulp --domain foo file repository create --name foo
# Create a File Repository 'foo' in 'boo' domain (Possible because of separate domains)
pulp --domain boo file repository create --name foo
# See Exposed Distributions in 'default' domain
pulp distribution list
Domains are isolated from each other and perform their own deduplication and uniqueness checks within their domain. Therefore multiple domains can each have their own repository named 'foo'; a capability not available without domains as repository names were unique within a Pulp system, but are now unique within a domain. This also means that content and artifact deduplication is no longer system wide, but instead performed at the domain level. Since domains can each have their own unique storage backend, duplicate content across domains could be stored in multiple locations. Also for separating tenants, it would be inappropriate to try to deduplicate across domains.
Most all Pulp objects and operations work the same within their domain. Uploading, syncing, publishing, and distributing workflows are all supported with domains. Objects are scoped to their domain and will not appear in other domains even if you have permissions on those domains. Plugins that support RBAC will now also have access to a new permission level on the domain. Assigning a role at the domain-level will allow users to operate with those permissions only within that domain. Current global(model)-level roles should be converted to domain-level if you wish for the user to not have permission across all domains.
# Delete the global-level role
pulp user role-assignment remove --username <username> --role <role_name> --object ""
# Assign the role at the domain-level
pulp user role-assignment add --username <username> --role <role_name> --domain <domain_href>
Note
Operations on resources across separate domains is not allowed. e.g. You can not add content from one domain to the repository of another domain even if you own both domains.
Warning
Pulp Export and Import are currently not supported with domains enabled.
There are notable objects in Pulp like Roles
, Users
, and Groups
, that are not a part of domains and remain global across the system.
These objects are closely intertwined with the RBAC system and currently do not make sense to be unique on the domain level.
Objects that are not a part of a domain are readable from any domain (with the correct permissions),
but are only operable on within the default
domain, i.e. Roles
can be read from any domain, but can only be created from the default
domain.