Correct external DB instructions for foreman-{deb,el} #2396

ekohl · 2023-08-24T13:23:11Z

When Katello isn't present, you don't need the Candlepin and Pulp databases. With this change, the scenario becomes correct and can be shown.

This is now a draft since I'm not entirely sure if it's all correct. I'm going to rely on the preview to tell me that.

I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.7/Katello 4.9 (planned Satellite 6.14)
Foreman 3.6/Katello 4.8
Foreman 3.5/Katello 4.7 (Satellite 6.13)
Foreman 3.4/Katello 4.6 (EL8 only)
Foreman 3.3/Katello 4.5 on EL7 & EL8 (Satellite 6.12 on EL8 only; orcharhino 6.4/6.5 on EL8 only)
Foreman 3.2/Katello 4.4 on EL7 & EL8
Foreman 3.1/Katello 4.3 on EL7 & EL8 (Satellite 6.11 EL7/8; orcharhino 6.3 on EL7/8)
We do not accept PRs for Foreman older than 3.1.

github-actions · 2023-08-24T13:27:37Z

The PR preview for a38cbf8 is available at theforeman-foreman-documentation-preview-pr-2396.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

ekohl · 2023-08-24T15:28:13Z

I noticed that the PostgreSQL path we use is for Debian 11, which uses PostgreSQL 13. Ubuntu 20.04 uses PostgreSQL 12, so the path is different.

This may need a bit more work.

mjivraja · 2023-08-29T05:08:39Z

guides/common/assembly_using-external-databases.adoc

 . xref:preparing-a-host-for-external-databases_{context}[].
+// TODO: a {RHEL} vs an {EL}
 Prepare a {RHEL} 8 server to host the external databases.


Suggested change

Prepare a {RHEL} 8 server to host the external databases.

Prepare a {EL} 8 server to host the external databases.

foreman-documentation/guides/common/attributes-satellite.adoc

Line 60 in f595593

:EL: {RHEL}

foreman-documentation/guides/common/attributes-base.adoc

Line 116 in f595593

:EL: Enterprise Linux

Will this help for your TODO?

No, it's exactly why there is a TODO. It would be an Enterprise Linux (correct) and an RHEL (incorrect).

One solution would be to create a new macro {an-EL} or similar that does the right thing, but I'm not sure what's best.

@maximiliankolb any suggestions?

I guess, the {EL} attribute satisfies both upstream and downstream, no?

suggestion: "Prepare your {EL} host ..."? I know this is a really ugly issue; it also happens with "a orcharhino Proxy"; sometimes even as "{SmartProxy}s -> orcharhino Proxys" instead of "Proxies" (we have an attribute for the latter by now).

Any thoughts on side stepping it and saying a server instead? Then leave it to the individual section to prepare the server? Looking ahead when we support both EL 8 & 9 at the same time that may (or may not) be easier.

"server" is also OK for me. Any thoughts @asteflova ?

I'm okay with "server".

(I would actually prefer "server" regardless of the an/a RHEL/EL issue: No need to specify particular details here because those details are included in the procedure you link to.)

IMO Server will be more generic. Decrease the readability score. We should play with attributes even if it applies to all builds.

I'm with Aneta on reducing the details in the sentence and saying just "Prepare a server...". Another option would be "Prepare a server on {EL} 8 to host...".

guides/common/modules/con_postgresql-as-an-external-database-considerations.adoc

mjivraja · 2023-08-29T06:07:30Z

guides/common/modules/proc_migrating-to-external-databases.adoc


 .Procedure

-. On {ProjectServer}, stop {Project} services:
+. On {ProjectServer}, stop services:


Should we be specific about the type of services we are stopping? As there can be many other active services.

Possibly. I wasn't sure. To me it felt odd because PostgreSQL is considered a project service, but we exclude it. And you could write out stop {Project} services except PostgreSQL but I like short instructions when the actual command is self explanatory. However, I realize I may not be representative for the target audience so I'm fine with whatever the writers suggest is best here.

I would recommend the original one. What's your take @maximiliankolb ?

Suggested change

. On {ProjectServer}, stop services:

. On {ProjectServer}, stop all {Project} services except for PostgreSQL:

Unsure about "except for"; maybe just "except"?

except for PostgreSQL

guides/doc-Installing_Server/master.adoc

guides/common/modules/proc_migrating-to-external-databases.adoc

guides/common/modules/proc_configuring-satellite-to-use-external-databases.adoc

guides/doc-Installing_Server/master.adoc

maximiliankolb · 2023-08-29T14:41:05Z

