Skip to content

Add new build target for foremanctl #4506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
+47 −41
Draft

Add new build target for foremanctl #4506

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7946467
Introduce 'foremanctl' as a new flavour
aneta-petrova Nov 28, 2025
6386d76
Add foremanctl to web navigation
aneta-petrova Nov 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ jobs:
make clean
make -j ${{ env.MAKE_J }} html BUILD=foreman-el
make -j ${{ env.MAKE_J }} html BUILD=foreman-deb
make -j ${{ env.MAKE_J }} html BUILD=foremanctl
make -j ${{ env.MAKE_J }} html BUILD=katello
make -j ${{ env.MAKE_J }} html BUILD=satellite
make -j ${{ env.MAKE_J }} html BUILD=orcharhino
Expand Down
2 changes: 1 addition & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ clean:
$(MAKE) -C guides/ clean
rm -rf $(DEST) web/output/

html: build-foreman-el build-foreman-deb build-katello
html: build-foreman-el build-foreman-deb build-foremanctl build-katello

build-%: FORCE prep
$(MAKE) -C guides/ html BUILD=$*
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ See the [README in the `guides/` subdirectory](guides/README.md) for more inform

To build both the static site and the guides for easy local testing, a global `Makefile` is provided in the root directory with the following targets:

* `html`: builds HTML guides with all contexts (`foreman-el`, `foreman-deb`, `katello`, `satellite`, and `orcharhino`)
* `html`: builds HTML guides with all contexts (`foreman-el`, `foreman-deb`, `foremanctl`, `katello`, `satellite`, and `orcharhino`)
* `web`: builds static site using the `nanoc` tool
* `compile`: compiles all content into a single directory `./result`
* `serve`: serves the result directory via a python web server (the default target)
Expand Down
Empty file added guides/common/attributes-foremanctl.adoc
View file
Open in desktop
Empty file.
4 changes: 4 additions & 0 deletions guides/common/attributes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
// Attribute files for SPECIFIC PRODUCTS:
// * attributes-foreman-el.adoc (attributes overridden or unique to Red Hat Enterprise Linux and clones)
// * attributes-foreman-deb.adoc (attributes overridden or unique to Debian/Ubuntu)
// * attributes-foremanctl.adoc (attributes overridden or unique to foremanctl build)
// * attributes-katello.adoc (attributes overridden or unique to Katello)
// * attributes-orcharhino.adoc (attributes overridden or unique to orcharhino)
// * attributes-satellite.adoc (attributes overridden or unique to Satellite)
Expand All @@ -37,6 +38,9 @@ ifeval::["{build}" == "foreman-deb"]
:foreman-deb:
:foreman:
endif::[]
ifeval::["{build}" == "foremanctl"]
:foremanctl:
Copy link
Member

@ekohl ekohl Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that I see this I'm wondering: initially we discussed a more feature flag idea. My idea was that we can modify the satellite flavor to also define foremanctl. Seeing this here makes me worried we'll break stuff. On the other hand, perhaps that's unfounded.

Testing that idea might require some real content to be in place.

Copy link
Member Author

@aneta-petrova aneta-petrova Nov 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please elaborate on how you think the satellite flavour could be made to also define foremanctl?

Copy link
Member

@ekohl ekohl Nov 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can add :foremanctl: to attributes-satellite.adoc to "flip" the feature on but that can have unintended consequences. That's what I had in my head as a theory and I'd love to come up with a way to test that theory though I doubt we can without filling up the foremanctl guide first.

Copy link
Member Author

@aneta-petrova aneta-petrova Nov 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't that effectively make foremanctl docs development downstream first?

As an alternative, in #4507 I'm looking into creating a new foremanctl target for each existing build target to get the ability to use a feature flag. It doesn't build but shows yet another alternative approach.

Copy link
Member

@ekohl ekohl Nov 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't that effectively make foremanctl docs development downstream first?

Maybe I wasn't clear. I was saying that we start building out the foremanctl flavor (build). Once downstream is ready, we "flip the switch" and also add the foremanctl attribute to the satellite flavor. And now I'm asking (out loud) if that is feasible. That doesn't mean the foremanctl flavor goes away in upstream because that's still a valid target. It just means that the satellite flavor will then be closer to the foremanctl flavor than the katello flavor.

Copy link
Member Author

