Skip to content

Create a new guide for provisioning virtual machines (2 of 3) #3608

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 7 commits into
base: master
Choose a base branch
from
Draft

Create a new guide for provisioning virtual machines (2 of 3) #3608

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2d4b401
Add guide for image-based provisioning on virt.infra
Lennonka Jan 23, 2025
2baf401
Add guide attributes
Lennonka Jan 23, 2025
2aa8b3d
Replace unnecessary procedure with snippet
Lennonka Jan 23, 2025
8355b4c
Add link to provisioning permissions
Lennonka Jan 23, 2025
f328a82
Hide sections not required for image-based provisioning
Lennonka Jan 23, 2025
fde6f81
Move permissions prereq to common prereqs
Lennonka Jan 24, 2025
f570995
Reword warning
Lennonka Jan 24, 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
2 changes: 0 additions & 2 deletions guides/common/assembly_configuring-provisioning-resources.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,5 +87,3 @@ include::modules/proc_creating-compute-profiles.adoc[leveloffset=+1]
include::modules/proc_setting-a-default-encrypted-root-password.adoc[leveloffset=+1]

include::modules/proc_using-novnc-to-access-virtual-machines.adoc[leveloffset=+1]

include::modules/proc_removing-a-virtual-machine-upon-host-deletion.adoc[leveloffset=+1]
2 changes: 0 additions & 2 deletions guides/common/assembly_preparing-client-platforms.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,4 @@ include::modules/proc_creating-hardware-models.adoc[leveloffset=+1]

ifdef::provisioning-cloud,provisioning-virtual[]
include::modules/proc_creating-compute-profiles.adoc[leveloffset=+1]

include::modules/proc_using-novnc-to-access-virtual-machines.adoc[leveloffset=+1]
endif::[]
6 changes: 6 additions & 0 deletions guides/common/assembly_preparing-networking.adoc
View file
Open in desktop
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@stejskalleos What exactly are the networking requirements for image-based provisioning?

I thought that DHCP wasn't required, but the Prerequisites for image-based provisioning say that it is.

They still need at least one domain and one subnet, right?

Copy link
Contributor

Choose a reason for hiding this comment

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

What exactly are the networking requirements

That's the thing, there are no exact requirements.
I'll describe it as best I can.

DHCP is always required. The host must have an IP address valid for its subnet and communication in the subnet.

Now, in Foreman, we have the terms managed and unmanaged DHCP, which, as far as I know, we came up with, rather than being an official tech buzzword.

  • Managed DHCP—Smart Proxy can add/update/remove DHCP records and leases and point the host to the bootloader file and boot configuration files. From the config files, it will get the path to the kernel and the init ramdisk and load them.

  • Unmanaged DHCP - Smart Proxy cannot do the stuff above, but that doesn't mean the host cannot obtain an IP from the DHCP.

In one sentence: The difference is whether or not the IP was assigned to the host by our smart-proxy, but the DHCP is still there.

So I would say that managed DHCP is preferred, but it is not required.

Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,15 @@ include::modules/proc_optimizing-performance-by-removing-nics-from-database.adoc

include::modules/con_network-resources.adoc[leveloffset=+1]

ifndef::provisioning-virtual[]
include::modules/con_foreman-and-dhcp-configuration.adoc[leveloffset=+1]

include::modules/ref_options-in-managed-dhcpv4.adoc[leveloffset=+2]

include::modules/ref_options-in-unmanaged-dhcpv6.adoc[leveloffset=+2]

include::modules/proc_troubleshooting-dhcp-problems.adoc[leveloffset=+1]
endif::[]

ifdef::provisioning,provisioning-cloud,provisioning-virtual[]
include::modules/con_prerequisites-for-image-based-provisioning.adoc[leveloffset=+1]
Expand All @@ -22,13 +24,17 @@ include::modules/proc_configuring-network-services.adoc[leveloffset=+1]

include::modules/ref_multiple-subnets-or-domains-using-installer.adoc[leveloffset=+2]

