Bug 1471548

Summary: [Docs][3.6][Upgrade] Fixes for chapter 3.4 (el6->3l7 upgrade)
Product: Red Hat Enterprise Virtualization Manager Reporter: Marina Kalinin <mkalinin>
Component: DocumentationAssignee: Byron Gravenorst <bgraveno>
Status: CLOSED CURRENTRELEASE QA Contact: Tahlia Richardson <trichard>
Severity: high Docs Contact:
Priority: high    
Version: 3.6.10CC: lbopf, lsurette, mkalinin, rbalakri, srevivo, ykaul, ylavi
Target Milestone: ovirt-4.1.5   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2017-08-23 23:42:35 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: Docs RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Marina Kalinin 2017-07-16 20:20:08 UTC
Upgrade Guide, chapter 3.4 - Upgrading Hosts in a Cluster from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7 [1]:

Part I:
~~~~~~~
- Provide a link to the table from the installation guide[3] under the first Important section.
- Use Next Generation RHVH in the first sentence there, it will be more clear.  Right now you have to read it 5 times to start noticing the difference. 
- RHVH 3.6 and RHEV-H 7 are super confusing. They are both 3.6 and based RHEL7. I suggest: do not use that notation at all, but reference to the new host as Next Generation RHVH.

Part II:
~~~~~~~
The Note does not really makes sense. The first sentence - yes, the second - no. Remove it or fix it. 

Part III:
~~~~~~~
Sections 4-6 are not clear either: so, we put host in maintenance, reinstall it with new OS, update the ssh key (by taking the original value from the host?? not clear) and then clicking Reinstall button? I do not understand that. 
Why section 5 is useful?
Are the users actually expected to reinstall the host with new OS in section 4? I believe so, but it is not clear at all.
And if we are done in section 4 reinstalling, why do we need section 6 to reinstall again? 

Please someone clarify.

[2] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.6/html-single/Installation_Guide/index.html#chap-Introduction_to_Hypervisor_Hosts
[2] https://access.redhat.com/downloads/content/150/ver=3.6/rhel---6/3.6/x86_64/product-software
[1] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.6/html-single/Upgrade_Guide/index.html#Upgrading_Hosts_in_a_Red_Hat_Enterprise_Linux_6_Cluster_to_Red_Hat_Enterprise_Linux_7

Comment 1 Marina Kalinin 2017-07-16 20:20:50 UTC
Yaniv, maybe you can clarify please, part III ?

Comment 2 Yaniv Lavi 2017-07-18 09:24:10 UTC
(In reply to Marina from comment #0)
> 
> Part III:
> ~~~~~~~
> Sections 4-6 are not clear either: so, we put host in maintenance, reinstall
> it with new OS, update the ssh key (by taking the original value from the
> host?? not clear) and then clicking Reinstall button? I do not understand
> that. 
> Why section 5 is useful?
> Are the users actually expected to reinstall the host with new OS in section
> 4? I believe so, but it is not clear at all.
> And if we are done in section 4 reinstalling, why do we need section 6 to
> reinstall again? 
> 

Installing the OS is 4.A.c and 4.B.c, so that should be clear.
Section 5 is needed to be able to connect to the now reinstalled host.
Reinstall in section 6 is the reinstall the oVirt parts of the host, since this is now a new OS.

Please let us know if you have suggested improvements. I agree that the work reinstall appears in two different contexts, so it can be confusing.

Comment 3 Lucy Bopf 2017-07-25 01:31:43 UTC
Marina, if we add to the documentation the additional context that Yaniv provided, is this enough to fix Part III?

Comment 4 Marina Kalinin 2017-08-08 10:54:46 UTC
Thanks Yaniv, for clarifying.

So, how I suggest to fix it now:

4. Upgrade each host: 
-> Here I have a lot of uncertainty how to phrase. Since in my opinion, this is not upgrade, but actually reinstall of the OS from RHEL6 to RHEL7. Using the word "upgrade" sounds super confusing. Maybe we can say instead:
Reinstall each host with RHEL 7 / with new operating system ?

5. In the Administration Portal, update the host's SSH fingerprint:
--> Update host's new SSH fingerprints in the Administrator Portal to allow the manager to connect to the host after reinstallation:
( can skip the second part explaining why, if you want)

6. Reinstall the host:
--> Install RHV packages on the host:

Comment 5 Lucy Bopf 2017-08-09 07:15:50 UTC
Thanks very much for the feedback, Marina!

I'll target and assign this now.

Comment 6 Lucy Bopf 2017-08-09 07:16:37 UTC
Assigning to Byron for review.