This documentation is for a release that is no longer maintained
See documentation for the latest supported version 3 or the latest supported version 4.Chapter 9. Quotas
9.1. Resource quotas per project Copy linkLink copied to clipboard!
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 might be consumed by resources in that project.
This guide describes how resource quotas work, how cluster administrators can set and manage resource quotas on a per project basis, and how developers and cluster administrators can view them.
9.1.1. Resources managed by quotas Copy linkLink copied to clipboard!
The following describes the set of compute resources and object types that can be managed by a quota.
A pod is in a terminal state if status.phase in (Failed, Succeeded)
is true.
Resource Name | Description |
---|---|
|
The sum of CPU requests across all pods in a non-terminal state cannot exceed this value. |
|
The sum of memory requests across all pods in a non-terminal state cannot exceed this value. |
|
The sum of CPU requests across all pods in a non-terminal state cannot exceed this value. |
|
The sum of memory requests across all pods in a non-terminal state cannot exceed this value. |
| The sum of CPU limits across all pods in a non-terminal state cannot exceed this value. |
| The sum of memory limits across all pods in a non-terminal state cannot exceed this value. |
Resource Name | Description |
---|---|
| The sum of storage requests across all persistent volume claims in any state cannot exceed this value. |
| The total number of persistent volume claims that can exist in the project. |
| The sum of storage requests across all persistent volume claims in any state that have a matching storage class, cannot exceed this value. |
| The total number of persistent volume claims with a matching storage class that can exist in the project. |
|
The sum of local ephemeral storage requests across all pods in a non-terminal state cannot exceed this value. |
|
The sum of ephemeral storage requests across all pods in a non-terminal state cannot exceed this value. |
| The sum of ephemeral storage limits across all pods in a non-terminal state cannot exceed this value. |
Resource Name | Description |
---|---|
| The total number of pods in a non-terminal state that can exist in the project. |
| The total number of ReplicationControllers that can exist in the project. |
| The total number of resource quotas that can exist in the project. |
| The total number of services that can exist in the project. |
|
The total number of services of type |
|
The total number of services of type |
| The total number of secrets that can exist in the project. |
|
The total number of |
| The total number of persistent volume claims that can exist in the project. |
| The total number of imagestreams that can exist in the project. |
9.1.2. Quota scopes Copy linkLink copied to clipboard!
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.
Scope | Description |
|
Match pods that have best effort quality of service for either |
|
Match pods that do not have best effort quality of service for |
A BestEffort
scope restricts a quota to limiting the following resources:
-
pods
A NotBestEffort
scope restricts a quota to tracking the following resources:
-
pods
-
memory
-
requests.memory
-
limits.memory
-
cpu
-
requests.cpu
-
limits.cpu
9.1.3. Quota enforcement Copy linkLink copied to clipboard!
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. 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 statistics are in the system.
9.1.4. Requests versus limits Copy linkLink copied to clipboard!
When allocating compute resources, each container might 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.
9.1.5. Sample resource quota definitions Copy linkLink copied to clipboard!
core-object-counts.yaml
- 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.
- 6
- The total number of services of type
LoadBalancer
that can exist in the project.
openshift-object-counts.yaml
- 1
- The total number of image streams that can exist in the project.
compute-resources.yaml
- 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
compute-resources-long-running.yaml
- 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
- Restricts the quota to only matching pods where
spec.activeDeadlineSeconds
is set tonil
. Build pods fall underNotTerminating
unless theRestartNever
policy is applied.
compute-resources-time-bound.yaml
- 1
- The total number of pods in a terminating state.
- 2
- Across all pods in a terminating state, the sum of CPU limits cannot exceed this value.
- 3
- Across all pods in a terminating state, the sum of memory limits cannot exceed this value.
- 4
- Restricts the quota to only matching pods where
spec.activeDeadlineSeconds >=0
. For example, this quota charges for build or deployer pods, but not long running pods like a web server or database.
storage-consumption.yaml
- 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. - 8
- Across all pods in a non-terminal state, the sum of ephemeral storage requests cannot exceed 2Gi.
- 9
- Across all pods in a non-terminal state, the sum of ephemeral storage limits cannot exceed 4Gi.
9.1.6. Creating a quota Copy linkLink copied to clipboard!
You can create a quota to constrain resource usage in a given project.
Procedure
- Define the quota in a file.
Use the file to create the quota and apply it to a project:
oc create -f <file> [-n <project_name>]
$ oc create -f <file> [-n <project_name>]
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example:
oc create -f core-object-counts.yaml -n demoproject
$ oc create -f core-object-counts.yaml -n demoproject
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
9.1.6.1. Creating object count quotas Copy linkLink copied to clipboard!
You can create an object count quota for all standard namespaced resource types on OpenShift Container Platform, such as BuildConfig
and DeploymentConfig
objects. 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 upon creation. These types of quotas are useful to protect against exhaustion of resources. The quota can only be created if there are enough spare resources within the project.
Procedure
To configure an object count quota for a resource:
Run the following command:
oc create quota <name> \ --hard=count/<resource>.<group>=<quota>,count/<resource>.<group>=<quota>
$ oc create quota <name> \ --hard=count/<resource>.<group>=<quota>,count/<resource>.<group>=<quota>
1 Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- The
<resource>
variable is the name of the resource, and<group>
is the API group, if applicable. Use theoc api-resources
command for a list of resources and their associated API groups.
For example:
oc create quota test \ --hard=count/deployments.extensions=2,count/replicasets.extensions=4,count/pods=3,count/secrets=4
$ oc create quota test \ --hard=count/deployments.extensions=2,count/replicasets.extensions=4,count/pods=3,count/secrets=4
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
resourcequota "test" created
resourcequota "test" created
Copy to Clipboard Copied! Toggle word wrap Toggle overflow This example limits the listed resources to the hard limit in each project in the cluster.
Verify that the quota was created:
oc describe quota test
$ oc describe quota test
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
9.1.6.2. Setting resource quota for extended resources Copy linkLink copied to clipboard!
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.
is allowed for extended resources. The following is an example scenario of how to set resource quota for the GPU resource nvidia.com/gpu
.
Procedure
Determine how many GPUs are available on a node in your cluster. For example:
oc describe node ip-172-31-27-209.us-west-2.compute.internal | egrep 'Capacity|Allocatable|gpu'
# oc describe node ip-172-31-27-209.us-west-2.compute.internal | egrep 'Capacity|Allocatable|gpu'
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Copy to Clipboard Copied! Toggle word wrap Toggle overflow In this example, 2 GPUs are available.
Set a quota in the namespace
nvidia
. In this example, the quota is1
:cat gpu-quota.yaml
# cat gpu-quota.yaml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create the quota:
oc create -f gpu-quota.yaml
# oc create -f gpu-quota.yaml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
resourcequota/gpu-quota created
resourcequota/gpu-quota created
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the namespace has the correct quota set:
oc describe quota gpu-quota -n nvidia
# oc describe quota gpu-quota -n nvidia
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Name: gpu-quota Namespace: nvidia Resource Used Hard -------- ---- ---- requests.nvidia.com/gpu 0 1
Name: gpu-quota Namespace: nvidia Resource Used Hard -------- ---- ---- requests.nvidia.com/gpu 0 1
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Define a pod that asks for a single GPU. The following example definition file is called
gpu-pod.yaml
:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create the pod:
oc create -f gpu-pod.yaml
# oc create -f gpu-pod.yaml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the pod is running:
oc get pods
# oc get pods
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
NAME READY STATUS RESTARTS AGE gpu-pod-s46h7 1/1 Running 0 1m
NAME READY STATUS RESTARTS AGE gpu-pod-s46h7 1/1 Running 0 1m
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the quota
Used
counter is correct:oc describe quota gpu-quota -n nvidia
# oc describe quota gpu-quota -n nvidia
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Name: gpu-quota Namespace: nvidia Resource Used Hard -------- ---- ---- requests.nvidia.com/gpu 1 1
Name: gpu-quota Namespace: nvidia Resource Used Hard -------- ---- ---- requests.nvidia.com/gpu 1 1
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Attempt to create a second GPU pod in the
nvidia
namespace. This is technically available on the node because it has 2 GPUs:oc create -f gpu-pod.yaml
# oc create -f gpu-pod.yaml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
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
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
Copy to Clipboard Copied! Toggle word wrap Toggle overflow This Forbidden error message is expected because you have a quota of 1 GPU and this pod tried to allocate a second GPU, which exceeds its quota.
9.1.7. Viewing a quota Copy linkLink copied to clipboard!
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.
Procedure
Get the list of quotas defined in the project. For example, for a project called
demoproject
:oc get quota -n demoproject
$ oc get quota -n demoproject
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
NAME AGE besteffort 11m compute-resources 2m core-object-counts 29m
NAME AGE besteffort 11m compute-resources 2m core-object-counts 29m
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Describe the quota you are interested in, for example the
core-object-counts
quota:oc describe quota core-object-counts -n demoproject
$ oc describe quota core-object-counts -n demoproject
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
9.1.8. Configuring explicit resource quotas Copy linkLink copied to clipboard!
Configure explicit resource quotas in a project request template to apply specific resource quotas in new projects.
Prerequisites
- Access to the cluster as a user with the cluster-admin role.
-
Install the OpenShift CLI (
oc
).
Procedure
Add a resource quota definition to a project request template:
If a project request template does not exist in a cluster:
Create a bootstrap project template and output it to a file called
template.yaml
:oc adm create-bootstrap-project-template -o yaml > template.yaml
$ oc adm create-bootstrap-project-template -o yaml > template.yaml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Add a resource quota definition to
template.yaml
. The following example defines a resource quota named 'storage-consumption'. The definition must be added before theparameters:
section in the template:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 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 value is set to
0
, the 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 value is set to
0
, the bronze storage class cannot create claims.
Create a project request template from the modified
template.yaml
file in theopenshift-config
namespace:oc create -f template.yaml -n openshift-config
$ oc create -f template.yaml -n openshift-config
Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteTo include the configuration as a
kubectl.kubernetes.io/last-applied-configuration
annotation, add the--save-config
option to theoc create
command.By default, the template is called
project-request
.
If a project request template already exists within a cluster:
NoteIf you declaratively or imperatively manage objects within your cluster by using configuration files, edit the existing project request template through those files instead.
List templates in the
openshift-config
namespace:oc get templates -n openshift-config
$ oc get templates -n openshift-config
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Edit an existing project request template:
oc edit template <project_request_template> -n openshift-config
$ oc edit template <project_request_template> -n openshift-config
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Add a resource quota definition, such as the preceding
storage-consumption
example, into the existing template. The definition must be added before theparameters:
section in the template.
If you created a project request template, reference it in the cluster’s project configuration resource:
Access the project configuration resource for editing:
By using the web console:
-
Navigate to the Administration
Cluster Settings page. - Click Configuration to view all configuration resources.
- Find the entry for Project and click Edit YAML.
-
Navigate to the Administration
By using the CLI:
Edit the
project.config.openshift.io/cluster
resource:oc edit project.config.openshift.io/cluster
$ oc edit project.config.openshift.io/cluster
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Update the
spec
section of the project configuration resource to include theprojectRequestTemplate
andname
parameters. The following example references the default project request template nameproject-request
:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Verify that the resource quota is applied when projects are created:
Create a project:
oc new-project <project_name>
$ oc new-project <project_name>
Copy to Clipboard Copied! Toggle word wrap Toggle overflow List the project’s resource quotas:
oc get resourcequotas
$ oc get resourcequotas
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Describe the resource quota in detail:
oc describe resourcequotas <resource_quota_name>
$ oc describe resourcequotas <resource_quota_name>
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
9.2. Resource quotas across multiple projects Copy linkLink copied to clipboard!
A multi-project quota, defined by a ClusterResourceQuota
object, allows quotas to be shared across multiple projects. Resources used in each selected project are aggregated and that aggregate is used to limit resources across all the selected projects.
This guide describes how cluster administrators can set and manage resource quotas across multiple projects.
9.2.1. Selecting multiple projects during quota creation Copy linkLink copied to clipboard!
When creating quotas, you can select multiple projects based on annotation selection, label selection, or both.
Procedure
To select projects based on annotations, run the following command:
oc create clusterquota for-user \ --project-annotation-selector openshift.io/requester=<user_name> \ --hard pods=10 \ --hard secrets=20
$ oc create clusterquota for-user \ --project-annotation-selector openshift.io/requester=<user_name> \ --hard pods=10 \ --hard secrets=20
Copy to Clipboard Copied! Toggle word wrap Toggle overflow This creates the following
ClusterResourceQuota
object:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- The
ResourceQuotaSpec
object that will be enforced over the selected projects. - 2
- A simple key-value selector for annotations.
- 3
- A label selector that can be used to select projects.
- 4
- A per-namespace map that describes current quota usage in each selected project.
- 5
- The aggregate usage across all selected projects.
This multi-project quota document controls all projects requested by
<user_name>
using the default project request endpoint. You are limited to 10 pods and 20 secrets.Similarly, to select projects based on labels, run this command:
oc create clusterresourcequota for-name \ --project-label-selector=name=frontend \ --hard=pods=10 --hard=secrets=20
$ oc create clusterresourcequota for-name \
1 --project-label-selector=name=frontend \
2 --hard=pods=10 --hard=secrets=20
Copy to Clipboard Copied! Toggle word wrap Toggle overflow This creates the following
ClusterResourceQuota
object definition:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
9.2.2. Viewing applicable cluster resource quotas Copy linkLink copied to clipboard!
A project administrator is not allowed to create or modify the multi-project quota that limits his or her project, but the administrator is allowed to view the multi-project quota documents that are applied to his or her project. The project administrator can do this via the AppliedClusterResourceQuota
resource.
Procedure
To view quotas applied to a project, run:
oc describe AppliedClusterResourceQuota
$ oc describe AppliedClusterResourceQuota
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
9.2.3. Selection granularity Copy linkLink copied to clipboard!
Because of the locking consideration when claiming quota allocations, the number of active projects selected by a multi-project quota is an important consideration. Selecting more than 100 projects under a single multi-project quota can have detrimental effects on API server responsiveness in those projects.