ifndef::provisioning-virtual[]
include::modules/ref_dhcp-options-for-network-configuration.adoc[leveloffset=+2]
endif::[]

include::modules/ref_dns-options-for-network-configuration.adoc[leveloffset=+2]

ifndef::provisioning-virtual[]
include::modules/ref_tftp-options-for-network-configuration.adoc[leveloffset=+2]

include::modules/proc_using-tftp-services-through-nat.adoc[leveloffset=+2]
endif::[]

include::modules/proc_adding-a-domain.adoc[leveloffset=+1]

Expand Down
6 changes: 2 additions & 4 deletions guides/common/assembly_security-settings.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@
include::modules/con_security-settings.adoc[]

ifndef::provisioning-virtual[]
include::modules/proc_configuring-the-security-token-validity-duration.adoc[leveloffset=+1]
endif::[]
Comment on lines +3 to +5
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@stejskalleos The security token is not relevant for image-based provisioning, correct?

Copy link
Contributor

Choose a reason for hiding this comment

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

It is.
The machine will still ask Foreman to generate the Kickstart default template.

  • Disabling tokens in the settings will remove the requirement though. To generate the template, you must ensure the host can be authenticated in Foreman. Usually, this is done by MAC / IP.
  • If the image already contains generated kickstart, you don't have to call Foreman for the generated template; you don't need the token.
  • Otherwise you need it.


include::modules/proc_setting-a-default-encrypted-root-password.adoc[leveloffset=+1]

ifdef::provisioning-cloud,provisioning-virtual[]
include::modules/proc_removing-a-virtual-machine-upon-host-deletion.adoc[leveloffset=+1]
endif::[]

include::assembly_provisioning-fips-compliant-hosts.adoc[leveloffset=+1]
1 change: 1 addition & 0 deletions guides/common/attributes-base.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
:MonitoringDocURL: {BaseURL}Monitoring_Project/{BaseFilenameURL}#
:PlanningDocURL: {BaseURL}Planning_for_Project/{BaseFilenameURL}#
:ProvisioningInstallerDocURL: {BaseURL}Provisioning_Installer/{BaseFilenameURL}#
:ProvisioningVirtualDocURL: {BaseURL}Provisioning_Virtual/{BaseFilenameURL}#
:ProvisioningDocURL: {BaseURL}Provisioning_Hosts/{BaseFilenameURL}#
:ReleaseNotesDocURL: {BaseURL}Release_Notes/{BaseFilenameURL}#
:TuningDocURL: {BaseURL}Tuning_Performance/{BaseFilenameURL}#
Expand Down
1 change: 1 addition & 0 deletions guides/common/attributes-satellite.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
:PlanningDocURL: {BaseURL}overview_concepts_and_deployment_considerations/index#
:ProvisioningDocURL: {BaseURL}provisioning_hosts/index#
:ProvisioningInstallerDocURL: {BaseURL}provisioning_hosts_by_using_anaconda/index#
:ProvisioningVirtualDocURL: {BaseURL}provisioning_virtual_machines/index#
:TuningDocURL: {BaseURL}tuning_performance_of_red_hat_satellite/index#
:UpdatingDocURL: {BaseURL}updating_red_hat_satellite/index#
:UpgradingDocURL: {BaseURL}upgrading_connected_red_hat_satellite_to_{ProjectVersion}/index#
Expand Down
1 change: 1 addition & 0 deletions guides/common/attributes-titles.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
:PlanningDocTitle: Planning for {ProjectName}
:ProvisioningDocTitle: Provisioning hosts
:ProvisioningInstallerDocTitle: Provisioning hosts by using an installer
:ProvisioningVirtualDocTitle: Provisioning virtual machines
:QuickStartDocTitle: Quick start guide for {Project} on {install-on-os}
:ReleaseNotesDocTitle: Release notes
:TuningDocTitle: Tuning performance of {ProjectName}
Expand Down
3 changes: 1 addition & 2 deletions guides/common/modules/con_provisioning-cloud-instances-on-openstack.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,4 @@ ifndef::orcharhino[]
For more information, see the {RHDocsBaseURL}red_hat_openstack_platform/16.0/html/instances_and_images_guide/index[{OpenStack} _Instances and Images Guide_].
endif::[]

