<commit_before>= Setting Quotas
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview

// tag::admin_quota_overview[]
A resource quota, defined by a `*ResourceQuota*` object, provides constraints
that limit aggregate resource consumption per project. It can limit the quantity
of objects that can be created in a project by type, as well as the total amount
of compute resources that may be consumed by resources in that project.
// end::admin_quota_overview[]

ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
[NOTE]
====
See the link:../dev_guide/compute_resources.html[Developer Guide] for more on
compute resources.
====
endif::[]

[[managed-by-quota]]
== Resources Managed by Quota

// tag::admin_quota_resources_managed[]
The following describes the set of compute resources and object types that may be
managed by a quota.

.Compute Resources Managed by Quota
[cols="3a,8a",options="header"]
|===

|Resource Name |Description

|`*cpu*`
|Across all pods in a non-terminal state, the sum of CPU requests cannot exceed
this value.

|`*memory*`
|Across all pods in a non-terminal state, the sum of memory requests cannot
exceed this value.

|`*requests.cpu*`
|Across all pods in a non-terminal state, the sum of CPU requests cannot exceed
this value.

|`*requests.memory*`
|Across all pods in a non-terminal state, the sum of memory requests cannot
exceed this value.

|`*limits.cpu*`
|Across all pods in a non-terminal state, the sum of CPU limits cannot exceed
this value.

|`*limits.memory*`
|Across all pods in a non-terminal state, the sum of memory limits cannot exceed
this value.
|===

.Object Counts Managed by Quota
[cols="3a,8a",options="header"]
|===

|Resource Name |Description

|`*pods*`
|The total number of pods in a non-terminal state that can exist in the project.
A pod is in a terminal state if `status.phase in (Failed, Succeeded)` is true.

|`*replicationcontrollers*`
|The total number of replication controllers that can exist in the project.

|`*resourcequotas*`
|The total number of resource quotas that can exist in the project.

|`*services*`
|The total number of services that can exist in the project.

|`*secrets*`
|The total number of secrets that can exist in the project.

|`*configmaps*`
|The total number of `*ConfigMap*` objects that can exist in the project.

|`*persistentvolumeclaims*`
|The total number of persistent volume claims that can exist in the project.
|===
// end::admin_quota_resources_managed[]

[[quota-scopes]]
== Quota Scopes

// tag::admin_quota_scopes[]
Each quota can have an associated set of _scopes_. A quota will only
measure usage for a resource if it matches the intersection of enumerated
scopes.

When a scope is added to a quota, it limits the number of resources it supports
to those that pertain to the scope. Resources specified on the quota outside of
the allowed set results in a validation error.

[cols="3a,8a",options="header"]
|===

|Scope |Description

|*Terminating*
|Match pods where `spec.activeDeadlineSeconds >= 0`

|*NotTerminating*
|Match pods where `spec.activeDeadlineSeconds is nil`

|*BestEffort*
|Match pods that have best effort quality of service for either `*cpu*` or
`*memory*`.

|*NotBestEffort*
|Match pods that do not have best effort quality of service for `*cpu*` and
`*memory*`.
|===

A *BestEffort* scope restricts a quota to limit the following resources:

- `*pods*`

A *Terminating*, *NotTerminating*, and *NotBestEffort* scope restricts a quota
to tracking the following resources:

- `*pods*`
- `*memory*`
- `*requests.memory*`
- `*limits.memory*`
- `*cpu*`
- `*requests.cpu*`
- `*limits.cpu*`
// end::admin_quota_scopes[]

[[quota-enforcement]]
== Quota Enforcement

// tag::admin_quota_enforcement[]
After a resource quota for a project is first created, the project restricts the
ability to create any new resources that may violate a quota constraint until it
has calculated updated usage statistics.

After a quota is created and usage statistics are updated, the project accepts
the creation of new content. When you create or modify resources, your quota
usage is incremented immediately upon the request to create or modify the
resource.

When you delete a resource, your quota use is decremented during the next full
recalculation of quota statistics for the project.
// end::admin_quota_enforcement[]
A link:#configuring-quota-sync-period[configurable amount of time] determines
how long it takes to reduce quota usage statistics to their current observed
system value.

If project modifications exceed a quota usage limit, the server denies the
action, and an appropriate error message is returned to the user explaining the
quota constraint violated, and what their currently observed usage stats are in
the system.

[[requests-vs-limits]]
== Requests vs Limits

// tag::admin_quota_requests_vs_limits[]
When allocating
link:../dev_guide/compute_resources.html#dev-compute-resources[compute
resources], each container may specify a request and a limit value for either
CPU or memory. The quota can be configured to quota either value.

If the quota has a value specified for `*requests.cpu*` or `*requests.memory*`,
then it requires that every incoming container makes an explicit request for
those resources. If the quota has a value specified for `*limits.cpu*` or
`*limits.memory*`, then it requires that every incoming container specifies an
explicit limit for those resources.
// end::admin_quota_requests_vs_limits[]

