Bug 1044224

Summary:	6.8.7. Idling and Overcommitment
Product:	OpenShift Container Platform	Reporter:	Luke Meyer <lmeyer>
Component:	Documentation	Assignee:	brice <bfallonf>
Status:	CLOSED CURRENTRELEASE	QA Contact:	ecs-bugs
Severity:	unspecified	Docs Contact:
Priority:	unspecified
Version:	2.0.0	CC:	alyoung, jokerman, libra-onpremise-devel, lmeyer, mmccomas
Target Milestone:	---
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2014-01-06 05:18:45 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:

Description Luke Meyer 2013-12-17 22:56:26 UTC

https://access.redhat.com/site/documentation/en-US/OpenShift_Enterprise/2/html-single/Deployment_Guide/index.html#sect-Idling_and_Overcommitment
6.8.7. Idling and Overcommitment

The idler has changed a little bit -- actually, it changed with OSE 1.2 and we just never documented the change. I noticed a few other things to correct too.


6.8.7.1. Enabling Gear Idling
Procedure 6.19. To Enable Gear Idling
Step 2 and 3 -- are unnecessary now. Actually this section should probably be called "Enabling Gear Un-Idling" as that's what oddjobd is for - it enables any access via httpd to un-idle a gear that has been idled (which would be good to mention). 
oo-idler has gone away too. It might actually be best to rename this section and put it at the end, and start with a new section instead:

---
Manually Idling a Gear
The oo-admin-ctl-gears command can be used to idle, un-idle, and list idle gears, e.g.:
# oo-admin-ctl-gears idlegear 52b0b26f36874dc06e000007
Idling gear 52b0b26f36874dc06e000007... [ OK ]
# oo-admin-ctl-gears listidle
52b0b26f36874dc06e000007 is idled
# oo-admin-ctl-gears unidlegear 52b0b26f36874dc06e000007
Unidling gear 52b0b26f36874dc06e000007... [ OK ]
# oo-admin-ctl-gears listidle
#
---


6.8.7.2. Automated Gear Idling
oo-autoidler has been perversely replaced by oo-auto-idler (with a dash) and now requires its interval in hours, not days. Here's the updated text I'd suggest:
---
The oo-last-access and oo-auto-idler commands can be combined in a cron job to idle inactive gears automatically. oo-last-access compiles the last access time for each gear from web front-end logs. oo-auto-idler idles any gears whose URL has not been accessed and the associated Git repository not updated in a specified interval of hours.
As root, create a cron job, for example /etc/cron.hourly/auto-idler, with the following contents:
###
(
  /usr/sbin/oo-last-access
  /usr/sbin/oo-auto-idler idle --interval 24
) >> /var/log/openshift/node/auto-idler.log 2>&1
###
Then make the file executable:
# chmod +x /etc/cron.hourly/auto-idler

This will run hourly to idle any gears that have been inactive for the last 24 hours (substitute your own desired interval), with some exceptions:
1. Gears that have no web endpoint (e.g. a custom message bus cartridge)
2. Non-primary gears in a scaled app
3. Any gear with UUID listed in /etc/openshift/node/idler_ignorelist.conf

NOTE: If you  use the kickstart or bash script, the configure_idler_on_node function performs this step.

If more complicated idling criteria are desired than what the oo-auto-idler command provides, simply copy it and modify it to incorporate any business logic as a custom script.
---

Comment 2 Luke Meyer 2013-12-17 23:00:42 UTC

I forgot: oo-last-access doesn't count access coming from the node itself. So where I said "oo-last-access compiles the last access time for each gear from web front-end logs." I should have said "oo-last-access compiles the last access time for each gear from web front-end logs, excluding any access originating from the same node the gear is on."

Comment 3 brice 2013-12-18 06:16:38 UTC

Luke, I took all this in and rewrote the Automatic topic, commented out the old Manual topic, and added a new Manual topic, as well as put the Automatic topic on top. It'd be too hard to copy/paste the changes into here. I'll let you see them for yourself :)

Hope it's all up to scratch. Let me know if you'd like me to change anything.

Comment 5 Luke Meyer 2013-12-18 15:03:40 UTC

Looks pretty good, but I'm finding the flow a bit odd now that I look at it. To me, the logical progression would be from manual to automatic.

Also, oddjobd isn't technically required when manually idling. What it's for is allowing automatic un-idling - starting the gear automatically when someone accesses the web app. So the description isn't quite right, and I'd say it probably makes more sense to talk about it after the manual basics.

So here's what I suggest:
1. Move "Manually Idling a Gear" before "Automated Gear Idling".
2. Move the entire part about oddjobd beginning with "Idling a gear requires oddjobd" to a new section about automatic un-idling something like:
---
Automatically Restoring Idle Gears

Web access restores an idle gear via the oddjobd service, which is a local message bus. When idling gears, ensure the oddjobd service is available and is running so that they become available again when a web request is made:
# chkconfig messagebus on
# service messagebus start
# chkconfig oddjobd on
# service oddjobd start
---
3. This line seems kind of unnecessary: "If more complicated idling criteria are desired than what the oo-auto-idler command provides, copy and modify the criteria to incorporate any business logic as a custom script." I'm pretty sure I wrote that originally, but now it seems like odd advice in a manual to tell people to modify what they want to. If they've read through this and they're so inclined, they will see what they need to do. I'd vote to remove it.

Comment 6 Luke Meyer 2013-12-18 19:57:10 UTC

BTW, this should probably be a separate bug, but I thought I'd note... The admin guide description of the idler tools is now totally out of date

https://access.redhat.com/site/documentation/en-US/OpenShift_Enterprise/2/html-single/Administration_Guide/index.html#sect-Idler_Commands

oo-last-access and oo-auto-idler being the only ones left I think.

Comment 7 brice 2013-12-19 00:09:23 UTC

1. Done.

2. Done, with a little rewording.

3. Done. To be honest, I didn't understand why that was there anyway :P

As for the stuff in the Admin Guide, is it as easy as deleting the sections that aren't oo-last-access and oo-auto-idler? That can easily be done.

Comment 9 Luke Meyer 2013-12-19 22:48:49 UTC

(In reply to brice from comment #7)

> As for the stuff in the Admin Guide, is it as easy as deleting the sections
> that aren't oo-last-access and oo-auto-idler? That can easily be done.

Delete those and rename oo-autoidler => oo-auto-idler

There are some other things but they can wait.

Thanks!

Comment 10 brice 2013-12-20 01:08:54 UTC

Ok. Created another bug with that info. I assigned myself and put you in as a CC recipient.

And thanks for all that, putting this bug onto QA.