Upstreamize VM subscriptions guide

guides/common/assembly_managing-virt-who-configurations.adoc

@@ -0,0 +1,22 @@
+include::modules/con_managing-virt-who-configurations.adoc[]
+
+include::modules/proc_checking-for-subscriptions-that-require-virt-who.adoc[leveloffset=+1]
+
+include::modules/proc_creating-a-virt-who-configuration.adoc[leveloffset=+1]
+
+include::modules/ref_virt-who-configuration-examples.adoc[leveloffset=+2]
+
+include::modules/con_deploying-virt-who-configurations.adoc[leveloffset=+1]
+
+include::modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc[leveloffset=+2]
+
+include::modules/proc_deploying-a-virt-who-configuration-on-satellite-server.adoc[leveloffset=+2]
+
+include::modules/proc_deploying-a-virt-who-configuration-on-a-capsule.adoc[leveloffset=+2]
+
+include::modules/proc_deploying-a-virt-who-configuration-on-a-separate-rhel-server.adoc[leveloffset=+2]
+
+include::modules/proc_editing-a-virt-who-configuration.adoc[leveloffset=+1]
+
+include::modules/proc_removing-a-virt-who-configuration.adoc[leveloffset=+1]
+

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

@@ -0,0 +1,3 @@
+include::modules/con_virtual-machine-subscriptions-overview.adoc[]
+
+include::modules/ref_virt-who-configuration-overview.adoc[leveloffset=+1]

guides/common/assembly_troubleshooting-virt-who.adoc

@@ -0,0 +1,7 @@
+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]

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

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

@@ -0,0 +1,10 @@
+[id="deploying-virt-who-configurations_{context}"]
+= Deploying virt-who configurations
+
+After you create a virt-who configuration, you download a script from the {ProjectWebUI} to deploy the configuration.
+
+The script installs virt-who and creates the local and global virt-who configuration files.
+
+For {oVirt}, {EL} Virtualization (KVM), and {OpenStack}, you deploy the configuration on the hypervisor specified in the file.
+
+For VMware vSphere, Microsoft Hyper-V, and Nutanix AHV, you deploy the configuration on {ProjectServer}, {SmartProxyServer}, or on a dedicated {EL} server.

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

@@ -0,0 +1,7 @@
+= 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_troubleshooting-virt-who.adoc

@@ -0,0 +1,6 @@
+[id="troubleshooting-virt-who_{context}"]
+= Troubleshooting virt-who
+
+You can troubleshoot virt-who by checking the service status, logs, and by identifying configuration issues.
+
+For more information, see link:https://docs.redhat.com/en/documentation/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:https://docs.redhat.com/en/documentation/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,20 @@
+[id="virtual-machine-subscriptions-overview_{context}"]
+= Virtual machine subscriptions overview
+
+Virtual machines (VMs) require host-based subscriptions instead of physical subscriptions.
+Many host-based subscriptions include entitlements for unlimited VMs.
+
+You can configure and deploy virt-who on your hypervisors.
+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 host-based subscriptions for {EL} VMs on the following virtualization platforms:
+
+* VMware vSphere
+* {EL} Virtualization (KVM)
+* {KubeVirt}
+* {OpenStack}
+* {oVirt}
+* Microsoft Hyper-V
+* Nutanix AHV
+

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