== Sample Resource Quota Definitions

// tag::admin_quota_sample_definitions[]
.*_object-counts.yaml_*
====
----
apiVersion: v1
kind: ResourceQuota
metadata:
  name: object-counts
spec:
  hard:
    configmaps: "10" <1>
    persistentvolumeclaims: "4" <2>
    replicationcontrollers: "20" <3>
    secrets: "10" <4>
    services: "10" <5>
----
<1> The total number of `*ConfigMap*` objects that can exist in the project.
<2> The total number of persistent volume claims (PVCs) that can exist in the
project.
<3> The total number of replication controllers that can exist in the project.
<4> The total number of secrets that can exist in the project.
<5> The total number of services that can exist in the project.
====

.*_compute-resources.yaml_*
====
----
apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-resources
spec:
  hard:
    pods: "4" <1>
    requests.cpu: "1" <2>
    requests.memory: 1Gi <3>
    limits.cpu: "2" <4>
    limits.memory: 2Gi <5>
----
<1> The total number of pods in a non-terminal state that can exist in the
project.
<2> Across all pods in a non-terminal state, the sum of CPU requests cannot
exceed 1 core.
<3> Across all pods in a non-terminal state, the sum of memory requests cannot
exceed 1Gi.
<4> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed
2 cores.
<5> Across all pods in a non-terminal state, the sum of memory limits cannot
exceed 2Gi.
====

.*_besteffort.yaml_*
====
----
apiVersion: v1
kind: ResourceQuota
metadata:
  name: besteffort
spec:
  hard:
    pods: "1" <1>
  scopes:
  - BestEffort <2>
----
<1> The total number of pods in a non-terminal state with *BestEffort* quality
of service that can exist in the project.
<2> Restricts the quota to only matching pods that have *BestEffort* quality of
service for either memory or CPU.
====
// end::admin_quota_sample_definitions[]

[[create-a-quota]]
== Creating a Quota

To create a quota, first define the quota to your specifications in a file, for
example as seen in
link:../admin_guide/quota.html#sample-resource-quota-definitions[Sample Resource
Quota Definitions]. Then, create using that file to apply it to a project:

----
$ oc create -f <resource_quota_definition> [-n <project_name>]
----

For example:

----
$ oc create -f resource-quota.json -n demoproject
----

[[viewing-a-quota]]
== Viewing a Quota

// tag::admin_quota_viewing[]
You can view usage statistics related to any hard limits defined in a project's
quota by navigating in the web console to the project's *Settings* tab.

You can also use the CLI to view quota details:

. First, get the list of quotas defined in the project. For example, for a project
called *demoproject*:
+
====
----
$ oc get quota -n demoproject
NAME                AGE
besteffort          11m
compute-resources   2m
object-counts       29m
----
====

. Then, describe the quota you are interested in, for example the *object-counts*
quota:
+
====
----
$ oc describe quota object-counts -n demoproject
Name:			object-counts
Namespace:		demoproject
Resource		Used	Hard
--------		----	----
configmaps		3	10
persistentvolumeclaims	0	4
replicationcontrollers	3	20
secrets			9	10
services		2	10
----
====
// end::admin_quota_viewing[]

[[configuring-quota-sync-period]]
== Configuring Quota Synchronization Period

When a set of resources are deleted, the synchronization time frame of resources
is determined by the `*resource-quota-sync-period*` setting in the
*_/etc/origin/master/master-config.yaml_* file.

Before quota usage is restored, a user may encounter problems when attempting to
reuse the resources. You can change the `*resource-quota-sync-period*` setting
to have the set of resources regenerate at the desired amount of time (in
seconds) and for the resources to be available again:

====
----
kubernetesMasterConfig:
  apiLevels:
  - v1beta3
  - v1
  apiServerArguments: null
  controllerArguments:
    resource-quota-sync-period:
      - "10s"
----
====

After making any changes, restart the master service to apply them.

Adjusting the regeneration time can be helpful for creating resources and
determining resource usage when automation is used.

[NOTE]
====
The `*resource-quota-sync-period*` setting is designed to balance system
performance. Reducing the sync period can result in a heavy load on the master.
====

ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
[[accounting-quota-dc]]
== Accounting for Quota in Deployment Configurations

If a quota has been defined for your project, see
link:../dev_guide/deployments.html#deployment-resources[Deployment Resources]
for considerations on any deployment configurations.
endif::[]
<commit_msg>Document quota support for requests.storage<commit_after>= Setting Quotas
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview

// tag::admin_quota_overview[]
A resource quota, defined by a `*ResourceQuota*` object, provides constraints
that limit aggregate resource consumption per project. It can limit the quantity
of objects that can be created in a project by type, as well as the total amount
of compute resources that may be consumed by resources in that project.
// end::admin_quota_overview[]

ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
[NOTE]
====
See the link:../dev_guide/compute_resources.html[Developer Guide] for more on
compute resources.
====
endif::[]

[[managed-by-quota]]
== Resources Managed by Quota

// tag::admin_quota_resources_managed[]
The following describes the set of compute resources and object types that may be
managed by a quota.

.Compute Resources Managed by Quota
[cols="3a,8a",options="header"]
|===

|Resource Name |Description

|`*cpu*`
|Across all pods in a non-terminal state, the sum of CPU requests cannot exceed
this value.

|`*memory*`
|Across all pods in a non-terminal state, the sum of memory requests cannot
exceed this value.

|`*requests.cpu*`
|Across all pods in a non-terminal state, the sum of CPU requests cannot exceed
this value.

|`*requests.memory*`
|Across all pods in a non-terminal state, the sum of memory requests cannot
exceed this value.

|`*limits.cpu*`
|Across all pods in a non-terminal state, the sum of CPU limits cannot exceed
this value.

|`*limits.memory*`
|Across all pods in a non-terminal state, the sum of memory limits cannot exceed
this value.

|`*requests.storage*`
|Across all persistent volume claims, the sum of storage requests cannot
exceed this value.
|===

.Object Counts Managed by Quota
[cols="3a,8a",options="header"]
|===

|Resource Name |Description

|`*pods*`
|The total number of pods in a non-terminal state that can exist in the project.
A pod is in a terminal state if `status.phase in (Failed, Succeeded)` is true.

|`*replicationcontrollers*`
|The total number of replication controllers that can exist in the project.

|`*resourcequotas*`
|The total number of resource quotas that can exist in the project.

|`*services*`
|The total number of services that can exist in the project.

|`*secrets*`
|The total number of secrets that can exist in the project.

|`*configmaps*`
|The total number of `*ConfigMap*` objects that can exist in the project.

|`*persistentvolumeclaims*`
|The total number of persistent volume claims that can exist in the project.
|===
// end::admin_quota_resources_managed[]

[[quota-scopes]]
== Quota Scopes

// tag::admin_quota_scopes[]
Each quota can have an associated set of _scopes_. A quota will only
measure usage for a resource if it matches the intersection of enumerated
scopes.

When a scope is added to a quota, it limits the number of resources it supports
to those that pertain to the scope. Resources specified on the quota outside of
the allowed set results in a validation error.

[cols="3a,8a",options="header"]
|===

|Scope |Description

|*Terminating*
|Match pods where `spec.activeDeadlineSeconds >= 0`

|*NotTerminating*
|Match pods where `spec.activeDeadlineSeconds is nil`

|*BestEffort*
|Match pods that have best effort quality of service for either `*cpu*` or
`*memory*`.

|*NotBestEffort*
|Match pods that do not have best effort quality of service for `*cpu*` and
`*memory*`.
|===

A *BestEffort* scope restricts a quota to limit the following resources:

- `*pods*`

A *Terminating*, *NotTerminating*, and *NotBestEffort* scope restricts a quota
to tracking the following resources:

- `*pods*`
- `*memory*`
- `*requests.memory*`
- `*limits.memory*`
- `*cpu*`
- `*requests.cpu*`
- `*limits.cpu*`
// end::admin_quota_scopes[]

[[quota-enforcement]]
== Quota Enforcement

// tag::admin_quota_enforcement[]
After a resource quota for a project is first created, the project restricts the
ability to create any new resources that may violate a quota constraint until it
has calculated updated usage statistics.

After a quota is created and usage statistics are updated, the project accepts
the creation of new content. When you create or modify resources, your quota
usage is incremented immediately upon the request to create or modify the
resource.

When you delete a resource, your quota use is decremented during the next full
recalculation of quota statistics for the project.
// end::admin_quota_enforcement[]
A link:#configuring-quota-sync-period[configurable amount of time] determines
how long it takes to reduce quota usage statistics to their current observed
system value.

If project modifications exceed a quota usage limit, the server denies the
action, and an appropriate error message is returned to the user explaining the
quota constraint violated, and what their currently observed usage stats are in
the system.

[[requests-vs-limits]]
== Requests vs Limits

// tag::admin_quota_requests_vs_limits[]
When allocating
link:../dev_guide/compute_resources.html#dev-compute-resources[compute
resources], each container may specify a request and a limit value for either
CPU or memory. The quota can be configured to quota either value.

If the quota has a value specified for `*requests.cpu*` or `*requests.memory*`,
then it requires that every incoming container makes an explicit request for
those resources. If the quota has a value specified for `*limits.cpu*` or
`*limits.memory*`, then it requires that every incoming container specifies an
explicit limit for those resources.
// end::admin_quota_requests_vs_limits[]

