Improve "Foreman on AWS" guide #3485

maximiliankolb · 2024-12-03T12:09:18Z

what

follow up to #3469

why

make the guide fit for orcharhino
apply conventions
add graphics for upstream Foreman+Katello
apply feedback based on Modularize Deploying Foreman on AWS guide #3469

additional info

We want to drop the standalone guide and merge the content to Planning for Foreman. With modular content, this will be fairly trivial.
The move requires Turn 'deployment considerations' into 'deployment path' #3456.

-> There will be a third PR after 3485 and 3456 to make this happen.

cherry-picks

to 3.13 and up only

github-actions · 2024-12-03T12:11:59Z

The PR preview for 8fd57df is available at theforeman-foreman-documentation-preview-pr-3485.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

ekohl

As mentioned on Matrix, some of my thoughts on what I'd like to see with this guide in the long term.

Once we drop the postgresql-evr package, we can use a plain PostgreSQL server. Right now we're aiming for Foreman 3.14 for that. For users it means they can use a managed database like Amazon RDS. It will probably be some special flavor of external database support where we point to https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html (or similar) to obtain the right values and reuse the existing modules.

I should check within Red Hat what the preference is, but it would make sense to me to default to it.

Of course, we first need to actually release the feature in 3.14.

ekohl · 2024-12-03T17:27:12Z

guides/common/modules/con_unsupported-use-cases-for-foreman-on-aws.adoc

@@ -1,12 +1,13 @@
-= Use Cases that Do Not Work
+[id="unsupported-use-cases-for-{project-context}-on-aws"]
+= Unsupported use cases for {Project} on AWS

 In AWS, you cannot manage the DHCP.


Note that if you add a Smart Proxy using a Smart Proxy in our on-premise data center (see Scenario 2: Connecting on-premises and AWS region) then you can use these methods.

This is a long standing issue I have with this guide.

I consider this out of scope for now. I am not that deep into AWS to test this. I can create a follow-up issue to make this visible.

ekohl · 2024-12-03T17:28:12Z

guides/common/modules/con_use-case-considerations-for-foreman-on-aws.adoc

+[id="use-case-considerations-for-{project-context}-on-aws"]
+= Use case considerations for {Project} on AWS
+
+Amazon Web Services (AWS) is an image-only compute resource which means that there are common {Project} use cases that do not work or require extra configuration in your Amazon Web Service environment.


Is this really relevant? You can simply take a bare OS image and then manage it as a normal OS in EC2.

Right now, we only document image-based provisioning: https://docs.theforeman.org/nightly/Provisioning_Hosts/index-katello.html#Creating_Image_Based_Hosts_on_Amazon_EC2_ec2-provisioning

Do you have a suggestion on how to reword https://github.com/theforeman/foreman-documentation/pull/3485/files#diff-8a3e0dc7ad6426c1ecb5681fcd4d86592e0bb22dfbb58ed31128dfbb5c4279c8R4? Should I replace line 4+5 with something more generic?

guides/common/modules/con_deploying-foreman-on-aws.adoc

guides/common/modules/proc_registering-hosts-on-aws-to-foreman.adoc

maximiliankolb · 2024-12-13T09:48:59Z

TODO: After #3167 has been merged, mention the option to run external DBs on dedicated Amazon service: https://aws.amazon.com/rds/ -> done with second commit.

maximiliankolb · 2025-01-20T07:44:05Z

Can someone please do a style review?

guides/common/modules/con_prerequisites-for-foreman-on-aws.adoc

aneta-petrova

I love the little cloud for Internet in the graphics. Very cute!

guides/common/modules/con_scenarios-for-foreman-on-aws.adoc

aneta-petrova

The supported use cases section could use a bit more love but since you're just moving the content and the purpose of this PR is clear from the description, it's completely fine to leave it as it is.

guides/common/modules/con_scenarios-for-foreman-on-aws.adoc

aneta-petrova · 2025-01-20T08:30:57Z

guides/common/modules/con_scenarios-for-foreman-on-aws.adoc