guides/common/modules/con_migrating-from-internal-databases-to-external-databases.adoc

+// TODO: a {RHEL} vs an {EL}
 Prepare a {RHEL} 8 server to host the external databases.


Suggested change

// TODO: a {RHEL} vs an {EL}

Prepare a {RHEL} 8 server to host the external databases.

Prepare your {RHEL} 8 server to host the external databases.

There is a big overlap between this and the assembly. Would a snippet be a good idea?

maximiliankolb · 2023-08-29T14:43:53Z

guides/common/modules/proc_migrating-to-external-databases.adoc


 .Procedure

-. On {ProjectServer}, stop {Project} services:
+. On {ProjectServer}, stop services:


Suggested change

. On {ProjectServer}, stop services:

. On {ProjectServer}, stop all {Project} services except for PostgreSQL:

Unsure about "except for"; maybe just "except"?

maximiliankolb · 2023-08-29T14:44:07Z

guides/common/modules/proc_migrating-to-external-databases.adoc

+----
+# {package-remove} {postgresql-server-package}
+----
+


Suggested change

+

guides/common/assembly_using-external-databases.adoc

asteflova · 2023-08-30T08:27:08Z

guides/common/assembly_using-external-databases.adoc

@@ -14,8 +14,11 @@ endif::[]

 To create and use external databases for {Project}, you must complete the following procedures:


Suggested change

To create and use external databases for {Project}, you must complete the following procedures:

To create and use external databases for {Project}, complete the following procedures:

This appears to be a very common pattern:

$ rg 'you must' | wc -l 188

While I agree with your suggestion, should it be tackled project wide?

While I agree with your suggestion, should it be tackled project wide?

That might be risky. Consider cases like "you must not". Removing "you must" in bulk would break sentences like that.

While we could easily exclude individual cases like these ^, there might be others. We would need to come up with an exhaustive list, and I don't know how we would go about that.

Looks like that is just one instance:

$ rg 'you must' | grep -v 'you must not' | wc -l 187

In this case I can take care of it, but I'm cautious about blowing up the scope too much.

ekohl · 2023-08-30T18:42:54Z

I've taken a bit of time to split the commits into more logical changes. Each individual commit should be reasonably easy to review.

Lennonka

Please, fix the build first. I'd like to take a look at the output too.

Lennonka · 2023-10-13T06:53:46Z

guides/common/modules/snip_external-db-migration-steps.adoc

Can we name this snip_steps-external-db-migration.adoc instead?

ekohl · 2023-10-13T11:05:12Z

I had some difficulty with the size of this PR and I've opened #2514 with some the things that I are ready to be merged.

This way they are all consistent with eachother. They follow: * manage * host * name * user * password Where parameters were missing they are added.

Also uses the package-install attribute.

After the DB is unmanaged and no longer needed, it should be removed to free up resources.

ekohl · 2023-10-13T11:19:03Z

Turns out the snippet isn't exactly the same: one has xref, the other doesn't.

When Katello isn't present, you don't need the Candlepin and Pulp databases. With this change, the scenario becomes correct and can be shown. This also adds steps to remove the existing database on the Foreman server, freeing up resources.

ekohl · 2024-07-26T15:26:42Z

I decided to split this up in smaller pieces so we can at least merge those:
#3172
#3173

ekohl · 2024-08-08T11:57:36Z

Will rebase once #3167 is merged.

maximiliankolb · 2024-09-05T14:12:54Z

FYI: I have cherry-picked 24017ac and f4ff4b3 in PR #3264

ekohl force-pushed the external-db-on-foreman branch 3 times, most recently from 101077d to 335efd3 Compare August 24, 2023 15:26

ekohl added this to the Make foreman-documentation the primary upstream documentation milestone Aug 25, 2023

This was linked to issues Aug 25, 2023

Make External DB support available in foreman-{deb,el} #985

Open

Migrating to external DB server doesn't clean up existing DB server #2131

Closed

ekohl force-pushed the external-db-on-foreman branch 2 times, most recently from acca56d to 04b49bf Compare August 28, 2023 13:15

mjivraja reviewed Aug 29, 2023

View reviewed changes

guides/common/modules/con_postgresql-as-an-external-database-considerations.adoc Outdated Show resolved Hide resolved

mjivraja reviewed Aug 29, 2023

View reviewed changes

maximiliankolb reviewed Aug 29, 2023

View reviewed changes

ekohl commented Aug 29, 2023

View reviewed changes

guides/common/assembly_using-external-databases.adoc Outdated Show resolved Hide resolved

