Upstreamize VM subscriptions guide

guides/common/assembly_overview-of-vm-subscriptions.adoc

@@ -0,0 +1,5 @@
+include::modules/con_virtual-machine-subscriptions-overview.adoc[]
+
+include::modules/ref_virt-who-configuration-overview.adoc[leveloffset=+1]
+
+include::modules/proc_checking-for-subscriptions-that-require-virt-who.adoc[leveloffset=+1]

guides/common/assembly_troubleshooting-virt-who.adoc

@@ -0,0 +1,9 @@
+include::modules/con_troubleshooting-virt-who.adoc[]
+
+include::modules/proc_checking-virt-who-status.adoc[leveloffset=+1]
+
+include::modules/proc_enabling-rhsm-debug-logging.adoc[leveloffset=+1]
+
+include::modules/proc_virt-who-does-not-report-to-satellite.adoc[leveloffset=+1]
+
+include::modules/ref_troubleshooting-virt-who.adoc[leveloffset=+1]

guides/common/attributes-satellite.adoc

@@ -16,6 +16,7 @@
 :APIDocURL: {BaseURL}using_the_satellite_rest_api/index#
 :ConfiguringLoadBalancerDocURL: {BaseURL}configuring_capsules_with_a_load_balancer/index#
 :ConfiguringUserAuthenticationDocURL: {BaseURL}configuring_authentication_for_red_hat_satellite_users/index#
+:ConfiguringVMSubscriptionsDocURL: {BaseURL}configuring_virt-who_for_virtual_machine_subscriptions/index#
 :ContentManagementDocURL: {BaseURL}managing_content/index#
 :InstallingServerDisconnectedDocURL: {BaseURL}installing_satellite_server_in_a_disconnected_network_environment/index#
 :InstallingServerDocURL: {BaseURL}installing_satellite_server_in_a_connected_network_environment/index#

guides/common/attributes-titles.adoc

@@ -6,6 +6,7 @@
 :AppCentricDeploymentDocTitle: Deploying hosts by using application centric approach
 :ConfiguringLoadBalancerDocTitle: Configuring {SmartProxies} with a load balancer
 :ConfiguringUserAuthenticationDocTitle: Configuring authentication for {ProjectName} users
+:ConfiguringVMSubscriptionsDocTitle: Configuring virt-who for virtual machine subscriptions
 :ContentManagementDocTitle: Managing content
 :ConvertingHostRHELDocTitle: Converting a host to RHEL
 :DeployingAWSDocTitle: Deploying {ProjectName} on Amazon Web Services
@@ -34,7 +35,6 @@
 :UpgradingDisconnectedPreviousDocTitle: Upgrading disconnected {ProjectName} to {ProjectVersionPrevious}
 
 // Not upstreamed
-:ConfiguringVMSubscriptionsDocTitle: Configuring virtual machine subscriptions
 :ConversionsToolkitDocTitle: Converting hosts to RHEL by using Satellite conversions toolkit
 
 // Overrides for titles per product

guides/common/modules/con_configuring-virt-who-for-provider.adoc

@@ -0,0 +1,39 @@
+ifeval::["{context}" == "vmware-virt-who"]
+:provider: VMware vSphere
+:targets: {ProjectServer}, {SmartProxyServer}, or on a dedicated {EL} server
+endif::[]
+ifeval::["{context}" == "kvm-virt-who"]
+:provider: {EL} Virtualization
+:targets: hypervisor
+endif::[]
+ifeval::["{context}" == "openstack-virt-who"]
+:provider: {OpenStack}
+:targets: hypervisor
+endif::[]
+ifeval::["{context}" == "hyperv-virt-who"]
+:provider: Microsoft Hyper-V
+:targets: {ProjectServer}, {SmartProxyServer}, or on a dedicated {EL} server
+endif::[]
+ifeval::["{context}" == "nutanix-virt-who"]
+:provider: Nutanix AHV
+:targets: {ProjectServer}, {SmartProxyServer}, or on a dedicated {EL} server
+endif::[]
+ifeval::["{context}" == "kubevirt-virt-who"]
+:provider: {KubeVirt}
+:targets: hypervisor
+endif::[]
+
+[id="deploying-virt-who-configuration_{context}"]
+= Configuring virt-who for {provider}
+
+You create a virt-who configuration for {provider} by using the {ProjectWebUI} or the CLI on the {ProjectServer}.
+
+Then, you deploy the generated script or Hammer command on the {targets}.
+
+ifdef::kubevirt-virt-who[]
+ifdef::satellite[]
+:FeatureName: The {KubeVirt} hypervisor
+include::snip_technology-preview.adoc[]
+endif::[]
+endif::[]
+