.Additional resources
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
3 changes: 1 addition & 2 deletions guides/common/modules/con_provisioning-virtual-machines-in-proxmox.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,4 @@ Proxmox Virtual Environment is an open-source server management platform for ent
Proxmox tightly integrates the KVM hypervisor and Linux Containers (LXC).
{Project} can interact with Proxmox, including creating virtual machines and controlling their power management states.

.Additional resources
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
4 changes: 1 addition & 3 deletions guides/common/modules/con_provisioning-virtual-machines-on-kubevirt.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,4 @@ include::snip_prerequisites-common-compute-resource.adoc[]
Ensure that no other DHCP services run on this network to avoid conflicts with {SmartProxyServer}.
For more information about network service configuration for {SmartProxyServers}, see {ProvisioningDocURL}preparing-networking[Preparing networking] in _{ProvisioningDocTitle}_.

.Additional resources
* For a list of permissions a non-admin user requires to provision hosts, see xref:permissions-required-to-provision-hosts_provisioning[].
Copy link
Contributor

Choose a reason for hiding this comment

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

Note to myself: snip_prerequisites-common-compute-resource.adoc

include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
4 changes: 1 addition & 3 deletions guides/common/modules/con_provisioning-virtual-machines-on-kvm.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,4 @@ If you want to use a non-root user on the KVM server, you must add the user to t
# usermod -a -G libvirt _non_root_user_
----

.Additional resources
* For a list of permissions a non-admin user requires to provision hosts, see xref:permissions-required-to-provision-hosts_provisioning[].
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
3 changes: 1 addition & 2 deletions guides/common/modules/con_provisioning-virtual-machines-on-ovirt.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,5 +48,4 @@ ifndef::satellite[]
For more information about how to create a user and add permissions in {oVirt}, see https://www.ovirt.org/documentation/administration_guide/#chap-Users_and_Roles[Users and Roles] in the {oVirt} documentation.
endif::[]

.Additional resources
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
4 changes: 4 additions & 0 deletions guides/common/modules/proc_creating-compute-profiles.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,12 @@ A default installation of {ProjectName} contains three predefined profiles:

You can apply compute profiles to all supported compute resources:

ifdef::provisioning,provisioning-cloud[]
Copy link
Contributor

Choose a reason for hiding this comment

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

Are these flags used during the documentation generation?
What's the reasoning for not including these blocks in the end docs?

* xref:supported-cloud-providers[]
endif::[]
ifdef::provisioning,provisioning-virtual[]
* xref:supported-virtualization-infrastructures[]
endif::[]

.Procedure
. In the {ProjectWebUI}, navigate to *Infrastructure* > *Compute Profiles* and click *Create Compute Profile*.
Expand Down
3 changes: 1 addition & 2 deletions guides/common/modules/proc_deleting-a-virtual-machine-on-amazon-ec2.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,4 @@ You can delete virtual machines running on Amazon EC2 from within {Project}.
This deletes the virtual machine from the Amazon EC2 compute resource while retaining any associated hosts within {Project}.
If you want to delete an orphaned host, navigate to *Hosts* > *All Hosts* and delete the host manually.

.Additional resources
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
3 changes: 1 addition & 2 deletions guides/common/modules/proc_deleting-a-virtual-machine-on-proxmox.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,4 @@ You can delete virtual machines running on Proxmox from within {Project}.
This deletes the virtual machine from your Proxmox compute resource while retaining any associated hosts within {Project}.
. Optional: If you want to delete the orphaned host, navigate to *Hosts* > *All Hosts* and delete the host manually.