asteflova reviewed Aug 30, 2023

View reviewed changes

ekohl force-pushed the external-db-on-foreman branch 2 times, most recently from e634158 to b7d16b2 Compare August 30, 2023 18:42

ekohl mentioned this pull request Sep 4, 2023

Add version numbers to upgrade links in navigation #2374

Merged

8 tasks

ekohl requested a review from Lennonka October 12, 2023 12:20

Lennonka requested changes Oct 13, 2023

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Oct 13, 2023

ekohl added 4 commits October 13, 2023 13:17

Move the external DB installer parameters around

b162fa5

This way they are all consistent with eachother. They follow: * manage * host * name * user * password Where parameters were missing they are added.

Remove a step where PostgreSQL is stopped and then started

45a2316

Introduce postgresql-server-package attribute

24017ac

Also uses the package-install attribute.

Remove PostgreSQL database after migrating to ext DB

f4ff4b3

After the DB is unmanaged and no longer needed, it should be removed to free up resources.

ekohl added 2 commits October 13, 2023 13:34

Move external DB step descriptions to a snippet

696e23f

ekohl force-pushed the external-db-on-foreman branch from b7d16b2 to a38cbf8 Compare October 13, 2023 11:34

pr-processor bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Oct 13, 2023

adamlazik1 added the Waiting on contributor Requires an action from the author label Nov 16, 2023

ekohl mentioned this pull request Feb 27, 2024

Add EL9 Support in Project and SmartProxy Installation #2805

Merged

7 tasks

Lennonka self-assigned this Mar 10, 2024

ekohl mentioned this pull request Aug 8, 2024

Make External DB support available in foreman-{deb,el} #985

Open

Lennonka removed their assignment Aug 8, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Correct external DB instructions for foreman-{deb,el} #2396

Correct external DB instructions for foreman-{deb,el} #2396

ekohl commented Aug 24, 2023

github-actions bot commented Aug 24, 2023 •

edited

Loading

ekohl commented Aug 24, 2023

mjivraja Aug 29, 2023

ekohl Aug 29, 2023

mjivraja Aug 29, 2023

maximiliankolb Aug 29, 2023

ekohl Aug 29, 2023

maximiliankolb Aug 30, 2023

asteflova Aug 30, 2023

mjivraja Aug 30, 2023

Lennonka Oct 13, 2023

mjivraja Aug 29, 2023

ekohl Aug 29, 2023

mjivraja Aug 29, 2023

maximiliankolb Aug 29, 2023

mjivraja Aug 30, 2023

maximiliankolb Aug 29, 2023

ekohl Aug 29, 2023

maximiliankolb Aug 29, 2023

maximiliankolb Aug 29, 2023

asteflova Aug 30, 2023

ekohl Aug 30, 2023

asteflova Aug 31, 2023

ekohl Aug 31, 2023

ekohl commented Aug 30, 2023

Lennonka left a comment •

edited

Loading

Lennonka Oct 13, 2023

ekohl commented Oct 13, 2023

ekohl commented Oct 13, 2023

ekohl commented Jul 26, 2024

ekohl commented Aug 8, 2024

maximiliankolb commented Sep 5, 2024

	Prepare a {RHEL} 8 server to host the external databases.
	Prepare a {EL} 8 server to host the external databases.

	. On {ProjectServer}, stop services:
	. On {ProjectServer}, stop all {Project} services except for PostgreSQL:

		// TODO: a {RHEL} vs an {EL}
		Prepare a {RHEL} 8 server to host the external databases.

	// TODO: a {RHEL} vs an {EL}
	Prepare a {RHEL} 8 server to host the external databases.
	Prepare your {RHEL} 8 server to host the external databases.

		@@ -14,8 +14,11 @@ endif::[]

		To create and use external databases for {Project}, you must complete the following procedures:

Correct external DB instructions for foreman-{deb,el} #2396

Are you sure you want to change the base?

Correct external DB instructions for foreman-{deb,el} #2396

Conversation

ekohl commented Aug 24, 2023

github-actions bot commented Aug 24, 2023 • edited Loading

ekohl commented Aug 24, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ekohl commented Aug 30, 2023

Lennonka left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ekohl commented Oct 13, 2023

ekohl commented Oct 13, 2023

ekohl commented Jul 26, 2024

ekohl commented Aug 8, 2024

maximiliankolb commented Sep 5, 2024

github-actions bot commented Aug 24, 2023 •

edited

Loading

Lennonka left a comment •

edited

Loading