Document foremanctl impact on Pulp import/export paths by aneta-petrova · Pull Request #4905 · theforeman/foreman-documentation

aneta-petrova · 2026-06-04T06:53:47Z

What changes are you introducing?

Updating existing information on allowed import paths for foremanctl
Adding a snippet with information on export paths

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

theforeman/foremanctl#455
https://github.com/theforeman/foremanctl/blob/744ba31fd0ee4e4a74eef97e2c705acca1b2961d/src/roles/pulp/defaults/main.yaml#L29-L30
theforeman/foremanctl#445

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Assisted-by: Cursor

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.19/Katello 4.21
Foreman 3.18/Katello 4.20 (Satellite 6.19)
Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6, 7.7, and 7.8)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
We do not accept PRs for Foreman older than 3.12.

github-actions · 2026-06-04T06:57:55Z

The PR preview for 40cc4da is available at theforeman-foreman-documentation-preview-pr-4905.surge.sh

No diff compared to the current base

show diff

aneta-petrova · 2026-06-04T07:05:31Z

Hi @aidenfine, can you please take a look at this PR and let me know if you think these are the changes needed to cover theforeman/foremanctl#455?

Note that the preview links in #4905 (comment) include containerized and non-containerized docs preview builds. So for example to review the foremanctl changes, the right HTML builds to look at would be mainly https://theforeman-foreman-documentation-preview-pr-4905.surge.sh/nightly/Managing_Content/index-containerized-katello.html.

vsedmik

Left one note bellow which is going to be addressed by another PR I have been told, so ACK here, looks good to me. 👍

maximiliankolb

Two minor suggestion, overall LGTM style-wise.

I also suggest to swap the order in the snippet file name:

$ fd snip_ | rg prereq
guides/common/modules/snip_prerequisite-activation-key-available.adoc
guides/common/modules/snip_prerequisite-configured-smart-proxy-registration-provisioning.adoc
guides/common/modules/snip_prerequisite-networking-for-provisioning.adoc
guides/common/modules/snip_prerequisite-project-client-repository-ak.adoc
guides/common/modules/snip_prerequisite-project-client-repository-enabled.adoc
guides/common/modules/snip_prerequisite-repositories-with-oscap.adoc
guides/common/modules/snip_prerequisites-common-compute-resource.adoc
guides/common/modules/snip_prerequisites-configuring-smartproxyservers-for-load-balancing.adoc
guides/common/modules/snip_prerequisites-deploying-ca-cert-rex.adoc
guides/common/modules/snip_registering-a-host-prerequisites.adoc

So maybe "snip_prerequisite-allowed-export-paths.adoc`.

maximiliankolb · 2026-06-05T06:48:57Z

Tech wise, I think that foreman-installer can already configure those paths in some cases, so I would appreciated it someone double-checked this:

# foreman-installer --full-help | grep -i import
    --foreman-proxy-puppet                                                               Enable Puppet module for environment imports and Puppet runs (current: true)
    --foreman-proxy-content-pulpcore-additional-import-paths                             Additional allowed paths that Pulpcore can use for content imports, or sync from using file:// protocol (current: [])
    --reset-foreman-proxy-content-pulpcore-additional-import-paths                       Reset pulpcore_additional_import_paths to the default value ([])
    --foreman-proxy-content-pulpcore-import-workers-percent                              What percentage of available-workers will pulpcore use for import tasks at a time (current: UNDEF)
    --reset-foreman-proxy-content-pulpcore-import-workers-percent                        Reset pulpcore_import_workers_percent to the default value (UNDEF)
# foreman-installer --full-help | grep -i export
    --foreman-proxy-content-pulpcore-additional-export-paths                             Additional allowed paths that Pulpcore can use for content exports (current: [])
    --reset-foreman-proxy-content-pulpcore-additional-export-paths                       Reset pulpcore_additional_export_paths to the default value ([])

Tested on Foreman 3.18/Katello 4.20.

ekohl

Please keep the installer and foremanctl commands in sync as much as possible. I realize it was already wrong before, but this is a good opportunity to fix it. Note that users who manually modify settings.py will lose the value on the next installer run and we also can't migrate them from non-containerized to containerized. For that latter part is exactly why we maintain the parameter mapping.

ekohl · 2026-06-05T08:32:58Z

+* The syncable exports must be located in one of your allowed import paths.
+ifndef::containerized[]
+The default import path is `/var/lib/pulp/imports/`.
+To configure additional paths, use `ALLOWED_IMPORT_PATHS` in `/etc/pulp/settings.py`.


Users should never modify settings.py themselves. Even with satellite-installer. Users can use {foreman-installer} --foreman-proxy-content-pulpcore-additional-import-paths $path to add additional paths. Looks like this bug was originally introduced in 1afa311.

Note that in https://github.com/theforeman/foremanctl/blob/master/docs/user/parameters.md#mapped we document this parameter mapping.

ekohl · 2026-06-05T08:34:55Z