.Additional resources
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
3 changes: 1 addition & 2 deletions guides/common/modules/proc_deleting-a-vm-on-google-gce.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,4 @@ You can delete VMs running on Google GCE on your {ProjectServer}.
This deletes the virtual machine from the Google GCE compute resource while retaining any associated hosts within {Project}.
If you want to delete the orphaned host, navigate to *Hosts > All Hosts* and delete the host manually.

.Additional resources
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
3 changes: 1 addition & 2 deletions guides/common/modules/proc_deleting-a-vm-on-microsoft-azure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,4 @@ You can delete VMs running on Microsoft Azure from within {Project}.
This deletes the virtual machine from the Microsoft Azure compute resource while retaining any associated hosts within {Project}.
If you want to delete the orphaned host, navigate to *Hosts > All Hosts* and delete the host manually.

.Additional resources
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
3 changes: 1 addition & 2 deletions guides/common/modules/proc_deleting-a-vm-on-vmware.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,4 @@ You can delete VMs running on VMware from within {Project}.
This deletes the virtual machine from the VMware compute resource while retaining any associated hosts within {Project}.
If you want to delete the orphaned host, navigate to *Hosts > All Hosts* and delete the host manually.

.Additional resources
include::snip_resource-remove-vm.adoc[]
include::snip_warning-destroy-vm-on-host-delete.adoc[]
12 changes: 2 additions & 10 deletions guides/common/modules/proc_removing-a-host-from-server.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
Use this procedure to remove a host from {Project}.
To use the CLI instead of the {ProjectWebUI}, see the xref:cli-Removing_a_Host_from_Server_{context}[].

include::snip_warning-destroy-vm-on-host-delete.adoc[]

.Procedure
. In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts* or *Hosts* > *Content Hosts*.
Note that there is no difference from what page you remove a host, from *All Hosts* or *Content Hosts*.
Expand All @@ -12,16 +14,6 @@ In both cases, {Project} removes a host completely.
. From the *Select Action* list, select *Delete Hosts*.
. Click *Submit* to remove the host from {Project} permanently.

[WARNING]
====
By default, the `Destroy associated VM on host delete` setting is set to `no`.
If a host record that is associated with a virtual machine is deleted, the virtual machine will remain on the compute resource.

To delete a virtual machine on the compute resource, navigate to *Administer > Settings* and select the *Provisioning* tab.
Setting `Destroy associated VM on host delete` to `yes` deletes the virtual machine if the host record that is associated with the virtual machine is deleted.
To avoid deleting the virtual machine in this situation, disassociate the virtual machine from {Project} without removing it from the compute resource or change the setting.
====

[id="cli-Removing_a_Host_from_Server_{context}"]
.CLI procedure
* Delete your host from {Project}:
Expand Down
37 changes: 0 additions & 37 deletions guides/common/modules/proc_removing-a-virtual-machine-upon-host-deletion.adoc
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion guides/common/modules/ref_permissions-required-to-provision-hosts.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[id="permissions-required-to-provision-hosts_{context}"]
[id="permissions-required-to-provision-hosts"]
= Permissions required to provision hosts

The following list provides an overview of the permissions a non-admin user requires to provision hosts.
Expand Down
2 changes: 2 additions & 0 deletions guides/common/modules/snip_prerequisites-common-compute-resource.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
* Ensure the provisioning user has the required permissions to provision hosts.
For more information, see xref:permissions-required-to-provision-hosts[].
ifdef::foreman-el,katello[]
* Provide the installation medium for the operating systems that you want to use to provision hosts.
If the Katello plugin is installed, you can use synchronized content repositories for {RHEL}.
Expand Down
3 changes: 0 additions & 3 deletions guides/common/modules/snip_resource-remove-vm.adoc
View file
Open in desktop

This file was deleted.

8 changes: 8 additions & 0 deletions guides/common/modules/snip_warning-destroy-vm-on-host-delete.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[WARNING]
====
By default, if a host entry that is associated with a virtual machine is deleted, the virtual machine will remain on the compute resource.

