using-cpu-entitlement-plugin.html.md.erb

---
title: Using the CPU entitlement plug-in in Cloud Foundry
owner: CLI
---

<%# Reset page title based on platform type %>
<% if vars.platform_code != 'CF' %>

<% set_title(" Using the CPU entitlement plug-in in", vars.app_runtime_abbr) %>

<% end %>

You can use the CPU entitlement plug-in to help manage your CPU resources in <%= vars.app_runtime_abbr %>.


## <a id='cpu-entitlement'></a> CPU entitlement
<%= partial "overview" %>

You can change the exact mapping of memory to CPU when you configure the `experimental_cpu_entitlement_per_share_in_percent`Garden BOSH release property. This property changes the CPU percentage that is entitled to a container per CPU share. For example, a value of `0.3` means that each app has access to 0.3% of the total CPU per share.

By default, the total shares available on a host is equal to the amount of memory on the host. The optimal value for the `experimental_cpu_entitlement_per_share_in_percent` property is 100% divided by the amount of total memory on the host. For example, a host with 1024&nbsp;MB of memory can have an optimal value of `100 / 1024`, which is 0.0977% per share. An 256&nbsp;MB app has access to 76.8% of the total CPU. In this case, if there is only a single core machine, you have over committed the amount of CPU available.

The way you configure the `experimental_cpu_entitlement_per_share_in_percent` property can create three possible states for the apps in your <%= vars.app_runtime_abbr %> deployment:

* Undercommitted - The apps' CPU entitlements are guaranteed minimums, but some CPU host might not be used.

* Optimal - The apps' CPU entitlements are guaranteed minimums.

* Overcommitted - The apps are not guaranteed to have access to their entitlement.

The following table contains examples of optimal values for machines with different total memory and number of CPU cores:

|         | 256M  | 1024M | 8192M |
| ------- |:-----:|:-----:|:-----:|
| 1 core  | 0.39  | 0.098 | 0.012 |
| 4 cores | 1.563 | 0.39  | 0.049 |
| 8 cores | 3.125 | 0.781 | 0.098 |


## <a id='cpu-entitlement-plugin'></a> CPU entitlement plug-in
<%= partial "plugin" %>

## <a id='cpu-throttling'></a> Spare CPU resources and throttling
<%= partial "spare-cpu-and-throttling" %>

Spare resources are distributed on the Diego Cell when the `experimental_cpu_throttling` property is set to `false`. If an app consumes less than the entitlement, and needs CPU resources over its entitlement, it receives the maximum amount of CPU resources from the spare CPU. Without CPU entitlement it depends on the other apps that run on the same Diego Cell. If the other apps constantly use high CPU, they restrict other apps from using more CPU when needed even though the other apps on the same Diego Cell use much more than their CPU entitlements. When an app that usually consumes less than its CPU entitlement needs extra CPU, the spare capacity is distributed evenly between the app that consumes less and all the other apps. When this occurs, the app can never spike over a certain amount of CPU. To provide bandwidth, you might over provision resources for Diego Cells.

When the `experimental_cpu_throttling` property is set to `false`, apps are allowed to temporarily exceed their entitlement, but apps that have been using less than their entitlement over a longer period of time are prioritized. Apps are never forced to use less than their entitlement.

Good and bad apps always get their entitlement. If you use the CPU Entitlement plug-in, the difference is in how the spare CPU gets distributed between the apps. All spare CPU is given to the good app that needs it, and then the bad apps are throttled to only have the amount of CPU to which they are entitled.

If the CPU spike of a good app happens for a long period of time, it eventually becomes a bad app, and is throttled to 100% if a different good app needs the CPU. Resources are then distributed more fairly between the apps.