+Create a VPN connection between the on-premises location and the AWS region where your {SmartProxyServer} is located.
+It is also possible to use the external host name of {ProjectServer} when you register the instance that runs {SmartProxy}.


Nitpick (applies to Scenario 3 as well). You have one para with a description and then two images (option 1 and option 2). It takes some effort to connect each image to the corresponding part of the para. What if you split the description into two bullet points? Then it would be somewhat easier to connect the dots (= to connect an image with the corresponding part of the concept description).

guides/common/modules/con_scenarios-for-foreman-on-aws.adoc

aneta-petrova · 2025-01-20T08:33:52Z

guides/doc-Deploying_Project_on_AWS/master.adoc

+include::common/modules/con_use-case-considerations-for-foreman-on-aws.adoc[leveloffset=+1]

-include::common/modules/con_foreman-on-aws-prerequisites.adoc[leveloffset=+1]
+include::common/modules/con_supported-use-cases-for-foreman-on-aws.adoc[leveloffset=+2]

-include::common/modules/con_foreman-on-aws-assumptions.adoc[leveloffset=+2]
+include::common/modules/con_unsupported-use-cases-for-foreman-on-aws.adoc[leveloffset=+2]


Have you considered making this a single module? I think it would be useful to document both support and unsupported functionality in a single file/section -- to make it easier to compare, skip from one to the other, make sure users are aware of both.

aneta-petrova · 2025-01-20T08:34:48Z

guides/common/modules/con_supported-use-cases-for-foreman-on-aws.adoc

+endif::[]
+
+.Multi-homed {Project} and {SmartProxy}
+Multi-homed {ProjectServer} is not supported.


But this is a module about what is supported! :) See my other note about perhaps documenting supported+unsupported in a single module. This is another reason why that might work better.

guides/common/modules/con_supported-use-cases-for-foreman-on-aws.adoc

aneta-petrova

Style review done! :)

guides/common/modules/con_unsupported-use-cases-for-foreman-on-aws.adoc

aneta-petrova · 2025-01-20T08:43:45Z

guides/common/modules/proc_registering-hosts-on-aws-to-foreman.adoc

@@ -0,0 +1,8 @@
+[id="registering-hosts-on-aws-to-{project-context}"]
+= Registering hosts on AWS to {Project}


I think it would be more user-friendly to include this as a step in the "Installing Foreman server on AWS" and "Installing Smart Proxy server on AWS" procedures. Users are unlikely to want to install a server/proxy server without continuing to register the hosts so in my mind, it's all one procedure.

Added ".Next steps" to both procedures. Did you mean to refer to "Registering hosts" in Managing hosts" & dropp the this file?

$ cat guides/doc-Deploying_Project_on_AWS/master.adoc | rg "^include" | sed "s/include::/guides\//g" | sed "s/\[.*$//g" | rg modules | rg -v "proc_providing-feedback-on-red-hat-documentation" | sort -u * Fix/adjust anchors and xrefs to make them fit for all build flavours * Make images not executable $ chmod -x guides/common/images/aws-combined-direct-satellite.png $ chmod -x guides/common/images/aws-combined-vpn-satellite.png $ chmod -x guides/common/images/aws-multi-region-direct-satellite.png $ chmod -x guides/common/images/aws-multi-region-vpn-satellite.png $ chmod -x guides/common/images/aws-single-region-satellite.png

Foreman/Katello does no longer require custom packages to run external databases. This means that users can now use managed DBs as external DB, for example, "Amazon Relational Database Service". Refs PR 3167 in foreman-documentation Refs https://aws.amazon.com/rds/

maximiliankolb

Applied most feedback. Needs re-review.

Still TODO: think about combining supported use cases and unsupported use cases & think about splitting/reordering scenarios aka. images and text.

guides/common/modules/con_prerequisites-for-foreman-on-aws.adoc

guides/common/modules/con_scenarios-for-foreman-on-aws.adoc

maximiliankolb · 2025-01-22T10:56:22Z

guides/common/modules/proc_registering-hosts-on-aws-to-foreman.adoc

@@ -0,0 +1,8 @@
+[id="registering-hosts-on-aws-to-{project-context}"]
+= Registering hosts on AWS to {Project}