If you want {Project} to destroy virtual machines on the compute resource when the associated host entry is deleted, navigate to *Administer* > *Settings* > *Provisioning* and set the *Destroy associated VM on host delete* setting to *Yes*.

To avoid destroying virtual machines in this situation, disassociate the virtual machine from {Project} without removing it from the compute resource or keep the setting set to *No*.
====
1 change: 1 addition & 0 deletions guides/doc-Provisioning_Virtual/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
include ../common/Makefile
1 change: 1 addition & 0 deletions guides/doc-Provisioning_Virtual/common
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../common
1 change: 1 addition & 0 deletions guides/doc-Provisioning_Virtual/docinfo.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../common/docinfo.html
17 changes: 17 additions & 0 deletions guides/doc-Provisioning_Virtual/docinfo.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<title>{ProvisioningVirtualDocTitle}</title>
<subtitle>Provision virtual machines on virtualization infrastructure by using images</subtitle>
<productname>Red Hat Satellite</productname>
<productnumber>{ProjectVersion}</productnumber>
<abstract>
<para>
TODO
Copy link
Contributor Author

@Lennonka Lennonka Jan 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Note to self: TODO

"Overture is composed last."

</para>
</abstract>
<authorgroup id="Author_Group">
<author>
<firstname>Red Hat Satellite</firstname>
<surname>Documentation Team</surname>
<email>[email protected]</email>
</author>
</authorgroup>
<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
1 change: 1 addition & 0 deletions guides/doc-Provisioning_Virtual/images/common
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../common/images
51 changes: 51 additions & 0 deletions guides/doc-Provisioning_Virtual/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
include::common/attributes.adoc[]
include::common/header.adoc[]
:context: provisioning-virtual
:provisioning-virtual:

= {ProvisioningVirtualDocTitle}

// This guide is not ready for stable releases
Comment on lines +5 to +8
Copy link
Contributor

Choose a reason for hiding this comment

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

question: Do you have reasons to believe that the guide would not work for unstable and/or foreman-el/foreman-deb?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It probably should work for all builds, since images are not part of Katello. However, right now I'm not sure it works at all and I would prefer to revisit this question later :))

Copy link
Contributor

Choose a reason for hiding this comment

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

I vote for making this guide "working" for all stable releases. I'll keep it in mind during the review

ifdef::HideDocumentOnStable[]
include::common/modules/snip_guide-not-ready.adoc[]
endif::[]
ifndef::HideDocumentOnStable[]

ifdef::satellite[]
include::common/modules/proc_providing-feedback-on-red-hat-documentation.adoc[leveloffset=+1]
endif::[]

include::common/assembly_introduction-to-provisioning.adoc[leveloffset=+1]

include::common/assembly_preparing-client-platforms.adoc[leveloffset=+1]

include::common/assembly_preparing-templates-for-provisioning.adoc[leveloffset=+1]

include::common/assembly_preparing-networking.adoc[leveloffset=+1]

include::common/assembly_security-settings.adoc[leveloffset=+1]

include::common/modules/con_provisioning-contexts.adoc[leveloffset=+1]

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

include::common/modules/proc_using-novnc-to-access-virtual-machines.adoc[leveloffset=+1]

include::common/assembly_provisioning-virtual-machines-kvm.adoc[leveloffset=+1]

include::common/assembly_provisioning-virtual-machines-rhv.adoc[leveloffset=+1]

include::common/assembly_provisioning-virtual-machines-vmware.adoc[leveloffset=+1]

ifndef::satellite[]
include::common/assembly_provisioning-virtual-machines-proxmox.adoc[leveloffset=+1]
endif::[]

include::common/assembly_provisioning-virtual-machines-kubevirt.adoc[leveloffset=+1]

[appendix]
include::common/modules/ref_host-parameter-hierarchy.adoc[leveloffset=+1]

[appendix]
include::common/modules/ref_permissions-required-to-provision-hosts.adoc[leveloffset=+1]
endif::[]
Loading