Create a new guide for installer-based provisioning (1 guide of 3) #3472

Lennonka · 2024-11-25T22:08:24Z

What changes are you introducing?

Splitting Provisioning hosts into 3 new guides:

Provisioning machines by using an installer - includes network boot and boot disks, which are both installer-based provisioning, plus Discovery, which also uses network boot <--- We are here.
Provisioning virtual machines - includes virtualization providers, image-based provisioning, and directives for installer-based provisioning if available
Provisioning cloud instances - includes cloud infrastructure providers and image-based provisioning only

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

To mitigate pain points identified in SAT-26089 comments (public).

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

Provisioning hosts will be destroyed after all 3 guides from above will have been created.
I've removed _{context} where it was needed for module reuse. Unfortunately, these changes were extensive to make the build work and this PR is as small as it gets.
Currently, I am only modifying the structure. Further, detailed improvements will be done in subsequent PRs. Therefore, the new guide is terminologically inconsistent.
Reviewers, please, focus on the title and heading structure in this PR. The rest of the affected guides are just link updates. Using preview first is highly recommended.
Will require updates of documentation links in the web UI.

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: N/A - for Foreman 3.14

github-actions · 2024-11-25T22:10:23Z

The PR preview for 5cb540b is available at theforeman-foreman-documentation-preview-pr-3472.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

guides/common/attributes-titles.adoc

apinnick

Looks OK but I had a comment about the title.

maximiliankolb

Reviewed diff of 52/63 files. Great effort Lena, thanks! I made many out of scope comments; feel free to decline them all. If you do, please let me know and I'll work on this as a follow-up PR.

I also left some questions but I'm unsure if the content is new or just has been moved. If you only move content, then I consider some more comments out of scope.

maximiliankolb · 2024-11-27T13:30:15Z

guides/common/assembly_configuring-provisionable-platforms.adoc

+
+include::modules/proc_setting-the-provisioning-context.adoc[leveloffset=+1]
+
+include::modules/proc_creating-operating-systems.adoc[leveloffset=+1]


mental note: I should create a follow-up PR to consolidate the procedure to create OS entries. Today, I believe that it'd be enough to show a table with sane name, codename, major and minor versions and associate templates for foreman-* + katello, show RHEL-only for Satellite, and show one specific OS for orcharhino.

out of scope for now, but maybe a nice future improvement.

maximiliankolb · 2024-11-27T13:31:21Z

guides/common/assembly_configuring-provisioning-content.adoc

+
+include::modules/proc_using-an-imagebuilder-image-for-provisioning.adoc[leveloffset=+1]
+
+include::modules/proc_adding-installation-media.adoc[leveloffset=+1]


mental note: same as above: I should think about eventually merging these procedures.

maximiliankolb · 2024-11-27T13:31:42Z

guides/common/assembly_configuring-templates-for-provisioning.adoc

+include::modules/proc_creating-custom-provisioning-snippets.adoc[leveloffset=+1]
+
+ifndef::satellite[]
+include::modules/ref_custom-provisioning-snippet-example-for-debian.adoc[leveloffset=+1]


same as above.

guides/common/assembly_using-boot-disks-to-provision-hosts.adoc

guides/common/modules/proc_configuring-the-security-token-validity-duration.adoc

maximiliankolb · 2024-11-27T15:18:02Z

guides/common/modules/proc_creating-a-suse-operating-system.adoc

@@ -47,7 +47,7 @@ For more information, see {ProvisioningDocURL}creating-partition-tables_provisio
 . In the {ProjectWebUI}, navigate to *Hosts* > *Templates* > *Provisioning Templates* and click *Create Template*.
 The provisioning templates are stored in the `/usr/share/foreman/app/views/unattended/provisioning_templates/` directory on your {ProjectServer}.
 +
-For more information, see {ProvisioningDocURL}provisioning-templates_provisioning[Provisioning Templates] in _{ProvisioningDocTitle}_.
+For more information, see {ProvisioningDocURL}provisioning-templates[Provisioning Templates] in _{ProvisioningDocTitle}_.


Suggested change

For more information, see {ProvisioningDocURL}provisioning-templates[Provisioning Templates] in _{ProvisioningDocTitle}_.

For more information, see {ProvisioningDocURL}provisioning-templates[Provisioning templates] in _{ProvisioningDocTitle}_.

maximiliankolb · 2024-11-27T15:20:04Z

guides/common/modules/proc_creating-discovery-rules.adoc

@@ -23,7 +23,7 @@ For example: `cpu_count  > 8`.
 . In the *Hostname* field, enter the pattern to determine host names for multiple hosts.
 This uses the same ERB syntax that provisioning templates use.
 The host name can use the `@host` attribute for host-specific values and the `rand` macro for a random number or the `sequence_hostgroup_param_next` macro for incrementing the value.
