Red Hat Bugzilla – Bug 1305555
[RFE] Add quickstart guide
Last modified: 2016-10-26 21:45:03 EDT
We currently have a getting started procedure on the product page:
There is a request from PM to create a quick start guide as part of revamping the install documentation. A quick start guide should focus on a specific, greenfield deployment, so we want to make sure that we nail down the scenario.
* Internal Capsule
* Internal services for DNS, DHCP, and TFTP
* Single server
Are there any other considerations?
Let's define greenfield for the sake of this BZ. It could have one of two meanings:
* An environment that has NO Satellite 6 deployed but has other networking services (DNS, DHCP)
* An environment that has NO Satellite 6 AND NO networking services (DNS, DHCP deployed.
The existing (possibly poorly named) Provisioning Guide  solves the latter usage and does so admirably. However, the scenario as depicted in the Provisioning Guide (you have a VLAN that you completely 'own', and you can enable any service you want) is not representative of the Satellite customer base. The former use case of 'I already have DNS & DHCP, show me how to make Satellite work with it' is MUCH more valid. Most environments have solutions for DNS & DHCP (note: many do not run DHCP).
I'd assert that the proposed quickstart guide, should have the following assumptions/use cases in mind.
* Single Satellite deployment
* Connected deployment topology (sync from CDN & not from Content ISOs)
* Assume that a DNS server exists (optional appendix: integrating Satellite 6.1 with Active Directory - https://access.redhat.com/articles/1527913)
* Assume environment either does NOT have DHCP OR that DHCP is NOT hosted on the Satellite itself.
* Assume kickstart based deployment & not image based.
* Assume deployment uses simple Content Views. (If you want CCVs and other awesomeness, see 10 Steps to an SOE - https://access.redhat.com/articles/1585273)
With those assumptions, I would use the existing Provisioning Guide as a base (since it was purpose built to be short), and refactor it accordingly.
I would make the following changes to the Provisioning Guide to make it more apropos for the use case in question.
* Rewrite Chapters 1 & 2 (since the installation switches will change a LOT now that we'd not be installing DNS & DHCP).
* Add a diagram depicting the example topology.
* Add a new sub-section in chapter 3 describing how to sync a custom product of type 'yum' to represent non Red Hat software that may need to be sync'd.
* Add the new Discovery ISO (https://access.redhat.com/blogs/1169563/posts/2090011) as the preferred boot disk provisioning mechanism. This will cover the use case where the customer does not have DHCP AND the use cases where they have DHCP, but NOT PXE.
* Provide the user with the hammer equivalent for every command that he/she needs to issue.
 - https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html-single/Provisioning_Guide/index.html
I would concur with Rich. I've spent the last day or two setting up my own Sat 6 environment based on the guide.
* Definitely focus on a scenario where DNS and DHCP are out of the hands of the person deploying the system.
* Because of the first point, PXE-less discovery would be swell (again, as per Rich's point). Definitely include step by step on how to make that work.
* It may also be of value to walk through step by step how to properly add an existing Red Hat system into this new Satellite environment. (including flipping the sub from external (if it's already there) to the internal Sat server)
Setting release flags.
A few questions as I start writing...
* Can I create a list of the assumptions in the beginning of the doc so the user knows right away if they can use this guide? I can show you an example of what I mean if necessary.
* Since the person that owns the external DNS might be different than the person doing the install, would a worksheet section be beneficial so the user could gather all of the values they need beforehand?
* Do we worry about certificates or answer files during installation, or is that outside the scope of this guide?
* By single Satellite deployment, are we assuming no external Capsule Servers? Just the internal Capsule?
(In reply to aheslin from comment #5)
> A few questions as I start writing...
> * Can I create a list of the assumptions in the beginning of the doc so the
> user knows right away if they can use this guide? I can show you an example
> of what I mean if necessary.
Definitely. 'Assumptions' & 'Intended Audience' sections are IMHO always welcome. It lets me know if this guide is worth my time AND if I need to get 'other stuff' before starting.
> * Since the person that owns the external DNS might be different than the
> person doing the install, would a worksheet section be beneficial so the
> user could gather all of the values they need beforehand?
Yes. But honestly, integrating with external DNS should be an appendix
> * Do we worry about certificates or answer files during installation, or is
> that outside the scope of this guide?
Nope. Skip these for now. (or put them in the Appendix). If you can't tell, I like appendices.
> * By single Satellite deployment, are we assuming no external Capsule
> Servers? Just the internal Capsule?
correct. Internal capsule only.
I agree with the points made in comments #1 and 3.
There are a number of different ways to provision ISO, PXE, DHCP/no PXE, Discovery with pxe, Discovery via ISO. Having documented workflows would help the customer choose the right solution.
This bug was accidentally moved from POST to MODIFIED via an error in automation, please see firstname.lastname@example.org with any questions
Since this guide is now out for Beta, I'm marking this as Verified and any updates can be tracked separately.
This content is now live on the Customer Portal.