Skip to content
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.

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

Upstreamize VM subscriptions guide #3528

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
21 changes: 21 additions & 0 deletions guides/common/assembly_managing-virt-who-configurations.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
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]
3 changes: 3 additions & 0 deletions guides/common/assembly_overview-of-vm-subscriptions.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
include::modules/con_virtual-machine-subscriptions-overview.adoc[]

include::modules/ref_virt-who-configuration-overview.adoc[leveloffset=+1]
7 changes: 7 additions & 0 deletions guides/common/assembly_troubleshooting-virt-who.adoc
Original file line number Diff line number Diff line change
@@ -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]
1 change: 1 addition & 0 deletions guides/common/attributes-titles.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

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

The DocURL for Satellite downstream has to match the title in snake_case, otherwise Pantheon will refuse to build it. Please update it in attributes-satellite.adoc

:ContentManagementDocTitle: Managing content
:ConvertingHostRHELDocTitle: Converting a host to RHEL
:DeployingAWSDocTitle: Deploying {ProjectName} on Amazon Web Services
Expand Down
10 changes: 10 additions & 0 deletions guides/common/modules/con_deploying-virt-who-configurations.adoc
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[id="managing-virt-who-configurations"]
= Managing virt-who configurations
apinnick marked this conversation as resolved.
Show resolved Hide resolved

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.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions guides/common/modules/con_troubleshooting-virt-who.adoc
Original file line number Diff line number Diff line change
@@ -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:{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.
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
[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)
* {OpenStack}
* {oVirt}
* Microsoft Hyper-V
* Nutanix AHV
* {KubeVirt}

ifdef::satellite[]
:FeatureName: The {KubeVirt} hypervisor
include::snip_technology-preview.adoc[]
endif::[]

Original file line number Diff line number Diff line change
@@ -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.
19 changes: 19 additions & 0 deletions guides/common/modules/proc_checking-virt-who-status.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
[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
* List the status of all virt-who instances by entering 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}.
131 changes: 131 additions & 0 deletions guides/common/modules/proc_creating-a-virt-who-configuration.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
[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`
* {KubeVirt}: `cnv`
<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.
--
Original file line number Diff line number Diff line change
@@ -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_
----
Original file line number Diff line number Diff line change
@@ -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_
----
Loading