1
0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00

OSDOCS-6582: CLIOT-28 CPU Usage guidance

This commit is contained in:
GroceryBoyJr
2024-09-19 14:46:25 -04:00
committed by openshift-cherrypick-robot
parent d5cd636e89
commit 7adcd676e8
7 changed files with 1115 additions and 1 deletions

View File

@@ -3200,6 +3200,8 @@ Topics:
- Name: Planning your environment according to object maximums
File: planning-your-environment-according-to-object-maximums
Distros: openshift-origin,openshift-enterprise
- Name: Compute Resource Quotas
File: compute-resource-quotas
- Name: Recommended host practices for IBM Z & IBM LinuxONE environments
File: ibm-z-recommended-host-practices
Distros: openshift-enterprise

View File

@@ -0,0 +1,75 @@
// Module included in the following assemblies:
//
// ../scalability_and_performance/compute-resource-quotas.adoc
:_mod-docs-content-type: PROCEDURE
[id="admin-limit-operations_{context}"]
= Limit range operations
== Creating a limit range
Shown here is an example procedure to follow for creating a limit range.
.Procedure
. Create the object:
+
[source,terminal]
----
$ oc create -f <limit_range_file> -n <project>
----
== View the limit
You can view any limit ranges that are defined in a project by navigating in the web console to the `Quota` page for the project. You can also use the CLI to view limit range details by performing the following steps:
.Procedure
. Get the list of limit range objects that are defined in the project. For example, a project called `demoproject`:
+
[source,terminal]
----
$ oc get limits -n demoproject
----
+
.Example Output
+
[source,terminal]
----
NAME AGE
resource-limits 6d
----
. Describe the limit range. For example, for a limit range called `resource-limits`:
+
[source,terminal]
----
$ oc describe limits resource-limits -n demoproject
----
+
.Example Output
+
[source,terminal]
----
Name: resource-limits
Namespace: demoproject
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
---- -------- --- --- --------------- ------------- -----------------------
Pod cpu 200m 2 - - -
Pod memory 6Mi 1Gi - - -
Container cpu 100m 2 200m 300m 10
Container memory 4Mi 1Gi 100Mi 200Mi -
openshift.io/Image storage - 1Gi - - -
openshift.io/ImageStream openshift.io/image - 12 - - -
openshift.io/ImageStream openshift.io/image-tags - 10 - - -
----
== Deleting a limit range
To remove a limit range, run the following command:
+
[source,terminal]
----
$ oc delete limits <limit_name>
----
S

View File