-By default, this includes `/var/lib/pulp/imports/`.
+* The syncable exports must be located in one of your allowed import paths.
+ifndef::containerized[]
+The default import path is `/var/lib/pulp/imports/`.


Not quite true: https://github.com/theforeman/puppet-foreman_proxy_content/blob/9f441f35d1a403f7576aa2845353c2d6d40246f9/manifests/init.pp#L151-L161 shows the logic. On content proxies (downstream: Capsule) it's /var/lib/pulp/sync_imports while on the main server (downstream: Satellite) it's both /var/lib/pulp/sync_imports and /var/lib/pulp/imports.

ekohl · 2026-06-05T08:40:15Z

+* Exports are written to one of your allowed export paths.
+ifndef::containerized[]
+The default export path is `/var/lib/pulp/exports/`.
+To configure additional paths, use `ALLOWED_EXPORT_PATHS` in `/etc/pulp/settings.py`.


Similar to above: please use --foreman-proxy-content-pulpcore-additional-export-paths. It's also odd that it mentions --content-export-path doesn't have an existing entry while --foreman-proxy-content-pulpcore-additional-export-paths exists for that.

aidenfine · 2026-06-12T14:11:26Z

Hi @aidenfine, can you please take a look at this PR and let me know if you think these are the changes needed to cover theforeman/foremanctl#455?

Note that the preview links in #4905 (comment) include containerized and non-containerized docs preview builds. So for example to review the foremanctl changes, the right HTML builds to look at would be mainly https://theforeman-foreman-documentation-preview-pr-4905.surge.sh/nightly/Managing_Content/index-containerized-katello.html.

Sorry for late reply. I would agree with what @ekohl is saying.

aneta-petrova · 2026-06-12T15:00:13Z

The Unused modules failure is probably due to https://github.com/theforeman/foreman-documentation/pull/4899/changes having been merged: Because the containerized guide's preview is empty, the new module seems unused. And it is unused right now, but won't be when we start exposing and publishing the containerized contents.

aneta-petrova · 2026-06-12T15:05:01Z

The Unused modules failure is probably due to https://github.com/theforeman/foreman-documentation/pull/4899/changes having been merged: Because the containerized guide's preview is empty, the new module seems unused. And it is unused right now, but won't be when we start exposing and publishing the containerized contents.

By the way, this is also the reason why the diff in #4905 (comment) is empty, so to review this type of change, there is no preview and looking at the changed lines should be enough.

aneta-petrova · 2026-06-12T15:10:51Z

Hi @aidenfine and/or @ekohl, can you please re-review?

pr-processor Bot added the Not yet reviewed label Jun 4, 2026

github-actions Bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Jun 4, 2026

aneta-petrova changed the title ~~Foremanctl pulp import export path~~ Document foremanctl impact on Pulp import/export paths Jun 4, 2026

vsedmik approved these changes Jun 4, 2026

View reviewed changes

Comment thread guides/common/modules/proc_creating-a-local-source-for-a-custom-file-type-repository.adoc

pr-processor Bot removed the Not yet reviewed label Jun 4, 2026

maximiliankolb reviewed Jun 5, 2026

View reviewed changes

Comment thread guides/common/modules/snip_allowed-export-paths-prerequisite.adoc

ekohl requested changes Jun 5, 2026

View reviewed changes

pr-processor Bot added the Waiting on contributor Requires an action from the author label Jun 5, 2026

aneta-petrova added 2 commits June 12, 2026 16:24

Update Pulp import/export paths for foremanctl

dc5a5f8

Document configuring export paths

01a5f7a

aneta-petrova force-pushed the foremanctl-pulp-import-export-path branch from 2b1e51d to 01a5f7a Compare June 12, 2026 14:24

pr-processor Bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Jun 12, 2026

aneta-petrova force-pushed the foremanctl-pulp-import-export-path branch from 80225ea to 92cda25 Compare June 12, 2026 14:47

Revert changes to existing docs

40cc4da

aneta-petrova force-pushed the foremanctl-pulp-import-export-path branch from 92cda25 to 40cc4da Compare June 12, 2026 14:47

aneta-petrova added testing done No issues from the functional perspective and removed Needs testing Requires functional testing labels Jun 12, 2026

Conversation

aneta-petrova commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Uh oh!

github-actions Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aneta-petrova commented Jun 4, 2026

Uh oh!

vsedmik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maximiliankolb commented Jun 5, 2026

Uh oh!

ekohl left a comment

Choose a reason for hiding this comment

Uh oh!

ekohl Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ekohl Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

ekohl Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

aidenfine commented Jun 12, 2026

Uh oh!

aneta-petrova commented Jun 12, 2026

Uh oh!

aneta-petrova commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aneta-petrova commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aneta-petrova commented Jun 4, 2026 •

edited

Loading

github-actions Bot commented Jun 4, 2026 •

edited

Loading

ekohl Jun 5, 2026 •

edited

Loading

aneta-petrova commented Jun 12, 2026 •

edited

Loading