Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 1512781 - [DOCS] Narrative and math in out of resource documentation is incorrect
Summary: [DOCS] Narrative and math in out of resource documentation is incorrect
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation
Version: 3.6.0
Hardware: Unspecified
OS: Unspecified
medium
medium
Target Milestone: ---
: ---
Assignee: Ashley Hardin
QA Contact: DeShuai Ma
Vikram Goyal
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-11-14 05:31 UTC by mmariyan
Modified: 2018-05-09 00:32 UTC (History)
4 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2018-02-19 21:58:00 UTC
Target Upstream Version:


Attachments (Terms of Use)

Description mmariyan 2017-11-14 05:31:35 UTC
Document URL:  https://docs.openshift.com/container-platform/3.6/admin_guide/out_of_resource_handling.html#out-of-resource-schedulable-resources-and-eviction-policies


Section Number and Name: 
1.Example scenario


Describe the issue: 

On page located at https://docs.openshift.com/container-platform/3.5/admin_guide/out_of_resource_handling.html#out-of-resource-schedulable-resources-and-eviction-policies the example given is below.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
capacity = 10 Gi
system-reserved = 10 Gi * .01 = 1 Gi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This should read:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
capacity = 10 Gi
system-reserved = 10 Gi * .1 = 1 Gi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A little further down appears the below text:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to turn on eviction so that eviction is triggered when the node observes that available memory falls below 10% of capacity for 30 seconds, or immediately when it falls below 5% of capacity, you need the scheduler to see allocatable as 8Gi. Therefore, ensure your system reservation covers the greater of your eviction thresholds.

capacity = 10 Gi
eviction-threshold = 10 Gi * .05 = .5 Gi
system-reserved = (10Gi * .01) + eviction-threshold = 1.5 Gi
allocatable = capacity - system-reserved = 8.5 Gi

Enter the following in the node-config.yaml:

kubeletArguments:
  system-reserved:
  - "8.5Gi"
  eviction-hard:
  - memory.available<.5Gi
  eviction-soft:
  - memory.available<1Gi
  eviction-soft-grace-period:
  - memory.available=30s
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are a couple things wrong or unclear about this section.

1) The eviction threshold should say "eviction-threshold = 10 Gi * .1 = 1 Gi" to match the narrative regarding the greater of the eviction thresholds which is 10% not 5%.
2) The math is wrong for system-reserved. It should read "system-reserved = (10Gi * .1) + eviction-threshold = 2 Gi".
3) The allocatable line should read "allocatable = capacity - system-reserved = 8 Gi" to then match the narrative and previous math changes.
4) In the kublet argument section the system-reserved section should be set to 2Gi from the calculations above.
5) Looking at the example scenario from the Kubernetes documentation located at https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/#example-scenario, the math there contradicts the math and narrative in the OpenShift documentation. Can we get clarification on whether the system-reserved parameter should be set to what we want to reserve for the system or if system reserve should equal what we want to reserve for the system plus the greater of our eviction thresholds?.
6) The narrative could be more clear about its statements on when available memory falls below a certain percentage of capacity. Does capacity mean total capacity on the node or total capacity on the node minus what we are reserving for the system. If our eviction numbers should be based off of total capacity minus what we want to reserve for the system then this changes a lot of the math for the example.

Assuming the narrative and behavior described in the OpenShift documentation is correct, the end result should read:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to turn on eviction so that eviction is triggered when the node observes that available memory falls below 10% of capacity for 30 seconds, or immediately when it falls below 5% of capacity, you need the scheduler to see allocatable as 8Gi. Therefore, ensure your system reservation covers the greater of your eviction thresholds.

capacity = 10 Gi
eviction-threshold = 10 Gi * .1 = 1 Gi
system-reserved = (10Gi * .1) + eviction-threshold = 2 Gi
allocatable = capacity - system-reserved = 8 Gi

Enter the following in the node-config.yaml:

kubeletArguments:
  system-reserved:
  - "2Gi"
  eviction-hard:
  - memory.available<.5Gi
  eviction-soft:
  - memory.available<1Gi
  eviction-soft-grace-period:
  - memory.available=30s
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Comment 3 openshift-github-bot 2018-02-09 18:08:09 UTC
Commits pushed to master at https://github.com/openshift/openshift-docs

https://github.com/openshift/openshift-docs/commit/328e544badbb8821b78592bf984557a405f0ad35
Bug 1512781, updated the Scenario math

https://github.com/openshift/openshift-docs/commit/0b172df08a9b25298032a5b28df89d744f71b294
Merge pull request #7375 from ahardin-rh/update-scenario

Bug 1512781, updated the Scenario math


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