Added ".Next steps" to both procedures. Did you mean to refer to "Registering hosts" in Managing hosts" & dropp the this file?

guides/common/modules/con_unsupported-use-cases-for-foreman-on-aws.adoc

guides/common/modules/con_supported-use-cases-for-foreman-on-aws.adoc

pr-processor bot added the Not yet reviewed label Dec 3, 2024

ekohl reviewed Dec 3, 2024

View reviewed changes

pr-processor bot removed the Not yet reviewed label Dec 3, 2024

maximiliankolb mentioned this pull request Dec 5, 2024

Modularize Deploying Foreman on AWS guide #3469

Merged

11 tasks

maximiliankolb force-pushed the improve_foreman_on_aws branch 2 times, most recently from e5e34a1 to a72da79 Compare December 6, 2024 15:10

aneta-petrova mentioned this pull request Dec 9, 2024

Modularize deployment scenarios #3498

Closed

9 tasks

maximiliankolb force-pushed the improve_foreman_on_aws branch 2 times, most recently from 3ec9aa8 to 6beeb99 Compare December 9, 2024 14:51

maximiliankolb marked this pull request as ready for review December 9, 2024 14:53

maximiliankolb commented Dec 9, 2024

View reviewed changes

guides/common/modules/con_deploying-foreman-on-aws.adoc Outdated Show resolved Hide resolved

guides/common/modules/proc_registering-hosts-on-aws-to-foreman.adoc Show resolved Hide resolved

maximiliankolb force-pushed the improve_foreman_on_aws branch from b53a90a to 727f4af Compare January 14, 2025 08:54

aneta-petrova reviewed Jan 20, 2025

View reviewed changes

aneta-petrova added the style review done No issues from docs style/grammar perspective label Jan 20, 2025

maximiliankolb added 3 commits January 22, 2025 11:17

Apply feedback

8fd57df

maximiliankolb force-pushed the improve_foreman_on_aws branch from 727f4af to 8fd57df Compare January 22, 2025 11:03

maximiliankolb commented Jan 22, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve "Foreman on AWS" guide #3485

Improve "Foreman on AWS" guide #3485

maximiliankolb commented Dec 3, 2024 •

edited

Loading

github-actions bot commented Dec 3, 2024 •

edited

Loading

ekohl left a comment

ekohl Dec 3, 2024

maximiliankolb Jan 20, 2025

ekohl Dec 3, 2024

maximiliankolb Jan 20, 2025

maximiliankolb commented Dec 13, 2024 •

edited

Loading

maximiliankolb commented Jan 20, 2025

aneta-petrova left a comment

aneta-petrova left a comment

aneta-petrova Jan 20, 2025

aneta-petrova Jan 20, 2025

aneta-petrova Jan 20, 2025

aneta-petrova left a comment

aneta-petrova Jan 20, 2025

maximiliankolb Jan 22, 2025

maximiliankolb left a comment

maximiliankolb Jan 22, 2025

		Create a VPN connection between the on-premises location and the AWS region where your {SmartProxyServer} is located.
		It is also possible to use the external host name of {ProjectServer} when you register the instance that runs {SmartProxy}.

		@@ -0,0 +1,8 @@
		[id="registering-hosts-on-aws-to-{project-context}"]
		= Registering hosts on AWS to {Project}

Improve "Foreman on AWS" guide #3485

Are you sure you want to change the base?

Improve "Foreman on AWS" guide #3485

Conversation

maximiliankolb commented Dec 3, 2024 • edited Loading

what

why

additional info

cherry-picks

github-actions bot commented Dec 3, 2024 • edited Loading

ekohl left a 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

maximiliankolb commented Dec 13, 2024 • edited Loading

maximiliankolb commented Jan 20, 2025

aneta-petrova left a comment

Choose a reason for hiding this comment

aneta-petrova left a 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

aneta-petrova left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maximiliankolb commented Dec 3, 2024 •

edited

Loading

github-actions bot commented Dec 3, 2024 •

edited

Loading

maximiliankolb commented Dec 13, 2024 •

edited

Loading