@@ -0,0 +1,295 @@
// Module included in the following assemblies:
//
// ../scalability_and_performance/compute-resource-quotas.adoc
:_mod-docs-content-type: CONCEPT
[id="admin-quota-limits_{context}"]
= Setting limit ranges
A limit range, defined by a `LimitRange` object, defines compute resource constraints at the pod, container, image, image stream, and persistent volume claim level. The limit range specifies the amount of resources that a pod, container, image, image stream, or persistent volume claim can consume.
All requests to create and modify resources are evaluated against each `LimitRange` object in the project. If the resource violates any of the enumerated constraints, the resource is rejected. If the resource does not set an explicit value, and if the constraint supports a default value, the default value is applied to the resource.
For CPU and memory limits, if you specify a maximum value but do not specify a minimum limit, the resource can consume more CPU and memory resources than the maximum value.
ifdef::openshift-online[]
[IMPORTANT]
====
For {product-title} Pro, the maximum pod memory is 3Gi. The minimum pod or container memory that you can specify is 100Mi.
For {product-title} Starter, the maximum pod memory is 1Gi. The minimum pod or container memory that you can specify is 200Mi.
====
endif::[]
.Core limit range object definition
[source,yaml]
----
apiVersion: "v1"
kind: "LimitRange"
metadata:
name: "core-resource-limits" <1>
spec:
limits:
- type: "Pod"
max:
cpu: "2" <2>
memory: "1Gi" <3>
min:
cpu: "200m" <4>
memory: "6Mi" <5>
- type: "Container"
max:
cpu: "2" <6>
memory: "1Gi" <7>
min:
cpu: "100m" <8>
memory: "4Mi" <9>
default:
cpu: "300m" <10>
memory: "200Mi" <11>
defaultRequest:
cpu: "200m" <12>
memory: "100Mi" <13>
maxLimitRequestRatio:
cpu: "10" <14>
----
<1> The name of the limit range object.
<2> The maximum amount of CPU that a pod can request on a node across all containers.
<3> The maximum amount of memory that a pod can request on a node across all containers.
<4> The minimum amount of CPU that a pod can request on a node across all containers. If you do not set a `min` value or you set `min` to `0`, the result is no limit and the pod can consume more than the `max` CPU value.
<5> The minimum amount of memory that a pod can request on a node across all containers. If you do not set a `min` value or you set `min` to `0`, the result is no limit and the pod can consume more than the `max` memory value.
<6> The maximum amount of CPU that a single container in a pod can request.
<7> The maximum amount of memory that a single container in a pod can request.
<8> The minimum amount of CPU that a single container in a pod can request. If you do not set a `min` value or you set `min` to `0`, the result is no limit and the pod can consume more than the `max` CPU value.
<9> The minimum amount of memory that a single container in a pod can request. If you do not set a `min` value or you set `min` to `0`, the result is no limit and the pod can consume more than the `max` memory value.
<10> The default CPU limit for a container if you do not specify a limit in the pod specification.
<11> The default memory limit for a container if you do not specify a limit in the pod specification.
<12> The default CPU request for a container if you do not specify a request in the pod specification.
<13> The default memory request for a container if you do not specify a request in the pod specification.
<14> The maximum limit-to-request ratio for a container.
.{product-title} Limit range object definition
[source,yaml]
----
apiVersion: "v1"
kind: "LimitRange"
metadata:
name: "openshift-resource-limits"
spec:
limits:
- type: openshift.io/Image
max:
storage: 1Gi <1>
- type: openshift.io/ImageStream
max:
openshift.io/image-tags: 20 <2>
openshift.io/images: 30 <3>
- type: "Pod"
max:
cpu: "2" <4>
memory: "1Gi" <5>
ephemeral-storage: "1Gi" <6>
min:
cpu: "1" <7>
memory: "1Gi" <8>
----
<1> The maximum size of an image that can be pushed to an internal registry.
<2> The maximum number of unique image tags as defined in the specification for the image stream.
<3> The maximum number of unique image references as defined in the specification for the image stream status.
<4> The maximum amount of CPU that a pod can request on a node across all containers.
<5> The maximum amount of memory that a pod can request on a node across all containers.
<6> The maximum amount of ephemeral storage that a pod can request on a node across all containers.
<7> The minimum amount of CPU that a pod can request on a node across all containers. See the Supported Constraints table for important information.
<8> The minimum amount of memory that a pod can request on a node across all containers. If you do not set a `min` value or you set `min` to `0`, the result` is no limit and the pod can consume more than the `max` memory value.
You can specify both core and {product-title} resources in one limit range object.
== Container limits
*Supported Resources:*
* CPU
* Memory
.Supported Constraints
Per container, the following must hold true if specified:
*Container*
[cols="3a,8a",options="header"]
|===
|Constraint |Behavior
|`Min`
|`Min[<resource>]` less than or equal to `container.resources.requests[<resource>]` (required) less than or equal to `container/resources.limits[<resource>]` (optional)
If the configuration defines a `min` CPU, the request value must be greater than the CPU value. If you do not set a `min` value or you set `min` to `0`, the result is no limit and the pod can consume more of the resource than the `max` value.
|`Max`
|`container.resources.limits[<resource>]` (required) less than or equal to `Max[<resource>]`
If the configuration defines a `max` CPU, you do not need to define a CPU request value. However, you must set a limit that satisfies the maximum CPU constraint that is specified in the limit range.
|`MaxLimitRequestRatio`
|`MaxLimitRequestRatio[<resource>]` less than or equal to (`container.resources.limits[<resource>]` / `container.resources.requests[<resource>]`)
If the limit range defines a `maxLimitRequestRatio` constraint, any new containers must have both a `request` and a `limit` value. Additionally, {product-title} calculates a limit-to-request ratio by dividing the `limit` by the `request`. The result should be an integer greater than 1.
For example, if a container has `cpu: 500` in the `limit` value, and `cpu: 100` in the `request` value, the limit-to-request ratio for `cpu` is `5`. This ratio must be less than or equal to the `maxLimitRequestRatio`.
|===
*Supported Defaults:*
`Default[<resource>]`:: Defaults `container.resources.limit[<resource>]` to specified value if none.
`Default Requests[<resource>]`:: Defaults `container.resources.requests[<resource>]` to specified value if none.
== Pod limits
*Supported Resources:*
* CPU
* Memory
*Supported Constraints:*
Across all containers in a pod, the following must hold true:
.Pod
[cols="3a,8a",options="header"]
|===
|Constraint |Enforced Behavior
|`Min`
|`Min[<resource>]` less than or equal to `container.resources.requests[<resource>]` (required) less than or equal to `container.resources.limits[<resource>]`. If you do not set a `min` value or you set `min` to `0`, the result is no limit and the pod can consume more of the resource than the `max` value.
|`Max`
|`container.resources.limits[<resource>]` (required) less than or equal to `Max[<resource>]`.
|`MaxLimitRequestRatio`
|`MaxLimitRequestRatio[<resource>]` less than or equal to (`container.resources.limits[<resource>]` / `container.resources.requests[<resource>]`).
|===
== Image limits
Supported Resources:
* Storage
Resource type name:
- `openshift.io/Image`
Per image, the following must hold true if specified:
.Image
[cols="3a,8a",options="header"]
|===
|Constraint |Behavior
|`Max`
|`image.dockerimagemetadata.size` less than or equal to `Max[<resource>]`
|===
[NOTE]
====
To prevent blobs that exceed the limit from being uploaded to the registry, the registry must be configured to enforce quota. The `REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_ENFORCEQUOTA` environment variable must be set to `true`. By default, the environment variable is set to `true` for new deployments.
====
== Image stream limits
*Supported Resources:*
* `openshift.io/image-tags`
* `openshift.io/images`
*Resource type name:*
- `openshift.io/ImageStream`
Per image stream, the following must hold true if specified:
.ImageStream
[cols="3a,8a",options="header"]
|===
|Constraint |Behavior
|`Max[openshift.io/image-tags]`
|`length( uniqueimagetags( imagestream.spec.tags ) )` less than or equal to `Max[openshift.io/image-tags]`
`uniqueimagetags` returns unique references to images of given spec tags.
|`Max[openshift.io/images]`
|`length( uniqueimages( imagestream.status.tags ) )` less than or equal to `Max[openshift.io/images]`
`uniqueimages` returns unique image names found in status tags. The name is equal to the digest for the image.
|===
== Counting of image references
The `openshift.io/image-tags` resource represents unique stream limits. Possible references are an `ImageStreamTag`, an `ImageStreamImage`, or a `DockerImage`. Tags can be created by using the `oc tag` and `oc import-image` commands or by using image streams. No distinction is made between internal and external references. However, each unique reference that is tagged in an image stream specification is counted just once. It does not restrict pushes to an internal container image registry in any way, but is useful for tag restriction.
The `openshift.io/images` resource represents unique image names that are recorded in image stream status. It helps to restrict several images that can be pushed to the internal registry. Internal and external references are not distinguished.
== PersistentVolumeClaim limits
*Supported Resources:*
* Storage
*Supported Constraints:*
Across all persistent volume claims in a project, the following must hold true:
.Pod
[cols="3a,8a",options="header"]
|===
|Constraint |Enforced Behavior
|`Min`
|Min[<resource>] +<=+ claim.spec.resources.requests[<resource>] (required)
|`Max`
|claim.spec.resources.requests[<resource>] (required) +<=+ Max[<resource>]
|===
[[limit-range-obj-def]]
.Limit Range Object Definition
[source,json]
----
{
"apiVersion": "v1",
"kind": "LimitRange",
"metadata": {
"name": "pvcs" <1>
},
"spec": {
"limits": [{
"type": "PersistentVolumeClaim",
"min": {
"storage": "2Gi" <2>
},
"max": {
"storage": "50Gi" <3>
}
}
]
}
}
----
<1> The name of the limit range object.
<2> The minimum amount of storage that can be requested in a persistent volume claim.
<3> The maximum amount of storage that can be requested in a persistent volume claim.

View File

@@ -0,0 +1,334 @@
// Module included in the following assemblies:
//
// ../scalability_and_performance/compute-resource-quotas.adoc
:_mod-docs-content-type: CONCEPT
[id="admin-quota-overview_{context}"]
= Resources managed by quota
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 and storage that may be consumed by resources in that project.
The following describes the set of compute resources and object types that may be managed by a quota.
[NOTE]
====
A pod is in a terminal state if `status.phase` is `Failed` or `Succeeded`.
====
.Compute resources managed by quota
[cols="3a,8a",options="header"]
|===
|Resource Name |Description
|`cpu`
|The sum of CPU requests across all pods in a non-terminal state cannot exceed this value. `cpu` and `requests.cpu` are the same value and can be used
interchangeably.
|`memory`
|The sum of memory requests across all pods in a non-terminal state cannot exceed this value. `memory` and `requests.memory` are the same value and can
be used interchangeably.
|`ephemeral-storage`
|The sum of local ephemeral storage requests across all pods in a non-terminal state cannot exceed this value. `ephemeral-storage` and
`requests.ephemeral-storage` are the same value and can be used interchangeably. This resource is available only if you enabled the ephemeral storage technology preview. This feature is disabled by default.
|`requests.cpu`
|The sum of CPU requests across all pods in a non-terminal state cannot exceed this value. `cpu` and `requests.cpu` are the same value and can be used
interchangeably.
|`requests.memory`
|The sum of memory requests across all pods in a non-terminal state cannot exceed this value. `memory` and `requests.memory` are the same value and can
be used interchangeably.
|`requests.ephemeral-storage`
|The sum of ephemeral storage requests across all pods in a non-terminal state cannot exceed this value. `ephemeral-storage` and
`requests.ephemeral-storage` are the same value and can be used interchangeably. This resource is available only if you enabled the ephemeral
storage technology preview. This feature is disabled by default.
|`limits.cpu`
|The sum of CPU limits across all pods in a non-terminal state cannot exceed this value.
|`limits.memory`
|The sum of memory limits across all pods in a non-terminal state cannot exceed this value.
|`limits.ephemeral-storage`
|The sum of ephemeral storage limits across all pods in a non-terminal state cannot exceed this value. This resource is available only if you enabled the
ephemeral storage technology preview. This feature is disabled by default.
|===
.Storage resources managed by quota
[cols="3a,8a",options="header"]
|===
|Resource Name |Description
|`requests.storage`
|The sum of storage requests across all persistent volume claims in any state cannot exceed this value.
|`persistentvolumeclaims`
|The total number of persistent volume claims that can exist in the project.
|`<storage-class-name>.storageclass.storage.k8s.io/requests.storage`
|The sum of storage requests across all persistent volume claims in any state that have a matching storage class, cannot exceed this value.
|`<storage-class-name>.storageclass.storage.k8s.io/persistentvolumeclaims`
|The total number of persistent volume claims with a matching storage class that can exist in the project.
|===
.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.
|`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.
|`openshift.io/imagestreams`
|The total number of image streams that can exist in the project.
|===
You can configure an object count quota for these standard namespaced resource types using the `count/<resource>.<group>` syntax.
[source,terminal]
----
$ oc create quota <name> --hard=count/<resource>.<group>=<quota> <1>
----
<1> `<resource>` is the name of the resource, and `<group>` is the API group, if applicable.
Use the `kubectl api-resources` command for a list of resources and their associated API groups.
== Setting resource quota for extended resources
Overcommitment of resources is not allowed for extended resources, so you must specify `requests` and `limits` for the same extended resource in a quota. Currently, only quota items with the prefix `requests.` are allowed for extended resources. The following is an example scenario of how to set resource quota for the GPU resource `nvidia.com/gpu`.
.Procedure
. To determine how many GPUs are available on a node in your cluster, use the following command:
+
[source,terminal]
----
$ oc describe node ip-172-31-27-209.us-west-2.compute.internal | egrep 'Capacity|Allocatable|gpu'
----
+
.Example output
[source,terminal]
----
openshift.com/gpu-accelerator=true
Capacity:
nvidia.com/gpu: 2
Allocatable:
nvidia.com/gpu: 2
nvidia.com/gpu: 0 0
----
+
In this example, 2 GPUs are available.
. Use this command to set a quota in the namespace `nvidia`. In this example, the quota is `1`:
+
[source,terminal]
----
$ cat gpu-quota.yaml
----
+
.Example output
[source,terminal]
----
apiVersion: v1
kind: ResourceQuota
metadata:
name: gpu-quota
namespace: nvidia
spec:
hard:
requests.nvidia.com/gpu: 1
----
. Create the quota with the following command:
+
[source,terminal]
----
$ oc create -f gpu-quota.yaml
----
+
.Example output
[source,terminal]
----
resourcequota/gpu-quota created
----
. Verify that the namespace has the correct quota set using the following command:
+
[source,terminal]
----
$ oc describe quota gpu-quota -n nvidia
----
+
.Example output
[source,terminal]
----
Name: gpu-quota
Namespace: nvidia
Resource Used Hard
-------- ---- ----
requests.nvidia.com/gpu 0 1
----
. Run a pod that asks for a single GPU with the following command:
+
[source,terminal]
----
$ oc create pod gpu-pod.yaml
----
+
.Example output
[source, terminal]
----
apiVersion: v1
kind: Pod
metadata:
generateName: gpu-pod-s46h7
namespace: nvidia
spec:
restartPolicy: OnFailure
containers:
- name: rhel7-gpu-pod
image: rhel7
env:
- name: NVIDIA_VISIBLE_DEVICES
value: all
- name: NVIDIA_DRIVER_CAPABILITIES
value: "compute,utility"
- name: NVIDIA_REQUIRE_CUDA
value: "cuda>=5.0"
command: ["sleep"]
args: ["infinity"]
resources:
limits:
nvidia.com/gpu: 1
----
. Verify that the pod is running bwith the following command:
+
[source,terminal]
----
$ oc get pods
----
+
.Example output
[source, terminal]
----
NAME READY STATUS RESTARTS AGE
gpu-pod-s46h7 1/1 Running 0 1m
----
. Verify that the quota `Used` counter is correct by running the following command:
+
[source,terminal]
----
$ oc describe quota gpu-quota -n nvidia
----
+
.Example output
[source, terminal]
----
Name: gpu-quota
Namespace: nvidia
Resource Used Hard
-------- ---- ----
requests.nvidia.com/gpu 1 1
----
. Using the following command, attempt to create a second GPU pod in the `nvidia` namespace. This is technically available on the node because it has 2 GPUs:
+
[source,terminal]
----
$ oc create -f gpu-pod.yaml
----
+
.Example output
[source, terminal]
----
Error from server (Forbidden): error when creating "gpu-pod.yaml": pods "gpu-pod-f7z2w" is forbidden: exceeded quota: gpu-quota, requested: requests.nvidia.com/gpu=1, used: requests.nvidia.com/gpu=1, limited: requests.nvidia.com/gpu=1
----
+
This `Forbidden` error message occurs because you have a quota of 1 GPU and this pod tried to allocate a second GPU, which exceeds its quota.
== Quota scopes
Each quota can have an associated set of _scopes_. A quota only measures usage for a resource if it matches the intersection of enumerated scopes.
Adding a scope to a quota restricts the set of resources to which that quota can apply. Specifying a resource 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`.
|`otBestEffort`
|Match pods that do not have best effort quality of service for `cpu` and `memory`.
|===
A `BestEffort` scope restricts a quota to limiting 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`
* `ephemeral-storage`
* `requests.ephemeral-storage`
* `limits.ephemeral-storage`
[NOTE]
====
Ephemeral storage requests and limits apply only if you enabled the ephemeral storage technology preview. This feature is disabled by default.
====