-For more information about provisioning templates, see xref:provisioning-templates_{context}[] and the API documentation.
+For more information about provisioning templates, see xref:provisioning-templates[] and the API documentation.


Suggested change

For more information about provisioning templates, see xref:provisioning-templates[] and the API documentation.

For more information about provisioning templates, see xref:provisioning-templates[].

out of scope but I'd drop this. It was originally probably meant as a reference to the DSL documentation: https://FQDN/templates_doc which AFAIK helps writing ERB templates

maximiliankolb · 2024-11-27T15:20:46Z

...es/common/modules/proc_installing-and-configuring-puppet-agent-during-host-provisioning.adoc

@@ -32,7 +32,7 @@ endif::[]
 .Procedure
 . Navigate to *Hosts* > *Templates* > *Provisioning Templates*.
 . Select a provisioning template depending on your host provisioning method.
-For more information, see {ProvisioningDocURL}kinds-of-provisioning-templates_provisioning[Kinds of Provisioning Templates] in _{ProvisioningDocTitle}_.
+For more information, see {ProvisioningDocURL}kinds-of-provisioning-templates[Kinds of Provisioning Templates] in _{ProvisioningDocTitle}_.


Suggested change

For more information, see {ProvisioningDocURL}kinds-of-provisioning-templates[Kinds of Provisioning Templates] in _{ProvisioningDocTitle}_.

For more information, see {ProvisioningDocURL}kinds-of-provisioning-templates[Kinds of provisioning templates] in _{ProvisioningDocTitle}_.

(out of scope)

guides/doc-Provisioning_Netboot/docinfo.xml

Lennonka · 2024-12-03T15:54:46Z

TODO: Incorporate changes from #2145

EDIT: Done.

guides/common/assembly_using-network-boot-to-provision-hosts.adoc

guides/common/modules/con_prerequisites-for-network-boot-provisioning.adoc

Lennonka · 2024-12-03T20:14:21Z

I've moved a couple more modules.

Lennonka · 2024-12-03T20:22:21Z

TODO: Add abstract to docinfo.xml

EDIT: Done.

Lennonka · 2024-12-05T17:00:01Z

I'm still unsure about the placement of the settings like the token duration or default root password. Do you think that a special chapter is in order, eg. Additional settings or Global provisioning settings? It would make them more visible. Now they are lost in the noise.

Lennonka · 2024-12-05T19:37:13Z

I've moved a couple more modules around.

Now ready for re-review.

apinnick · 2024-12-08T11:44:48Z

I'm still unsure about the placement of the settings like the token duration or default root password. Do you think that a special chapter is in order, eg. Additional settings or Global provisioning settings? It would make them more visible. Now they are lost in the noise.

@Lennonka Can you find the user stories for these 2 features? The security token validity duration seems to belong to PXE provisioning, so I would expect to find it in the network boot section.

I am not sure about where defaults encrypted root passwords would go. Now that only one navigation section can be open at a time, it's harder to scan the entire TOC. I don't think "Global provisioning settings" is the best name because users tend to ignore headers that are not very specific. If you had to create a separate section, "Security settings" would make sense. Maybe FIPS could be moved there.

Lennonka · 2024-12-09T22:01:48Z

@apinnick The settings are applicable to both network boot and boot disks. Users don't have to configure the token as it has a default duration value, unless they want to change it for some reason. I don't have a user story in my GDoc for the token.

Maybe "Security settings" and moving FIPS there is a good idea.
However, in the following guide I'll have another setting and I'm not sure what to do then.

It's out of scope for this PR, but perhaps we should consider it as well.

apinnick · 2024-12-10T10:09:55Z

@apinnick The settings are applicable to both network boot and boot disks. Users don't have to configure the token as it has a default duration value, unless they want to change it for some reason. I don't have a user story in my GDoc for the token.

