Bug 1118766 - [RFE][Sprint 48] Nothing describes how HA apps work or how to use them
Summary: [RFE][Sprint 48] Nothing describes how HA apps work or how to use them
Alias: None
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation
Version: 2.1.0
Hardware: Unspecified
OS: Unspecified
Target Milestone: ---
: ---
Assignee: brice
QA Contact: Alex Dellapenta
: 1133631 (view as bug list)
Depends On:
TreeView+ depends on / blocked
Reported: 2014-07-11 13:32 UTC by Luke Meyer
Modified: 2015-07-20 00:20 UTC (History)
5 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Last Closed: 2014-11-12 01:04:55 UTC

Attachments (Terms of Use)

Description Luke Meyer 2014-07-11 13:32:11 UTC
We have a few references in the manual to administratively allowing HA apps, and one obscure reference in the REST API guide for how to actually enable them.

We have the PEP (http://openshift.github.io/documentation/openshift-pep-005-available-web.html) which was partially implemented.
We have the blog article (https://www.openshift.com/blogs/announcing-openshift-origin-3).

Nothing pulls it all together and describes all the workings and options in one place.

1. How does a user make their app HA? (REST API only currently)
2. When are secondary LB gears created? What controls this?
3. How does auto-scaling work?
4. How "HA" is the app? What happens if the first gear goes away?
   (no auto-scaling, can't git push; also DB gears of course aren't HA yet)
5. How do requests get directed to secondary LB gears?
   (via the HA alias and their router setup)

Comment 2 brice 2014-07-15 01:06:56 UTC
Hey Luke.

Thanks for the extra info on this BZ. I've done up a first draft, but before I show it, can I ask a few questions:

1. How "partially implemented" was the PEP from above? ie, if I use the info from that, am I going to be putting in some incorrect information?

2. Do you know if this ties into this BZ:


I can't seem to find any info on this one, but they sound _kinda_ similar. 


Comment 3 Luke Meyer 2014-07-15 14:50:50 UTC
(In reply to brice from comment #2)

> 1. How "partially implemented" was the PEP from above? ie, if I use the info
> from that, am I going to be putting in some incorrect information?

The entire routing layer is currently an implementation detail left to the administrator. There is no router component.

The PEP proposes a couple methods of making scaling decisions - the implementation leaves it to one head gear.

The PEP indicates that LB gears could route to a subset of service gears - in the implementation, all route to all.

Just a few details I noticed quickly - a lot more need to be filled in.

> 2. Do you know if this ties into this BZ:
> https://bugzilla.redhat.com/show_bug.cgi?id=1062468

Well, not really - that was about improvements to the scaling algorithm, but it could be a good place to talk about that too.

Comment 4 Luke Meyer 2014-07-24 16:41:02 UTC
Some source material:


Comment 6 brice 2014-09-02 06:52:43 UTC
Hi, Luke.

So I'm sure you're aware that this isn't a small task. And you're definitely right in that the info is currently all over the place. Unfortunately, this is because each guide is aimed at a different audience. So for this BZ specifically, I've put a small "this is what high-availability is" section in the User Guide which links the reader to already-existing sections of the Admin Guide and the Deploy Guide, then later on put in a section on making apps highly-available (which ties into another BZ from Eric [1]). 

I know this probably is nowhere near complete, but I thought I'd let you in on the plan so far, and also what I have so far.

Please let me know if I've got any information incorrect or if you disagree with anything. I'm all ears!


[1] https://bugzilla.redhat.com/show_bug.cgi?id=1131666

Comment 8 brice 2014-09-03 01:44:16 UTC

I've also added a note to the bottom of the section in the Admin Guide that says "Now go to the User Guide for a procedure on how to make apps HA".

Also, I went to add a similar note to the section of the Deployment Guide where we set up a load-balancer, but it ends on the same topic in the Admin Guide (topic sharing!).

Comment 10 brice 2014-09-16 06:01:23 UTC

Changed some stuff in the User Guide to more reflect Luke's question on how auto-scaling works.

Comment 13 brice 2014-09-18 04:25:10 UTC
Luke, thanks again for the detailed review. I've rewritten the three topics you mentioned above. I think this new edit more closely aligns with the layout you are trying to suggest above. 

I'm not going to go through each edit I made cos obviously I made a lot. But here's a few notes:

1. I removed a lot of the information about outages. I do think this is more for the Admin, and might even be a little to simple for an admin. 

2. I kept the topic about manually scaling an app, but instead provided a link to the topic in the User Guide rather than doubling up on the into (I realized I had done that a bit here).

3. I tried to take in all your rearranging suggestions. I hope I followed them correctly.

4. Also removed the zones info. If you that info needs to be in the docs somewhere, this may be a story for another BZ.

5. I hope I clarified the curl/Rest API stuff correctly.

I think that's all. Please let me know what you think and if it requires any more edits.


Comment 16 brice 2014-09-30 03:11:03 UTC
Luke, if you didn't pick at things then the docs would be in a much worse state than what they currently are :)

I've taken in your suggestions. I've made a few sentence level edits, but nothing that changes the meanings (I think). I won't put this onto QA just yet, but it'd be great if you can give one final ack that this is all good. 


Comment 17 Luke Meyer 2014-09-30 12:28:57 UTC
User guide looks fine. For admin guide, I'm still not seeing the distinction between routing layer and LB layer. For reference, see Terms under http://openshift.github.io/documentation/openshift-pep-005-available-web.html

Anywhere you have "external load balancer" should really be "external routing layer" or just "routing layer". I really think it's too confusing if you refer to both as load balancing. Gears inside OSE load balance. Something external routes.

Also, step 2 should come after step 3, and probably just be combined with step 4. Setting ROUTER_HOSTNAME is only relevant if MANAGE_HA_DNS="true", and neither one makes sense until after the discussion of why a DNS entry is needed for the HA app.

Comment 18 brice 2014-10-01 04:10:27 UTC
Luke, you're right. I've gone through the Admin Guide and the Deployment Guide and made the distinction more clear. I'd say it's in a better state now. can I ask for a final ack?


Comment 21 brice 2014-10-02 06:37:07 UTC
Deploy Guide

Ah, yes. I had changed the title, but there was something fiddley going on preventing it from showing up. Fixed now.

Bullet point added. But is that all you meant? I think if you want me to add anything extra from your new blog post then a separate BZ might have to be raised titles something about "Implementing a Routing Layer". More than happy to work on that with you again, though. I don't doubt there's some good points in there we can throw in :)

Admin Guide

Done. Well, change to:
"In order to create DNS entries for high-availability applications that point to the routing layer, OpenShift Enterprise adds either a prefix or suffix, or both, to the regular application name:"

Mainly cos CCS rules against and/or

Deleted that last bit too. I thought you had suggested that to be added. My mistake :)

Anything more suggestions?

Comment 22 Luke Meyer 2014-10-02 17:23:40 UTC
(In reply to brice from comment #21)

> Bullet point added. But is that all you meant?

For now yes :) The info from my blog post may be germane for a future request.

> Deleted that last bit too. I thought you had suggested that to be added. My
> mistake :)

I wanted to "mention at the end that OSE still only creates the DNS record if MANAGE_HA_DNS=true." Not sure the sequence of events but the existing wording on now-step-3 seems to make that clear enough.

Thanks, +1 now!

Comment 23 brice 2014-10-03 00:45:03 UTC
Ok! Thanks, Luke. I'll put this onto QA

For QA:
User guide
- Added info section on HA apps
- Edited existing info on Scalable apps
- Added section on making apps HA

Admin guide
- Edited section on Enabling Support for HA apps

Dep guide
- Edit of the routing layer sections to tie in with this
- Tried to make the difference between routing layer and load balancer more obvious
- updated same section from admin guide that's being shared here

Comment 27 Alex Dellapenta 2014-10-24 20:51:30 UTC
*** Bug 1133631 has been marked as a duplicate of this bug. ***

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