View File

@@ -0,0 +1,343 @@
// Module included in the following assemblies:
//
// ../scalability_and_performance/compute-resource-quotas.adoc
:_mod-docs-content-type: PROCEDURE
[id="admin-quota-usage_{context}"]
= Admin quota usage
== Quota enforcement
After a resource quota for a project is first created, the project restricts the ability to create any new resources that can 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.
A 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 compared to limits
When allocating compute resources by quota, each container can specify a request and a limit value each for CPU, memory, and ephemeral storage. Quotas can restrict any of these values.
If the quota has a value specified for `requests.cpu` or `requests.memory`, then it requires that every incoming container make 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 specify an explicit limit for those resources.
== Sample resource quota definitions
.Example core-object-counts.yaml
[source,yaml]
----
apiVersion: v1
kind: ResourceQuota
metadata:
name: core-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.
.Example openshift-object-counts.yaml
[source,yaml]
----
apiVersion: v1
kind: ResourceQuota
metadata:
name: openshift-object-counts
spec:
hard:
openshift.io/imagestreams: "10" <1>
----
<1> The total number of image streams that can exist in the project.
.Example compute-resources.yaml
[source,yaml]
----
apiVersion: v1
kind: ResourceQuota
metadata:
name: compute-resources
spec:
hard:
pods: "4" <1>
requests.cpu: "1" <2>
requests.memory: 1Gi <3>
requests.ephemeral-storage: 2Gi <4>
limits.cpu: "2" <5>
limits.memory: 2Gi <6>
limits.ephemeral-storage: 4Gi <7>
----
<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 ephemeral storage requests cannot exceed 2Gi.
<5> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed 2 cores.
<6> Across all pods in a non-terminal state, the sum of memory limits cannot exceed 2Gi.
<7> Across all pods in a non-terminal state, the sum of ephemeral storage limits cannot exceed 4Gi.
.Example besteffort.yaml
[source,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.
.Example compute-resources-long-running.yaml
[source,yaml]
----
apiVersion: v1
kind: ResourceQuota
metadata:
name: compute-resources-long-running
spec:
hard:
pods: "4" <1>
limits.cpu: "4" <2>
limits.memory: "2Gi" <3>
limits.ephemeral-storage: "4Gi" <4>
scopes:
- NotTerminating <5>
----
<1> The total number of pods in a non-terminal state.
<2> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed this value.
<3> Across all pods in a non-terminal state, the sum of memory limits cannot exceed this value.
<4> Across all pods in a non-terminal state, the sum of ephemeral storage limits cannot exceed this value.
<5> Restricts the quota to only matching pods where `spec.activeDeadlineSeconds` is set to `nil`. Build pods will fall under `NotTerminating` unless the `RestartNever` policy is applied.
.Example compute-resources-time-bound.yaml
[source,yaml]
----
apiVersion: v1
kind: ResourceQuota
metadata:
name: compute-resources-time-bound
spec:
hard:
pods: "2" <1>
limits.cpu: "1" <2>
limits.memory: "1Gi" <3>
limits.ephemeral-storage: "1Gi" <4>
scopes:
- Terminating <5>
----
<1> The total number of pods in a non-terminal state.
<2> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed this value.
<3> Across all pods in a non-terminal state, the sum of memory limits cannot exceed this value.
<4> Across all pods in a non-terminal state, the sum of ephemeral storage limits cannot exceed this value.
<5> Restricts the quota to only matching pods where `spec.activeDeadlineSeconds >=0`. For example, this quota would charge for build pods, but not long running pods such as a web server or database.
.Example storage-consumption.yaml
[source,yaml]
----
apiVersion: v1
kind: ResourceQuota
metadata:
name: storage-consumption
spec:
hard:
persistentvolumeclaims: "10" <1>
requests.storage: "50Gi" <2>
gold.storageclass.storage.k8s.io/requests.storage: "10Gi" <3>
silver.storageclass.storage.k8s.io/requests.storage: "20Gi" <4>
silver.storageclass.storage.k8s.io/persistentvolumeclaims: "5" <5>
bronze.storageclass.storage.k8s.io/requests.storage: "0" <6>
bronze.storageclass.storage.k8s.io/persistentvolumeclaims: "0" <7>
----
<1> The total number of persistent volume claims in a project
<2> Across all persistent volume claims in a project, the sum of storage requested cannot exceed this value.
<3> Across all persistent volume claims in a project, the sum of storage requested in the gold storage class cannot exceed this value.
<4> Across all persistent volume claims in a project, the sum of storage requested in the silver storage class cannot exceed this value.
<5> Across all persistent volume claims in a project, the total number of claims in the silver storage class cannot exceed this value.
<6> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this is set to `0`, it means bronze storage class cannot request storage.
<7> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this is set to `0`, it means bronze storage class cannot create claims.
== Creating a quota
To create a quota, first define the quota in a file. Then use that file to apply it to a project. See the Additional resources section for a link describing this.
[source,terminal]
----
$ oc create -f <resource_quota_definition> [-n <project_name>]
----
Here is an example using the `core-object-counts.yaml` resource quota definition and the `demoproject` project name:
[source,terminal]
----
$ oc create -f core-object-counts.yaml -n demoproject
----
== Creating object count quotas
You can create an object count quota for all {product-title} standard namespaced resource types, such as `BuildConfig`, and `DeploymentConfig`. An object quota count places a defined quota on all standard namespaced resource types.
When using a resource quota, an object is charged against the quota if it exists in server storage. These types of quotas are useful to protect against exhaustion of storage resources.
To configure an object count quota for a resource, run the following command:
[source,terminal]
----
$ oc create quota <name> --hard=count/<resource>.<group>=<quota>,count/<resource>.<group>=<quota>
----
.Example showing object count quota:
[source,terminal]
----
$ oc create quota test --hard=count/deployments.extensions=2,count/replicasets.extensions=4,count/pods=3,count/secrets=4
resourcequota "test" created
$ oc describe quota test
Name: test
Namespace: quota
Resource Used Hard
-------- ---- ----
count/deployments.extensions 0 2
count/pods 0 3
count/replicasets.extensions 0 4
count/secrets 0 4
----
This example limits the listed resources to the hard limit in each project in the cluster.
== Viewing a quota
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 `Quota` page.
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`:
+
[source,terminal]
----
$ oc get quota -n demoproject
NAME AGE
besteffort 11m
compute-resources 2m
core-object-counts 29m
----
. Describe the quota you are interested in, for example the `core-object-counts` quota:
+
[source,terminal]
----
$ oc describe quota core-object-counts -n demoproject
Name: core-object-counts
Namespace: demoproject
Resource Used Hard
-------- ---- ----
configmaps 3 10
persistentvolumeclaims 0 4
replicationcontrollers 3 20
secrets 9 10
services 2 10
----
ifdef::openshift-origin,openshift-enterprise[]
== 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 can encounter problems when attempting to reuse the resources. You can change the `resource-quota-sync-period` setting to have the set of resources regenerate in the needed amount of time (in seconds) for the resources to be once again available:
.Example `resource-quota-sync-period` setting
[source,yaml]
----
kubernetesMasterConfig:
apiLevels:
- v1beta3
- v1
apiServerArguments: null
controllerArguments:
resource-quota-sync-period:
- "10s"
----
After making any changes, restart the controller services to apply them.
[source,terminal]
----
$ master-restart api
$ master-restart controllers
----
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 balances system performance. Reducing the sync period can result in a heavy load on the controller.
====
endif::[]
ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
== Explicit quota to consume a resource
If a resource is not managed by quota, a user has no restriction on the amount of resource that can be consumed. For example, if there is no quota on storage related to the gold storage class, the amount of gold storage a project can create is unbounded.
For high-cost compute or storage resources, administrators can require an explicit quota be granted to consume a resource. For example, if a project was not explicitly given quota for storage related to the gold storage class, users of that project would not be able to create any storage of that type.
In order to require explicit quota to consume a particular resource, the following stanza should be added to the master-config.yaml.
[source,yaml]
----
admissionConfig:
pluginConfig:
ResourceQuota:
configuration:
apiVersion: resourcequota.admission.k8s.io/v1alpha1
kind: Configuration
limitedResources:
- resource: persistentvolumeclaims <1>
matchContains:
- gold.storageclass.storage.k8s.io/requests.storage <2>
----
<1> The group or resource to whose consumption is limited by default.
<2> The name of the resource tracked by quota associated with the group/resource to limit by default.
In the above example, the quota system intercepts every operation that creates or updates a `PersistentVolumeClaim`. It checks what resources controlled by quota would be consumed. If there is no covering quota for those resources in the project, the request is denied. In this example, if a user creates a `PersistentVolumeClaim` that uses storage associated with the gold storage class and there is no matching quota in the project, the request is denied.
endif::[]

View File

@@ -1 +0,0 @@
../snippets/

View File

@@ -0,0 +1,66 @@
:_mod-docs-content-type: ASSEMBLY
[id="compute-resource-quotas"]
= Using quotas and limit ranges
include::_attributes/common-attributes.adoc[]
:context: using-quotas-and-limit-ranges
toc::[]
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 and storage that may be consumed by resources in that project.
Using quotas and limit ranges, cluster administrators can set constraints to limit the number of objects or amount of compute resources that are used in your project. This helps cluster administrators better manage and allocate resources across all projects, and ensure that no projects are using more than is appropriate for the cluster size.
[IMPORTANT]
====
Quotas are set by cluster administrators and are scoped to a given project. {product-title} project owners can change quotas for their project, but not limit ranges. {product-title} users cannot modify quotas or limit ranges.
====
The following sections help you understand how to check on your quota and limit range settings, what sorts of things they can constrain, and how you can request or limit compute resources in your own pods and containers.
include::modules/admin-quota-overview.adoc[leveloffset=+1]
.Additional resources
See xref:../applications/quotas/quotas-setting-per-project.adoc[Resources managed by quotas] for more on compute resources.
See xref:../nodes/clusters/nodes-cluster-overcommit.adoc#nodes-cluster-overcommit-resource-requests_nodes-cluster-overcommit[Quality of Service Classes] for more on committing compute resources.
include::modules/admin-quota-usage.adoc[leveloffset=+1]
.Additional resources
For examples of how to create the file needed to set quotas, see
xref:../applications/quotas/quotas-setting-per-project.adoc#quotas-resources-managed_quotas-setting-per-project[Resources managed by quotas].
A description of how to allocate xref:../applications/quotas/quotas-setting-per-project.adoc#quotas-resources-managed_quotas-setting-per-project[compute resources managed by quota].
For information on managing limits and quota on project resources, see
xref:../applications/projects/working-with-projects.adoc#working-with-projects-create-project[Working with projects].
If a quota has been defined for your project, see xref:../applications/deployments/what-deployments-are.adoc[Understanding deployments] for considerations in cluster configurations.
include::modules/admin-quota-limits.adoc[leveloffset=+1]
.Additional resources
For information on stream limits, see xref:../openshift_images/image-streams-manage.adoc#images-imagestream-use_image-streams-managing[managing images streams].
For information on xref:../nodes/clusters/nodes-cluster-limit-ranges.adoc#nodes-cluster-limit-stream-limits[stream limits].
For more information on xref:../nodes/clusters/nodes-cluster-limit-ranges.adoc#nodes-cluster-limit-ranges-about_nodes-cluster-limit-ranges[compute resource constraints].
For more information on how CPU and memory are measured, see xref:../scalability_and_performance/recommended-performance-scale-practices/recommended-control-plane-practices.adoc#recommended-scale-practices_recommended-control-plane-practices[Recommended control plane practices].
You can specify limits and requests for ephemeral storage. For more information on this feature, see xref:../storage/understanding-ephemeral-storage.adoc#storage-ephemeral-storage-overview_understanding-ephemeral-storage[Understanding ephemeral storage].
include::modules/admin-limit-operations.adoc[leveloffset=+1]
.Additional resources
For information about enforcing different limits on the number of projects that your users can create, managing limits, and quota on project resources, see xref:../applications/quotas/quotas-setting-per-project.adoc[Resource quotas per projects].