@Lennonka I had another look at the security token procedure. I see what you mean about it being a global procedure. It will not fit easily into existing UI procedures because it is set in Administer > Settings . IMO, the main use case for setting a new token duration would be for enhanced security, by making the duration shorter. (I sincerely hope no one tries to disable token generation in a production system. That should only be done in a test system. Do we need to mention this or can we trust the user's intelligence? 😺 ).

I would like to see FIPS moved out of the appendices because users tend to ignore stuff at the end of the doc. Enabling FIPS is also an admin security procedure. I do think the two subjects would fit well together in a Security settings section. Maybe there are other procedures that would fit there. Not sure.

Re: Removing VMs after deleting hosts. I would not recommend putting it in "Global" because no one would expect to find the info there. I have run into this setting before, for CNV. It's the kind of info that needs to be called out for users who are creating VMs and deleting hosts. It might not even require a procedure. Deleting VMs is usually straightforward. You might be able to manage with a warning at the beginning of all the "Provisioning VMs on ..." sections, because the behavior is not expected.

I see that Destroy VM on deleting host setting is mentioned in Managing hosts, so you might not need to do anything more. Maybe you could just rewrite that warning and use as is. Alternatively, you could turn the warning into a very short procedure module and add it to each of the Provisioning VMs assemblies. It is not really a global setting because it does not apply to cloud instances, only to virtualization platforms.

Hope this helps!

maximiliankolb

I found one broken link and made some minor suggestions; nothing that blocks your PR.

Style-wise LGTM (with that one fixed link) 👍

maximiliankolb · 2024-12-10T13:27:25Z

guides/common/modules/con_provisioning-cloud-instances-on-openstack.adoc

@@ -8,7 +8,7 @@ In {Project}, you can interact with {OpenStack} REST API to create cloud instanc
 .Prerequisites
 include::snip_prerequisites-common-compute-resource.adoc[]
 * A {SmartProxyServer} managing a network in your OpenStack environment.
-For more information, see {ProvisioningDocURL}Configuring_Networking_provisioning[Configuring Networking] in _{ProvisioningDocTitle}_.
+For more information, see {ProvisioningDocURL}configuring-networking[Configuring Networking] in _{ProvisioningDocTitle}_.


Suggested change

For more information, see {ProvisioningDocURL}configuring-networking[Configuring Networking] in _{ProvisioningDocTitle}_.

For more information, see {ProvisioningDocURL}configuring-networking[Configuring networking] in _{ProvisioningDocTitle}_.

Leaving this to another PR.

guides/common/modules/proc_creating-hosts-with-uefi-http-boot-provisioning.adoc

guides/common/modules/proc_using-a-synced-kickstart-repository.adoc

guides/common/modules/proc_creating-hosts-with-pxe-provisioning.adoc

Lennonka · 2024-12-18T21:01:55Z

Rebased.

Lennonka · 2024-12-19T21:49:41Z

guides/common/attributes-titles.adoc

@apinnick FYI, we have separate titles for upstream and downstream.

guides/common/modules/con_provisioning-virtual-machines-on-ovirt.adoc

pr-processor bot added the Not yet reviewed label Nov 25, 2024

Lennonka commented Nov 25, 2024

View reviewed changes

guides/common/attributes-titles.adoc Outdated Show resolved Hide resolved

pr-processor bot removed the Not yet reviewed label Nov 25, 2024

Lennonka marked this pull request as draft November 25, 2024 22:45

Lennonka marked this pull request as ready for review November 26, 2024 06:08

Lennonka added Needs style review Requires a review from docs style/grammar perspective Not yet reviewed labels Nov 26, 2024

Lennonka requested review from apinnick, maximiliankolb and bangelic November 26, 2024 06:08

pr-processor bot removed the Not yet reviewed label Nov 26, 2024

apinnick reviewed Nov 26, 2024

View reviewed changes

maximiliankolb reviewed Nov 27, 2024

View reviewed changes

Lennonka commented Dec 3, 2024

View reviewed changes

guides/common/assembly_using-network-boot-to-provision-hosts.adoc Outdated Show resolved Hide resolved

Lennonka commented Dec 3, 2024

View reviewed changes

guides/common/modules/con_prerequisites-for-network-boot-provisioning.adoc Outdated Show resolved Hide resolved

Lennonka force-pushed the create-provisioning-netboot-guide-1of3 branch from 869ed35 to 6fc2cd1 Compare December 3, 2024 18:36

Lennonka requested a review from maximiliankolb December 4, 2024 09:47

Lennonka added the Needs re-review label Dec 5, 2024

maximiliankolb approved these changes Dec 10, 2024

View reviewed changes

pr-processor bot removed the Needs re-review label Dec 10, 2024

Lennonka force-pushed the create-provisioning-netboot-guide-1of3 branch from 3a04968 to 9730057 Compare December 10, 2024 20:33

Lennonka added 19 commits December 18, 2024 21:27

fixup! Create a new guide for installer-based provisioning

0240a65

fixup! Create a new guide for installer-based provisioning

2aca670

Rename the guide

f0a683c

Update IDs, xrefs, and links

9d2bece

Update context and guide attributes

2766f7c

Incorporate Secure Boot from theforeman#2145

8044280

fixup! Rename the guide

76f6011

Incorporate smaller suggestions from review

cb5a811

Move network boot info

cc638fe

Add concept for Secure Boot config

73a99ce

Move iPXE

5bd81c7

Hide prereqs for image-based provisioning

53a6f18

Add Abstract

6709b54

Move settings to a special chapter

169943b

Remove 'Building cloud images' from this guide

8f75bd2

Move provisioning contexts to a special chapter

2f54109

Fix title attribute in docinfo.xml

049dbc4

Incorporate suggestions from Max

15ba29d

Incorporate suggestions from Avital

d6d8df0

Lennonka force-pushed the create-provisioning-netboot-guide-1of3 branch from 9730057 to d6d8df0 Compare December 18, 2024 21:01

Lennonka added 4 commits December 18, 2024 22:07

fixup after rebase

3cf5402

Reword 'Configuring' to 'Preparing'

0596f6b

Change the title of the guide

9566c0b

Rename two headings

7bb21f2

Lennonka commented Dec 19, 2024

View reviewed changes

guides/common/attributes-titles.adoc

Copy link

Contributor Author

Lennonka Dec 19, 2024

Choose a reason for hiding this comment

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

@apinnick FYI, we have separate titles for upstream and downstream.

maximiliankolb reviewed Dec 20, 2024

View reviewed changes

guides/common/modules/con_provisioning-virtual-machines-on-ovirt.adoc Outdated Show resolved Hide resolved

Lennonka added 3 commits December 20, 2024 18:11

Fix link labels

80299e4

Refactor TFTP boot

3a0fd76

fixup! Refactor TFTP boot

5cb540b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create a new guide for installer-based provisioning (1 guide of 3) #3472

Create a new guide for installer-based provisioning (1 guide of 3) #3472

Lennonka commented Nov 25, 2024 •

edited

Loading

github-actions bot commented Nov 25, 2024 •

edited

Loading

apinnick left a comment

maximiliankolb left a comment

maximiliankolb Nov 27, 2024

maximiliankolb Nov 27, 2024

maximiliankolb Nov 27, 2024

maximiliankolb Nov 27, 2024

maximiliankolb Nov 27, 2024

maximiliankolb Nov 27, 2024

Lennonka commented Dec 3, 2024 •

edited

Loading

Lennonka commented Dec 3, 2024

Lennonka commented Dec 3, 2024 •

edited

Loading

Lennonka commented Dec 5, 2024 •

edited

Loading

Lennonka commented Dec 5, 2024

apinnick commented Dec 8, 2024

Lennonka commented Dec 9, 2024 •

edited

Loading

apinnick commented Dec 10, 2024

maximiliankolb left a comment

maximiliankolb Dec 10, 2024

Lennonka Dec 10, 2024

Lennonka commented Dec 18, 2024

Lennonka Dec 19, 2024


		include::modules/proc_setting-the-provisioning-context.adoc[leveloffset=+1]

		include::modules/proc_creating-operating-systems.adoc[leveloffset=+1]


		include::modules/proc_using-an-imagebuilder-image-for-provisioning.adoc[leveloffset=+1]

		include::modules/proc_adding-installation-media.adoc[leveloffset=+1]

	For more information, see {ProvisioningDocURL}provisioning-templates[Provisioning Templates] in _{ProvisioningDocTitle}_.
	For more information, see {ProvisioningDocURL}provisioning-templates[Provisioning templates] in _{ProvisioningDocTitle}_.

	For more information about provisioning templates, see xref:provisioning-templates[] and the API documentation.
	For more information about provisioning templates, see xref:provisioning-templates[].

Create a new guide for installer-based provisioning (1 guide of 3) #3472

Are you sure you want to change the base?

Create a new guide for installer-based provisioning (1 guide of 3) #3472

Conversation

Lennonka commented Nov 25, 2024 • edited Loading

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

Checklists

github-actions bot commented Nov 25, 2024 • edited Loading

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

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

Lennonka commented Dec 3, 2024 • edited Loading

Lennonka commented Dec 3, 2024

Lennonka commented Dec 3, 2024 • edited Loading

Lennonka commented Dec 5, 2024 • edited Loading

Lennonka commented Dec 5, 2024

apinnick commented Dec 8, 2024

Lennonka commented Dec 9, 2024 • edited Loading

apinnick commented Dec 10, 2024

maximiliankolb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lennonka commented Dec 18, 2024

Choose a reason for hiding this comment

Lennonka commented Nov 25, 2024 •

edited

Loading

github-actions bot commented Nov 25, 2024 •

edited

Loading

Lennonka commented Dec 3, 2024 •

edited

Loading

Lennonka commented Dec 3, 2024 •

edited

Loading

Lennonka commented Dec 5, 2024 •

edited

Loading

Lennonka commented Dec 9, 2024 •

edited

Loading