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 2b1e51d is available at theforeman-foreman-documentation-preview-pr-4905.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

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. 👍

vsedmik · 2026-06-04T13:45:02Z

+ifdef::containerized[]
+. Add the parent folder to allowed import paths:
+
+[options="nowrap", subs="+quotes,attributes"]
+----
+# {foremanctl} deploy --content-import-path /var/lib/pulp/__local_repos__
+----
+endif::[]


This is probably not the only part that needs update in this chapter for the containerized SAT, the preceding foreman-maintain will need an update too.

Looking at the satellite-maintain instructions above makes me wonder if they're even correct right now. Line 30 is telling users to use satellite-maintain packages after unlocking package management, and that doesn't seem right (https://github.com/theforeman/foreman-documentation/blob/master/guides/common/modules/ref_managing-packages-on-the-base-operating-system.adoc).

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:42:32Z

+To configure additional paths, use `ALLOWED_EXPORT_PATHS` in `/etc/pulp/settings.py`.
+endif::[]
+ifdef::containerized[]
+The default export path is `/var/lib/pulp/exports/`.


line 5 and 9 are identical, you could move this line below line 3.

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.

aneta-petrova added 2 commits June 4, 2026 08:42

Update Pulp import/export paths for foremanctl

65c732c

Document configuring export paths

2b1e51d

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

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

maximiliankolb reviewed Jun 5, 2026

View reviewed changes

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document foremanctl impact on Pulp import/export paths#4905

Document foremanctl impact on Pulp import/export paths#4905
aneta-petrova wants to merge 2 commits into
theforeman:masterfrom
aneta-petrova:foremanctl-pulp-import-export-path

aneta-petrova commented Jun 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 4, 2026

Uh oh!

aneta-petrova commented Jun 4, 2026

Uh oh!

vsedmik left a comment

Uh oh!

vsedmik Jun 4, 2026

Uh oh!

aneta-petrova Jun 4, 2026

Uh oh!

maximiliankolb left a comment

Uh oh!

maximiliankolb Jun 5, 2026

Uh oh!

maximiliankolb commented Jun 5, 2026

Uh oh!

ekohl left a comment

Uh oh!

ekohl Jun 5, 2026 •

edited

Loading

Uh oh!

ekohl Jun 5, 2026

Uh oh!

ekohl Jun 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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

Uh oh!

aneta-petrova commented Jun 4, 2026

Uh oh!

vsedmik left a comment

Choose a reason for hiding this comment

Uh oh!

vsedmik Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

aneta-petrova Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

maximiliankolb Jun 5, 2026

Choose a reason for hiding this comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aneta-petrova commented Jun 4, 2026 •

edited

Loading

ekohl Jun 5, 2026 •

edited

Loading