== Sample Resource Quota Definitions

// tag::admin_quota_sample_definitions[]
.*_object-counts.yaml_*
====
----
apiVersion: v1
kind: ResourceQuota
metadata:
  name: object-counts
spec:
  hard:
    configmaps: "10" <1>
    persistentvolumeclaims: "4" <2>
    replicationcontrollers: "20" <3>
    secrets: "10" <4>
    services: "10" <5>
----
<1> The total number of `*ConfigMap*` objects that can exist in the project.
<2> The total number of persistent volume claims (PVCs) that can exist in the
project.
<3> The total number of replication controllers that can exist in the project.
<4> The total number of secrets that can exist in the project.
<5> The total number of services that can exist in the project.
====

.*_compute-resources.yaml_*
====
----
apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-resources
spec:
  hard:
    pods: "4" <1>
    requests.cpu: "1" <2>
    requests.memory: 1Gi <3>
    limits.cpu: "2" <4>
    limits.memory: 2Gi <5>
----
<1> The total number of pods in a non-terminal state that can exist in the
project.
<2> Across all pods in a non-terminal state, the sum of CPU requests cannot
exceed 1 core.
<3> Across all pods in a non-terminal state, the sum of memory requests cannot
exceed 1Gi.
<4> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed
2 cores.
<5> Across all pods in a non-terminal state, the sum of memory limits cannot
exceed 2Gi.
====

.*_besteffort.yaml_*
====
----
apiVersion: v1
kind: ResourceQuota
metadata:
  name: besteffort
spec:
  hard:
    pods: "1" <1>
  scopes:
  - BestEffort <2>
----
<1> The total number of pods in a non-terminal state with *BestEffort* quality
of service that can exist in the project.
<2> Restricts the quota to only matching pods that have *BestEffort* quality of
service for either memory or CPU.
====
// end::admin_quota_sample_definitions[]

[[create-a-quota]]
== Creating a Quota

To create a quota, first define the quota to your specifications in a file, for
example as seen in
link:../admin_guide/quota.html#sample-resource-quota-definitions[Sample Resource
Quota Definitions]. Then, create using that file to apply it to a project:

----
$ oc create -f <resource_quota_definition> [-n <project_name>]
----

For example:

----
$ oc create -f resource-quota.json -n demoproject
----

[[viewing-a-quota]]
== Viewing a Quota

// tag::admin_quota_viewing[]
You can view usage statistics related to any hard limits defined in a project's
quota by navigating in the web console to the project's *Settings* tab.

You can also use the CLI to view quota details:

. First, get the list of quotas defined in the project. For example, for a project
called *demoproject*:
+
====
----
$ oc get quota -n demoproject
NAME                AGE
besteffort          11m
compute-resources   2m
object-counts       29m
----
====

. Then, describe the quota you are interested in, for example the *object-counts*
quota:
+
====
----
$ oc describe quota object-counts -n demoproject
Name:			object-counts
Namespace:		demoproject
Resource		Used	Hard
--------		----	----
configmaps		3	10
persistentvolumeclaims	0	4
replicationcontrollers	3	20
secrets			9	10
services		2	10
----
====
// end::admin_quota_viewing[]

[[configuring-quota-sync-period]]
== Configuring Quota Synchronization Period

When a set of resources are deleted, the synchronization time frame of resources
is determined by the `*resource-quota-sync-period*` setting in the
*_/etc/origin/master/master-config.yaml_* file.

Before quota usage is restored, a user may encounter problems when attempting to
reuse the resources. You can change the `*resource-quota-sync-period*` setting
to have the set of resources regenerate at the desired amount of time (in
seconds) and for the resources to be available again:

====
----
kubernetesMasterConfig:
  apiLevels:
  - v1beta3
  - v1
  apiServerArguments: null
  controllerArguments:
    resource-quota-sync-period:
      - "10s"
----
====

After making any changes, restart the master service to apply them.

Adjusting the regeneration time can be helpful for creating resources and
determining resource usage when automation is used.

[NOTE]
====
The `*resource-quota-sync-period*` setting is designed to balance system
performance. Reducing the sync period can result in a heavy load on the master.
====

ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
[[accounting-quota-dc]]
== Accounting for Quota in Deployment Configurations

If a quota has been defined for your project, see
link:../dev_guide/deployments.html#deployment-resources[Deployment Resources]
for considerations on any deployment configurations.
endif::[]

{'fraction_non_alphanumeric': 0.09723100880821452, 'fraction_numerical': 0.00749428196019271, 'mean_word_length': 4.407894736842105, 'pattern_counts': {'":': 0, '<': 55, '<?xml version=': 0, '>': 57, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2720780', 'n_tokens_mistral': 6323, 'n_tokens_neox': 6005, 'n_words': 2654}