guides/common/modules/con_managing-virt-who-configurations.adoc

@@ -0,0 +1,8 @@
+[id="managing-virt-who-configurations"]
+= Managing virt-who configurations
+
+You can check for subscriptions that require a virt-who configuration.
+
+Then, you create a virt-who configuration and deploy it on a hypervisor or virtualization manager.
+
+Optionally, you can edit or delete a virt-who configuration.

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

@@ -10,14 +10,8 @@ You can create a compute resource for {KubeVirt} so that you can provision and m
 ifdef::satellite[]
 Note that template provisioning is not supported for this release.
 
-[IMPORTANT]
-====
-The {KubeVirt} compute resource is a Technology Preview feature only.
-Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete.
-Red Hat does not recommend using them in production.
-These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
-For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.
-====
+:FeatureName: The {KubeVirt} compute resource
+include::snip_technology-preview.adoc[]
 endif::[]
 
 .Prerequisites

guides/common/modules/con_troubleshooting-virt-who.adoc

@@ -0,0 +1,6 @@
+[id="troubleshooting-virt-who"]
+= Troubleshooting virt-who
+
+You can troubleshoot virt-who by checking the service status, logs, and by identifying configuration issues.
+
+For more information, see link:{RHDocsBaseURL}subscription_central/1-latest/html/getting_started_with_rhel_system_registration/adv-reg-rhel-config-vm-sub_#virt-who-troubleshooting-methods_[Virt-who troubleshooting methods] and link:{RHDocsBaseURL}subscription_central/1-latest/html/getting_started_with_rhel_system_registration/adv-reg-rhel-config-vm-sub_#virt-who-troubleshooting-scenarios_[Virt-who troubleshooting scenarios] in _Getting Started with RHEL System Registration_ in the Subscription Central documentation.

guides/common/modules/con_virtual-machine-subscriptions-overview.adoc

@@ -0,0 +1,23 @@
+[id="virtual-machine-subscriptions-overview"]
+= Virt-who and virtual machine subscriptions
+
+Virtual machines (VMs) require host-based subscriptions instead of physical subscriptions.
+Many host-based subscriptions include entitlements for unlimited VMs.
+
+virt-who queries the virtualization platform and reports hypervisor and VM information to {Project}.
+You can view your subscription usage by using the Subscriptions service on the {RHCloud}.
+
+You can configure virt-who for the following virtualization platforms:
+
+* {EL} Virtualization (KVM)
+* VMware vSphere
+* Nutanix AHV
+* Microsoft Hyper-V
+* {OpenStack}
+* {KubeVirt}
+
+ifdef::satellite[]
+:FeatureName: The {KubeVirt} hypervisor
+include::snip_technology-preview.adoc[]
+endif::[]
+

guides/common/modules/proc_checking-for-subscriptions-that-require-virt-who.adoc

@@ -0,0 +1,9 @@
+[id="checking-for-subscriptions-that-require-virt-who_{context}"]
+= Checking for subscriptions that require virt-who
+
+You can check for subscriptions that require virt-who configuration.
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Content* > *Subscriptions*.
+. Check the *Requires Virt-Who* column of the subscriptions list.
+If a tick is displayed, you must configure virt-who to use that subscription.

guides/common/modules/proc_checking-virt-who-status.adoc

@@ -0,0 +1,20 @@
+[id="checking-virt-who-status"]
+= Checking virt-who status
+
+You can check the status of virt-who by using the {ProjectWebUI} or the Hammer CLI tool.
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*.
+. Check the *Status* column of each virt-who instance.
++
+The `OK` status indicates that virt-who is successfully connecting to {ProjectServer} and reporting the virtual machines managed by each hypervisor.
+
+.CLI procedure
+* List the status of all virt-who instances by entering the following command on {ProjectServer}:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+$ hammer virt-who-config list
+----
++
+The output includes the date and time when each virt-who instance reported to {ProjectServer}.

guides/common/modules/proc_creating-a-virt-who-configuration.adoc

