Bug 1305555 - [RFE] Add quickstart guide
[RFE] Add quickstart guide
Status: CLOSED CURRENTRELEASE
Product: Red Hat Satellite 6
Classification: Red Hat
Component: Documentation (Show other bugs)
Unspecified
Unspecified Unspecified
medium Severity medium (vote)
: Beta
: 6.2
Assigned To: Allison Heslin
satellite-doc-list
: FutureFeature
Depends On:
Blocks: 260381
  Show dependency treegraph
 
Reported: 2016-02-08 10:01 EST by Deon Ballard
Modified: 2016-10-26 21:45 EDT (History)
9 users (show)

See Also:
Fixed In Version:
Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2016-10-26 21:45:03 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Deon Ballard 2016-02-08 10:01:40 EST
We currently have a getting started procedure on the product page:
https://access.redhat.com/products/red-hat-satellite/#getstarted

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.

Suggested environment:

* Internal Capsule
* Internal services for DNS, DHCP, and TFTP
* Single server

Are there any other considerations?

Thanks!
Comment 1 Rich Jerrido 2016-02-08 12:25:31 EST
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 [1] 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. 



[1] - https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html-single/Provisioning_Guide/index.html
Comment 3 Marc Richter 2016-02-09 15:53:54 EST
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)
Comment 4 Andrew Dahms 2016-02-10 04:53:33 EST
Setting release flags.
Comment 5 Allison Heslin 2016-02-22 14:20:25 EST
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?
Comment 6 Rich Jerrido 2016-02-23 11:10:05 EST
(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.
Comment 7 Joe Giordano 2016-02-25 10:22:12 EST
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.
Comment 8 Mike McCune 2016-03-28 18:13:31 EDT
This bug was accidentally moved from POST to MODIFIED via an error in automation, please see mmccune@redhat.com with any questions
Comment 9 Allison Heslin 2016-04-29 14:08:25 EDT
Since this guide is now out for Beta, I'm marking this as Verified and any updates can be tracked separately.
Comment 10 Andrew Dahms 2016-10-26 21:45:03 EDT
This content is now live on the Customer Portal.

Closing.

Note You need to log in before you can comment on or make changes to this bug.