@aneta-petrova aneta-petrova Nov 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suspect previewing the changes might be trickier with what you're suggesting. Also extending the single foremanctl build target from being satellite-compliant to being fit for any other build target.

In the meantime #4507 started building correctly. That approach shows a separate preview for each build target + flavor combination:

  • Foreman EL
  • Foreman Deb
  • Foreman + Katello
  • orcharhino
  • Satellite
  • Foreman EL and foremanctl
  • Foreman Deb and foremanctl
  • Foreman + Katello and foremanctl
  • orcharhino and foremanctl
  • Satellite and foremanctl

Then, once any existing build target goes into full foremanctl mode, we could just drop the pre-foremanctl build and replace it with the corresponding foremanctl build. So in a way, the same thing we intended to do when we created a separate foremanctl server installation guide (in #3975), with the intention of eventually replacing the pre-foremanctl guide with it (in #4087).

endif::[]
ifeval::["{build}" == "katello"]
:katello:
endif::[]
Expand Down
9 changes: 2 additions & 7 deletions guides/common/modules/proc_running-project-deployment-utility.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,7 @@
Install the required packages and run the {Project} deployment utility.

.Procedure
ifdef::foremanctl[]
[tabs]
====
Puppet-based installation::
endif::[]
ifndef::foremanctl[]
. Upgrade all packages:
+
[options="nowrap" subs="+quotes,attributes"]
Expand All @@ -36,8 +32,8 @@ The installation run is non-interactive by default.
The script displays its progress and writes logs to `{installer-log-file}`.
+
For a list of the available customization options, run `{foreman-installer} --help` or `{foreman-installer} --full-help`.
endif::[]
ifdef::foremanctl[]
Containerized installation::
. Upgrade all packages:
+
[options="nowrap" subs="+quotes,attributes"]
Expand All @@ -60,5 +56,4 @@ Containerized installation::
You can find credentials to access your {ProjectServer} in the message shown in the `TASK [post_install : Admin credentials]` task results.
+
For a list of available options, run `foremanctl --help`.
====
endif::[]
9 changes: 2 additions & 7 deletions guides/common/modules/ref_system-requirements-quickstart.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,7 @@

The following list shows the most critical requirements common for most scenarios.

ifdef::foremanctl[]
[tabs]
====
Puppet-based installation::
endif::[]
ifndef::foremanctl[]
// The requirements in this section must match the full requirements in the installation guide.
ifdef::foreman-deb[]
* The following operating systems are supported for deploying {Project}:
Expand All @@ -30,9 +26,9 @@ ifdef::foreman-el,katello,orcharhino[]
endif::[]
* Install {ProductName} on a freshly provisioned system that serves no other function except to run {ProductName}.
* Ensure the system has at least {project-minimum-cpus} and {project-minimum-memory} of memory.
endif::[]

ifdef::foremanctl[]
Containerized installation::
ifdef::foreman-deb[]
* The following operating systems are supported for deploying {Project}:
endif::[]
Expand All @@ -49,5 +45,4 @@ ifdef::foreman-deb[]
endif::[]
* Install {ProductName} on a freshly provisioned system that serves no other function except to run {ProductName}.
* Ensure the system has at least {project-minimum-cpus} and {project-minimum-memory} of memory.
====
endif::[]
16 changes: 0 additions & 16 deletions guides/common/modules/snip_configuring-repositories-el.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,3 @@
ifdef::foremanctl[]
[tabs]
====
Puppet-based installation::
endif::[]
. Clear any metadata:
+
[options="nowrap" subs="+quotes,attributes"]
Expand Down Expand Up @@ -40,14 +35,3 @@ ifdef::foreman-el,katello[]
# {package-install} https://yum.puppet.com/puppet7-release-el-{distribution-major-version}.noarch.rpm
----
endif::[]
ifdef::foremanctl[]
Containerized installation::
* Enable the required repositories:
+
[options="nowrap" subs="+quotes,attributes"]
----
# dnf copr enable @theforeman/foremanctl rhel-9-x86_64
----
====
endif::[]
6 changes: 6 additions & 0 deletions guides/common/modules/snip_configuring-repositories-foremanctl.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
* Enable the required repositories:
+
[options="nowrap" subs="+quotes,attributes"]
----
# dnf copr enable @theforeman/foremanctl rhel-9-x86_64
----
3 changes: 2 additions & 1 deletion guides/doc-Installing_Server/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ ifdef::satellite[]
include::common/modules/con_red-hat-helper-app.adoc[leveloffset=+1]
endif::[]

ifndef::foremanctl[]
include::common/assembly_planning-project-server-installation.adoc[leveloffset=+1]

include::common/assembly_preparing-environment-for-project-server-installation.adoc[leveloffset=+1]
Expand Down Expand Up @@ -73,7 +74,7 @@ endif::[]

[appendix]
include::common/modules/proc_restoring-manual-changes-overwritten-by-a-puppet-run.adoc[leveloffset=+1]

endif::[]
endif::[]

ifndef::orcharhino,satellite[]
Expand Down
9 changes: 1 addition & 8 deletions guides/doc-Quickstart/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,13 @@ include::common/header.adoc[]
:mode: connected
:ProductName: {ProjectServer}
:tabs-sync-option:
ifdef::katello[]
:foremanctl:
endif::[]

= {QuickstartDocTitle}

This guide describes the quickest way to get a {ProjectServer} up and running.
ifdef::foremanctl[]
You can choose between a Puppet-based installation and containerized installation.
endif::[]
For a full installation guide, see {InstallingServerDocURL}[_{InstallingServerDocTitle}_].
ifdef::foremanctl[]
The full installation guide is currently provided only for the Puppet-based installation.

ifdef::foremanctl[]
:FeatureName: The `foremanctl` deployment utility
include::common/modules/snip_technology-preview.adoc[]
endif::[]
Comment on lines +14 to 17
Copy link
Member Author

@aneta-petrova aneta-petrova Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should add this to every foremanctl guide we add to navigation, until the tool becomes more stable.

Expand Down
2 changes: 2 additions & 0 deletions guides/doc-Release_Notes/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
include::common/attributes.adoc[]
include::common/header.adoc[]

ifndef::foremanctl[]
ifndef::katello[]
include::topics/foreman.adoc[]
endif::[]
Expand All @@ -27,6 +28,7 @@ ifdef::katello[]

include::topics/katello-contributors.adoc[leveloffset=+1]
endif::[]
endif::[]

ifndef::orcharhino,satellite[]
include::common/ribbons.adoc[]
Expand Down
2 changes: 2 additions & 0 deletions guides/doc-Upgrading_Project/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ ifdef::satellite[]
include::common/modules/proc_providing-feedback-on-red-hat-documentation.adoc[leveloffset=+1]
endif::[]

ifndef::foremanctl[]
ifdef::foreman-el[]
[IMPORTANT]
====
Expand Down Expand Up @@ -47,6 +48,7 @@ endif::[]

[appendix]
include::common/modules/proc_troubleshooting-permission-issues.adoc[leveloffset=+1]
endif::[]

ifndef::orcharhino,satellite[]
include::common/ribbons.adoc[]
Expand Down
1 change: 1 addition & 0 deletions web/content/index.adoc.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ The future version is built in nightly:
** link:/release/nightly/index-foreman-el.html[Foreman on Enterprise Linux (EL)]
** link:/release/nightly/index-foreman-deb.html[Foreman on Debian/Ubuntu]
** link:/release/nightly/index-katello.html[Foreman with Katello on Enterprise Linux (EL)]
** link:/release/nightly/index-foremanctl.html[Containerized Foreman]

<% if (release = releases_in_state('RC').first) %>
A release candidate is available for testing:
Expand Down
22 changes: 22 additions & 0 deletions web/releases/nightly.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,28 @@
["Hammer_Reference", "Hammer reference"]
]
}
},
{
"title": "Containerized Foreman",
Copy link
Member Author

@aneta-petrova aneta-petrova Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is almost certainly not a good name for the new build target and I'm open to suggestions.

"header": "Containerized Foreman {FOREMAN_VER}",
"filename": "index-foremanctl.html",
"sections": {
"Release notes and upgrading": [
["Upgrading_Project", "Upgrading Foreman to Containerized {FOREMAN_VER}"]
],
"Quickstart": [
["Quickstart", "Quickstart guide"]
],
"Deploying Foreman": [
["Installing_Server", "Installing Foreman Server"]
],
"Administering Foreman server": [
],
"Administering hosts": [
],
"Reference": [
]
}
}
]
}
Loading