@@ -0,0 +1,197 @@
+ifeval::["{context}" == "vmware-virt-who"]
+:provider: VMware vSphere
+:hypervisor-ui: VMware vSphere / vCenter (esx)
+:hypervisor-cli: esx
+:server: vcenter.example.com
+:username: username_vcenter@example.com
+endif::[]
+ifeval::["{context}" == "kvm-virt-who"]
+:provider: {EL} Virtualization (KVM)
+:hypervisor-ui: libvirt
+:hypervisor-cli: libvirt
+:server: qemu+ssh://root@libvirt.example.com/system
+:username: root
+endif::[]
+ifeval::["{context}" == "openstack-virt-who"]
+:provider: {OpenStack}
+:hypervisor-ui: libvirt
+:hypervisor-cli: libvirt
+:server: qemu:///system
+:username: virt_who_user
+endif::[]
+ifeval::["{context}" == "hyperv-virt-who"]
+:provider: Microsoft Hyper-V
+:hypervisor-ui: Microsoft Hyper-V (hyperv)
+:hypervisor-cli: hyperv
+:server: hypervisor.example.com
+:username: virt_who_user
+endif::[]
+ifeval::["{context}" == "nutanix-virt-who"]
+:provider: Nutanix AHV
+:hypervisor-ui: Nutanix AHV (ahv)
+:hypervisor-cli: ahv
+:server: prism.example.com
+:username: prism_user
+endif::[]
+ifeval::["{context}" == "kubevirt-virt-who"]
+:provider: {KubeVirt}
+:hypervisor-ui: Container-native virtualization
+:hypervisor-cli: cnv
+:server: hypervisor.example.com
+:username: virt_who_user
+endif::[]
+
+[id="creating-a-virt-who-configuration_{context}"]
+= Creating a virt-who configuration
+
+You can create a virt-who configuration for {provider} by using the {ProjectWebUI}.
+To create a virt-who configuration by using the CLI, see xref:cli-creating-a-virt-who-configuration_{context}[].
+
+The virt-who configuration creates a `virt_who_reporter_[id]` user with the `Virt-who Reporter` role, which provides minimal permissions for virt-who reporting to {ProjectServer}.
+This user cannot be manually configured or used to log in to {ProjectServer}.
+
+Local configuration values, in the `/etc/virt-who.d/_conf_name_.conf` file, apply only to the hypervisor or virtualization manager.
+
+Global configuration values, in the `/etc/sysconfig/virt-who` file, apply to all virt-who configurations on the same server.
+These values include `Interval`, `Enable debugging output`, `HTTP Proxy`, and `Ignore Proxy`.
+Redeploying a virt-who configuration on the same server overwrites these values.
+
+.Prerequisites
+* You have imported a subscription manifest that includes a host-based subscription into {ProjectServer}.
+For more information, see xref:checking-for-subscriptions-that-require-virt-who_virt-who-vm-subs[].
+
+ifdef::vmware-virt-who[]
+* You have created a virt-who user with read-only access to all objects in the vCenter Data Center and a non-expiring password on the vCenter Server.
+endif::[]
+
+ifdef::kvm-virt-who,hyperv-virt-who,openstack-virt-who[]
+* You have created a virt-who user with read-only access and a non-expiring password on the hypervisor.
+endif::[]
+
+ifdef::kubevirt-virt-who[]
+* You have created a `kubeconfig` file.
+endif::[]
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*.
+. Click *Create Config*.
+. Complete the following fields:
+* *Name*: Configuration name.
+* *Hypervisor Type*: Select *{hypervisor-ui}*.
+ifdef::vmware-virt-who,hyper-virt-who[]
+* *Hypervisor Server*: FQDN or IP address.
+* *Hypervisor Username*: virt-who user name.
+* *Hypervisor Password*: virt-who user password.
+The password is encrypted when you deploy the configuration.
+endif::[]
+* *Interval*: Virtual machine information reporting interval.
+* *{ProjectServer} FQDN*.
+* *Hypervisor ID*: Select *Hostname* or *UUID*.
+
+. Optional: *Filtering*. Select one of the following options for querying hypervisors:
+* *Unlimited* (default): All hypervisors are queried.
+* *Whitelist*: Specific hypervisors are included.
+* *Blacklist*: Specific hypervisors are excluded.
+** *Filter hosts*: Comma-separated list of included hypervisors.
+** *Exclude hosts*: Comma-separated list of excluded hypervisors.
++
+--
+Specify the host name or UUID according to the hypervisor ID you selected.
+
+.Host names
+
+* You can use wildcards, regular expressions, and special characters in the host name.
+* If you use regular expressions, you must escape the backslashes.
+* If you use special characters, you must enclose the host name in quotation marks.
+--
+ifdef::vmware-virt-who[]
+* *Filter host parents*: Comma-separated list of included cluster IDs.
+* *Exclude host parents*: Comma-separated list of excluded cluster IDs.
+For more information, see link:https://access.redhat.com/solutions/5696481[Using the "Filter Host Parents" and "Exclude Host Parents" Attributes with VMware Clusters] in the _Red{nbsp}Hat Knowledgebase_.
+endif::[]
+
+. You can configure the following logging and proxy options:
+* *Enable debugging output*: Enables debug logging for virt-who.
+* *HTTP Proxy*.
+Example: `http://_proxy.example.com_:3128`.
++
+To use no proxy, leave this field blank; this has the same result as entering `{asterisk}` in the *Ignore Proxy* field.
+* *Ignore Proxy*: Comma-separated list of host names, IP addresses, or domains to bypass existing proxy settings.
+ifdef::kubevirt-virt-who[]
+. Enter the `kubeconfig` file path.
+endif::[]
+ifdef::nutanix-virt-who[]
+. Select *Prism Central* or *Prism Element* from the *Prism Flavor* list.
+. Optional: *Enable AHV Debug*: Enables AHV internal debugging.
+This option provides additional AHV information when you enable both debugging options.
+endif::[]
+
+. Click *Submit*.
+
+[id="cli-creating-a-virt-who-configuration_{context}"]
+== CLI procedure
+
+* On {ProjectServer}, enter the `hammer virt-who-config create` command:
++
+[options="nowrap" subs="+quotes,attributes"]
+----
+$ hammer virt-who-config create \
+--name _My_virt-who_Configuration_ \
+--organizations "_My_Organization_" \
+--interval 720 \ <1>
+--filtering-mode none \ <2>
+--hypervisor-id _hostname_ \ <3>
+--hypervisor-type {hypervisor-cli} \
+--hypervisor-server _hypervisor.example.com_ \ <4>
+--hypervisor-username virt_who_user \ <5>
+ifdef::vmware-virt-who,hyperv-virt-who[]
+--hypervisor-password _<password>_
+endif::[]
+--proxy '_http://proxy.example.com_:3128' \ <6>
+--satellite-url _{foreman-example-com}_
+----
+--
+<1> Optional: Specify the virtual machine information reporting interval, in minutes.
+<2> Specify `none` for no filtering of hypervisors for virt-who queries.
+Specify `whitelist` or `blacklist` to include or exclude hypervisors for virt-who queries.
+<3> Specify `hostname`, `uuid`, or `hwuuid` for the hypervisor ID format.
+* You can use `uuid` to avoid duplication if you rename a hypervisor.
++
+* You can use `hwuuid` for configurations that apply to a virtualization manager instead of an individual hypervisor.
++
+[NOTE]
+====
+You cannot change `hwuuid` to another option after virt-who starts running because this might cause duplicate entries in Subscription Manager.
+====
+
+ifdef::vmware-virt-who[]
+<4> Specify the FQDN or IP address of the vCenter Server.
+endif::[]
+ifdef::kubevirt-virt-who,openstack-virt-who,nutanix-virt-who,kvm-virt-who,hyperv-virt-who[]
+<4> Specify the FQDN or IP address of the hypervisor.
+endif::[]
+<5> Specify the name of the virt-who user you created on the hypervisor.
+<6> Optional.
+--
+
+[id="virt-who configuration example_{context}"]
+== virt-who configuration example
+
+.{provider} virt-who configuration example
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+type={hypervisor-cli}
+hypervisor_id=_hostname_
+ifdef::nutanix-virt-who[]
+prism_central=true
+endif::[]
+owner=Default_Organization
+env=Library
+server=_{server}_
+username=_{username}_
+encrypted_password=$cr_password
+rhsm_hostname=_{foreman-example-com}_
+rhsm_username=virt_who_reporter_1
+rhsm_encrypted_password=$user_password
+rhsm_prefix=/rhsm
+----