Hide Forgot
Document URL: https://access.redhat.com/documentation/en/red-hat-satellite/6.2/single/installation-guide#upgrading_satellite_server_and_capsule_server Section Number and Name: Chapter 6 Describe the issue: In chapter 6 of the install guide, it should be very clear the differences in the upgrade process between - upgrading from 6.1.x to 6.2.x (which you will run katello-installer) & - upgrading from 6.2.x to 6.2.x+1 (which you will not run katello-installer) Chapter 6 currently covers both scenarios (in sections 6.1->6.6 & sections 6.7 respectively). Suggestions for improvement. - Either in the beginning of the chapter denote the differences above, otherwise an end-user may perceive the docs to be incorrect and/or run the incorrect steps. OR - Move section 6.7 (Upgrading Between Minor Versions of Satellite) to a new chapter to make it more apparent. - Place the directions for 'Upgrading Between Minor Versions of Satellite' first in the install guide as it is the more common process. Lastly, we may want to consider refactoring our terminology: Upgrade = moving Satellite from 6.1.x to 6.2.x (this is a big deal, requires a lot of work, downtime, etc). Update = moving Satellite from 6.2.x to 6.2.x+1 (this is a much less invasive process) .
Hello Rich Thank you for raising this bug. (In reply to Rich Jerrido from comment #0) > Document URL: > > https://access.redhat.com/documentation/en/red-hat-satellite/6.2/single/ > installation-guide#upgrading_satellite_server_and_capsule_server > > > Section Number and Name: > > Chapter 6 > > Describe the issue: > > In chapter 6 of the install guide, it should be very clear the differences > in the upgrade process between > > - upgrading from 6.1.x to 6.2.x (which you will run katello-installer) & That is not quite right. The `katello-installer` command is only used for upgrading between minor versions, or should we say point releases, of 6.1.X If you follow the procedures in the Installation Guide you will see that the command to upgrade from 6.1.X to 6.2.X is `satellite-installer --scenario satellite --upgrade` and that this command is only used after changing the repositories on the base system and downloading the new packages. > - upgrading from 6.2.x to 6.2.x+1 (which you will not run katello-installer) A while ago I added a new section "Upgrading Between Minor Versions of Satellite" to both the 6.2 and 6.1 Installation Guides. See [1] and [2] > > > Chapter 6 currently covers both scenarios (in sections 6.1->6.6 & sections > 6.7 respectively). As number can change, I will paste the section headings: 6.1. Upgrading the Satellite Server 6.2. Upgrading Disconnected Satellite Server 6.3. Upgrading Capsule Servers 6.4. Upgrading Discovery on Capsule Servers 6.5. Upgrading Satellite Clients 6.6. Upgrading a Self-Registered Satellite Server 6.7. Upgrading Between Minor Versions of Satellite > > > Suggestions for improvement. > > - Either in the beginning of the chapter denote the differences above, We could add some text just under "Supported upgrade paths for Satellite 6.2:" > otherwise an end-user may perceive the docs to be incorrect and/or run the > incorrect steps. OR > - Move section 6.7 (Upgrading Between Minor Versions of Satellite) to a new > chapter to make it more apparent. I will ask our Content Strategist to consider and decide. > - Place the directions for 'Upgrading Between Minor Versions of Satellite' > first in the install guide as it is the more common process. Sounds like a quick fix, but the idea of a new chapter might make it easier to separate. I will ask our Content Strategist to consider and decide. > > > Lastly, we may want to consider refactoring our terminology: > > Upgrade = moving Satellite from 6.1.x to 6.2.x (this is a big deal, requires > a lot of work, downtime, etc). > > Update = moving Satellite from 6.2.x to 6.2.x+1 (this is a much less > invasive process) . I did raise this issue before, but could not get sufficient support. I will find a link to where that was discussed before. Thank you BTW, all upgrade procedures are currently under review here: BZ#1367674 [1] https://access.redhat.com/documentation/en/red-hat-satellite/6.2/paged/installation-guide/chapter-6-upgrading-satellite-server-and-capsule-server#upgrading_between_minor_versions [2] BZ#1362527
Hello Steve Bream Can you please consider the idea in comment 0 of moving "Upgrading Between Minor Versions of Satellite" to the start of the current chapter about upgrading or to move it to a new chapter. Thank you
Hello Steve further to comment 3 why not review the section headers in the chapter while this is chapter is being looked at. For example, "Upgrading the Satellite Server" might be better as "Upgrading a Connected Satellite Server" in order to make it easier to navigate that chapter.
(In reply to Stephen Wadeley from comment #4) > Hello Steve further to comment 3 > > why not review the section headers in the chapter while this is chapter is > being looked at. > > For example, "Upgrading the Satellite Server" might be better as "Upgrading > a Connected Satellite Server" in order to make it easier to navigate that > chapter. Hello Stephen, Thank you for bringing this up. I think that it makes sense from both a "quick fix" perspective and in a user's context to separate upgrades into two chapters - users aren't likely to be doing both at the same time, and separating them should help reduce confusion. Further, the minor upgrade procedure has enough facets to warrant the extra heading. After reading Comment 1, I think that perhaps adding a chapter for upgrading minor versions is the right time to revisit the issue of terminology. Revising the terminology as described in Comment 1 will reduce confusion regarding what steps to follow and prevent redundancy in chapter titles. I suggest: Chapter 6 (current chapter 6, sections 6.1-6.6) Upgrading Satellite Server and Capsule Server Chapter 7 (current section 6.7 "Upgrading Between Minor Versions of Satellite"): Updating Satellite Server, Capsule Server, and Content Hosts We can reinforce the terminology with some introductory text at the beginning of each chapter along the lines of: "Upgrading is the process of migrating your Satellite and Capsule server installations from one release to the next, for example Satellite 6.1 to Satellite 6.2. Upgrades are usually done in order to take advantage of significant new features or capabilities. Because upgrades can involve deprecation of installed code, they can require a significant amount of time. You should plan your workflow to avoid disruption to your operating environment when performing upgrades." and: "Updating is the process of migrating your Satellite and Capsule servers, and Content Hosts to a new minor version. Updates typically patch security vulnerabilities and correct minor issues discovered after code is released. Generally speaking, updates require little time and are non-disruptive to your operating environment. Before updating you should still read the announcement that accompanies the update for specific information." I also like your suggestion to rename section 6.1 to "Upgrading a Connected Satellite Server" to better clarify the flow and create parallelism with the other section headings. So to sum up, the new structure will look like this: 6. UPGRADING SATELLITE SERVER AND CAPSULE SERVER 6.1. Upgrading the Satellite Server 6.1.1. Upgrading a Connected Satellite Server 6.1.2. Removing Redundant Firewall Rules 6.2. Upgrading a Disconnected Satellite Server 6.2.1. Upgrading Satellite Server 6.1 6.2.2. Upgrading To Disconnected Satellite Server version 6.2 6.3. Upgrading Capsule Servers 6.4. Upgrading Discovery on Capsule Servers 6.5. Upgrading Satellite Clients 6.6. Upgrading a Self-Registered Satellite Server New Chapter: 7. UPDATING SATELLITE SERVER, CAPSULE SERVER, AND CONTENT HOSTS 7.1 Updating a Satellite Server 7.2 Updating a Capsule Server 7.3 Updating Content Hosts If there are different procedures for updating connected and disconnected Satellite servers, those sections in Chapter 7 should follow the naming conventions of the analogous sections in Chapter 6. I feel like that was a very long answer, please ping me if I've made things more confusing.
Hello Steve Thank you for comment 5 Some things to note: Even a disconnected system needs a manifest Even a disconnected system should have the host based firewall configured. Note that "Satellite Server" is the product name, so if we use "the Satellite Server" it can be interpreted as "the Satellite server" which we would like to avoid as it gets confusing when we talk about the "Satellite Server" application running on an OS on some server hardware (a.k.a. the base system). How about: 6. UPGRADING SATELLITE SERVER AND CAPSULE SERVER 6.1. Upgrading to Satellite Server 6.2 <-- Add the version at the start 6.1.1. Upgrading the Subscription Manifest 6.1.3. Removing Redundant Firewall Rules {that step would not be needed except when going 6.1.X to 6.2.X} 6.2. Upgrading a Connected Satellite Server 6.3. Upgrading a Disconnected Satellite Server Re: Upgrading Satellite Server 6.1 I think we should drop this section for reasons of consistency. We can trim the text and move those links to the "Before You Begin" section. BZ#1382535 is asking me to add links to all the prerequisite sections. Re: 6.2.2. Upgrading To Disconnected Satellite Server version 6.2 I think we could just drop that subheading, and no need to mention version if we drop the other stuff as above. and then the rest as you suggested. = = = = = I'll implement the changes in the branch for BZ#1367674 first, then cherry-pick them to this bugs branch. That way I can check for merge conflicts. Would be nice if we could resolve that bug first. If there are lots of merge conflicts, we can just use the branch for BZ#1367674 and drop this one on closing. Thank you /me adds "create parallelism" to list of words to use in meetings.
Thank you Stephen, I like the structure you've proposed in comment 6. As long as we're meeting our commitments to support previous releases, I agree that we should drop the section on upgrading Satellite 6.1. I also agree that the content in 6.2.2 will be covered well enough by the preceding information if the versions are removed. Thank you. (and you want to use "create parallelism" for your meeting bingo card, don't you? :)
Hello Steve " read the announcement " seems a little vague I just noticed we do not link to the release notes from the Installation Guide. We need to find suitable place for this: https://access.redhat.com/documentation/en/red-hat-satellite/[Red Hat Satellite Release Notes] Thank you
(In reply to Stephen Wadeley from comment #8) > Hello Steve > > " read the announcement " seems a little vague > > I just noticed we do not link to the release notes from the Installation > Guide. > > We need to find suitable place for this: > > https://access.redhat.com/documentation/en/red-hat-satellite/[Red Hat > Satellite Release Notes] > > Thank you Hi Stephen, I see your point on "read the announcement" - I think we're a little hamstrung by the desire to make this applicable across z stream releases, which can make it hard to link to the release notes. It's also an old habit of caution, to point users to the notes for a specific update in case something in the current update isn't compatible with their existing environment. So it's really a generic statement that perhaps is a bit too generic. Perhaps "Before updating, check the release notes for potential conflicts."
Hello Stephen, I agree with your placement, of the update/upgrade information, and with your suggestion to treat the lack of information on adding a manifest as a separate bug. Russell, let's go ahead and merge these changes and mark this one as done. Thanks to you both.