@@ -0,0 +1,10 @@
+[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,21 @@
+[id="checking-virt-who-status_{context}"]
+= 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
+
+* To list the status of all virt-who instances by using the CLI, enter the following command on {ProjectServer}:
++
+----
+$ 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,130 @@
+[id="creating-a-virt-who-configuration_{context}"]
+= Creating a virt-who configuration
+
+You can create a virt-who configuration by using the {ProjectWebUI} or the Hammer CLI tool.
+
+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 are stored in the `/etc/virt-who.d/_conf_name_.conf` file and apply only to the hypervisor or virtualization manager.
+
+Global configuration values, such as `Interval`, `Enable debugging output`, `HTTP Proxy`, and `Ignore Proxy`, apply to all virt-who configurations on the same server and are overwritten if you deploy a new virt-who configuration on that server.
+Global configuration values are stored in the `/etc/sysconfig/virt-who` file.
+
+.Prerequisites
+
+* You have imported a subscription manifest that includes a host-based subscription into {ProjectServer}.
+* VMware vSphere: 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.
+* Microsoft Hyper-V:
+** You have enabled remote management on each hypervisor.
+** You have created a virt-who user with read-only access and a non-expiring password on each hypervisor.
+* {oVirt}, {EL} Virtualization (KVM), {OpenStack}:
+** You have registered the hypervisor to {ProjectServer}.
+** You have created a virt-who user with read-only access and a non-expiring password on each hypervisor.
+* {KubeVirt}: You have created a `kubeconfig` file.
+
+.Procedure
+
+. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*.
+. Click *Create Config*.
+. Complete the following fields:
+* *Name*: Configuration name.
+* *Hypervisor Type*: Select one of the following types:
+** *VMware vSphere / vCenter (esx)*.
+** *Microsoft Hyper-V (hyperv)*.
+** *libvirt*: For {oVirt}, {EL} Virtualization (KVM), or {OpenStack}.
+** *Container-native virtualization*: For {KubeVirt}.
+** *Nutanix AHV (ahv)*.
+
+* VMware vSphere and Microsoft Hyper-V:
+** *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.
+
+* *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.
+--
++
+* vCenter Server:
+** *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_.
+
+. 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.
+. {KubeVirt}: Enter the path in the *Path to kubeconfig file* field.
+. Nutanix AHV:
+* 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.
+
+. Click *Submit*.
+
+.CLI procedure
+
+* On {ProjectServer}, enter the `hammer virt-who-config create` command according to the following example:
++
+[options="nowrap" subs="+quotes"]
+----
+$ 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 libvirt \ <4>
+--hypervisor-server _{foreman-example-com}_ \ <5>
+--hypervisor-username virt_who_user \ <6>
+--proxy '_http://proxy.example.com_:3128' \ <7>
+--satellite-url _server.example.com_
+----
+--
+<1> 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 a hypervisor is renamed.
++
+* 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 entires in Subscription Manager.
+====
+
+<4> Specify the hypervisor type:
+* {EL} Virtualization (KVM), {oVirt}, or {OpenStack}: `libvirt`.
+* VMware vSphere: `esx`.
+* Microsoft Hyper-V: `hyperv`.
+* Nutanix AHV: `ahv`
+<5> Specify the FQDN or IP address of the hypervisor or the vCenter Server.
+<6> Specify the name of the virt-who user you created on the hypervisor.
++
+For VMware vSphere or Microsoft Hyper-V, specify the virt-who user password: `--hypervisor-password <password>`.
+<7> Optional.
+--

guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-capsule.adoc

@@ -0,0 +1,40 @@
+[id="deploying-a-virt-who-configuration-on-a-capsule_{context}"]
+= Deploying a virt-who configuration on a {SmartProxyServer}
+
+For VMware vSphere and Microsoft Hyper-V, you can deploy the virt-who configuration on {SmartProxyServer}.
+
+Global configuration values apply to all virt-who configurations on the same {SmartProxyServer} and are overwritten if you deploy a new virt-who configuration.
+
+.Procedure
+
+. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*.
+. Click a virt-who configuration.
+. Click the *Deploy* tab.
+. Under *Configuration script*, click *Download the script*.
+. Copy the script to {SmartProxyServer}:
++
+[options="nowrap" subs="+quotes"]
+----
+$ scp _deploy_virt_who_config_1_.sh root@_{smartproxy-example-com}_:
+----
+
+. Make the script executable:
++
+[options="nowrap" subs="+quotes"]
+----
+$ chmod +x _deploy_virt_who_config_1_.sh
+----
+
+. Run the script:
++
+[options="nowrap" subs="+quotes"]
+----
+$ sh _deploy_virt_who_config_1_.sh
+----
+
+. After the deployment is complete, delete the script:
++
+[options="nowrap" subs="+quotes"]
+----
+$ rm _deploy_virt_who_config_1_
+----

guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc

@@ -0,0 +1,46 @@
+[id="deploying-a-virt-who-configuration-on-a-hypervisor_{context}"]
+= Deploying a virt-who configuration on a hypervisor or a {SmartProxyServer}
+
+For {oVirt}, {EL} Virtualization (KVM), and {OpenStack}, you deploy the configuration on the hypervisor specified in the file.
+
+Global values apply only to this hypervisor.
+
+.Prerequisites
+
+* You have registered the hypervisor to {ProjectServer}.
+* {oVirt}: You have updated {oVirt} to the latest version so that the minimum virt-who version is available.
+virt-who is available by default on {oVirt}, but you cannot update virt-who by using the `rhel-7-server-rhvh-4-rpms` repository.
+
+.Procedure
+
+. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*.
+. Click a virt-who configuration.
+. Click the *Deploy* tab.
+. Under *Configuration script*, click *Download the script*.
+. Copy the script to the hypervisor:
++
+[options="nowrap" subs="+quotes"]
+----
+$ scp _deploy_virt_who_config_1_.sh root@_hypervisor.example.com_:
+----
+
+. Make the script executable:
++
+[options="nowrap" subs="+quotes"]
+----
+$ chmod +x _deploy_virt_who_config_1_.sh
+----
+
+. Run the script:
++
+[options="nowrap" subs="+quotes"]
+----
+$ sh _deploy_virt_who_config_1_.sh
+----
+
+. After the deployment is complete, delete the script:
++
+[options="nowrap" subs="+quotes"]
+----
+$ rm _deploy_virt_who_config_1_
+----