mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-26 05:03:09 +00:00
Merge pull request #13725 from HaiyangDING/update_resource-quota_doc
Auto commit by PR queue bot
This commit is contained in:
commit
ab07e320ec
23
docs/admin/resource-quota.md
Normal file → Executable file
23
docs/admin/resource-quota.md
Normal file → Executable file
@ -40,15 +40,24 @@ Resource quotas are a tool for administrators to address this concern. Resource
|
|||||||
work like this:
|
work like this:
|
||||||
- Different teams work in different namespaces. Currently this is voluntary, but
|
- Different teams work in different namespaces. Currently this is voluntary, but
|
||||||
support for making this mandatory via ACLs is planned.
|
support for making this mandatory via ACLs is planned.
|
||||||
- Users put [compute resource limits](../user-guide/compute-resources.md) on their pods.
|
|
||||||
- The administrator creates a Resource Quota for each namespace.
|
- The administrator creates a Resource Quota for each namespace.
|
||||||
|
- Users put compute resource requests on their pods. The sum of all resource requests across
|
||||||
|
all pods in the same namespace must not exceed any hard resource limit in any Resource Quota
|
||||||
|
document for the namespace. Note that we used to verify Resource Quota by taking the sum of
|
||||||
|
resource limits of the pods, but this was altered to use resource requests. Backwards compatibility
|
||||||
|
for those pods previously created is preserved because pods that only specify a resource limit have
|
||||||
|
their resource requests defaulted to match their defined limits. The user is only charged for the
|
||||||
|
resources they request in the Resource Quota versus their limits because the request is the minimum
|
||||||
|
amount of resource guaranteed by the cluster during scheduling. For more information on over commit,
|
||||||
|
see [compute-resources](../user-guide/compute-resources.md).
|
||||||
- If creating a pod would cause the namespace to exceed any of the limits specified in the
|
- If creating a pod would cause the namespace to exceed any of the limits specified in the
|
||||||
the Resource Quota for that namespace, then the request will fail with HTTP status
|
the Resource Quota for that namespace, then the request will fail with HTTP status
|
||||||
code `403 FORBIDDEN`.
|
code `403 FORBIDDEN`.
|
||||||
- If quota is enabled in a namespace and the user does not specify limits on the pod for each
|
- If quota is enabled in a namespace and the user does not specify *requests* on the pod for each
|
||||||
of the resources for which quota is enabled, then the POST of the pod will fail with HTTP
|
of the resources for which quota is enabled, then the POST of the pod will fail with HTTP
|
||||||
status code `403 FORBIDDEN`. Hint: Use the LimitRange admission controller to force default
|
status code `403 FORBIDDEN`. Hint: Use the LimitRange admission controller to force default
|
||||||
values of limits before the quota is checked to avoid this problem.
|
values of *limits* (then resource *requests* would be equal to *limits* by default, see
|
||||||
|
[admission controller](admission-controllers.md)) before the quota is checked to avoid this problem.
|
||||||
|
|
||||||
Examples of policies that could be created using namespaces and quotas are:
|
Examples of policies that could be created using namespaces and quotas are:
|
||||||
- In a cluster with a capacity of 32 GiB RAM, and 16 cores, let team A use 20 Gib and 10 cores,
|
- In a cluster with a capacity of 32 GiB RAM, and 16 cores, let team A use 20 Gib and 10 cores,
|
||||||
@ -78,10 +87,10 @@ in a namespace can be limited. The following compute resource types are support
|
|||||||
|
|
||||||
| ResourceName | Description |
|
| ResourceName | Description |
|
||||||
| ------------ | ----------- |
|
| ------------ | ----------- |
|
||||||
| cpu | Total cpu limits of containers |
|
| cpu | Total cpu requests of containers |
|
||||||
| memory | Total memory limits of containers
|
| memory | Total memory requests of containers
|
||||||
|
|
||||||
For example, `cpu` quota sums up the `resources.limits.cpu` fields of every
|
For example, `cpu` quota sums up the `resources.requests.cpu` fields of every
|
||||||
container of every pod in the namespace, and enforces a maximum on that sum.
|
container of every pod in the namespace, and enforces a maximum on that sum.
|
||||||
|
|
||||||
## Object Count Quota
|
## Object Count Quota
|
||||||
@ -107,7 +116,7 @@ supply of Pod IPs.
|
|||||||
|
|
||||||
## Viewing and Setting Quotas
|
## Viewing and Setting Quotas
|
||||||
|
|
||||||
Kubectl supports creating, updating, and viewing quotas
|
Kubectl supports creating, updating, and viewing quotas:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ kubectl namespace myspace
|
$ kubectl namespace myspace
|
||||||
|
124
docs/admin/resourcequota/README.md
Normal file → Executable file
124
docs/admin/resourcequota/README.md
Normal file → Executable file
@ -32,7 +32,9 @@ Documentation for other releases can be found at
|
|||||||
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
||||||
Resource Quota
|
Resource Quota
|
||||||
========================================
|
========================================
|
||||||
This example demonstrates how [resource quota](../../admin/admission-controllers.md#resourcequota) and [limits](../../admin/admission-controllers.md#limitranger) can be applied to a Kubernetes namespace. See [ResourceQuota design doc](../../design/admission_control_resource_quota.md) for more information.
|
This example demonstrates how [resource quota](../../admin/admission-controllers.md#resourcequota) and
|
||||||
|
[limitsranger](../../admin/admission-controllers.md#limitranger) can be applied to a Kubernetes namespace.
|
||||||
|
See [ResourceQuota design doc](../../design/admission_control_resource_quota.md) for more information.
|
||||||
|
|
||||||
This example assumes you have a functional Kubernetes setup.
|
This example assumes you have a functional Kubernetes setup.
|
||||||
|
|
||||||
@ -44,26 +46,29 @@ Let's create a new namespace called quota-example:
|
|||||||
|
|
||||||
```console
|
```console
|
||||||
$ kubectl create -f docs/admin/resourcequota/namespace.yaml
|
$ kubectl create -f docs/admin/resourcequota/namespace.yaml
|
||||||
|
namespace "quota-example" created
|
||||||
$ kubectl get namespaces
|
$ kubectl get namespaces
|
||||||
NAME LABELS STATUS
|
NAME LABELS STATUS AGE
|
||||||
default <none> Active
|
default <none> Active 2m
|
||||||
quota-example <none> Active
|
quota-example <none> Active 39s
|
||||||
```
|
```
|
||||||
|
|
||||||
Step 2: Apply a quota to the namespace
|
Step 2: Apply a quota to the namespace
|
||||||
-----------------------------------------
|
-----------------------------------------
|
||||||
By default, a pod will run with unbounded CPU and memory limits. This means that any pod in the
|
By default, a pod will run with unbounded CPU and memory requests/limits. This means that any pod in the
|
||||||
system will be able to consume as much CPU and memory on the node that executes the pod.
|
system will be able to consume as much CPU and memory on the node that executes the pod.
|
||||||
|
|
||||||
Users may want to restrict how much of the cluster resources a given namespace may consume
|
Users may want to restrict how much of the cluster resources a given namespace may consume
|
||||||
across all of its pods in order to manage cluster usage. To do this, a user applies a quota to
|
across all of its pods in order to manage cluster usage. To do this, a user applies a quota to
|
||||||
a namespace. A quota lets the user set hard limits on the total amount of node resources (cpu, memory)
|
a namespace. A quota lets the user set hard limits on the total amount of node resources (cpu, memory)
|
||||||
and API resources (pods, services, etc.) that a namespace may consume.
|
and API resources (pods, services, etc.) that a namespace may consume. In term of resources, Kubernetes
|
||||||
|
checks the total resource *requests*, not resource *limits* of all containers/pods in the namespace.
|
||||||
|
|
||||||
Let's create a simple quota in our namespace:
|
Let's create a simple quota in our namespace:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ kubectl create -f docs/admin/resourcequota/quota.yaml --namespace=quota-example
|
$ kubectl create -f docs/admin/resourcequota/quota.yaml --namespace=quota-example
|
||||||
|
resourcequota "quota" created
|
||||||
```
|
```
|
||||||
|
|
||||||
Once your quota is applied to a namespace, the system will restrict any creation of content
|
Once your quota is applied to a namespace, the system will restrict any creation of content
|
||||||
@ -74,23 +79,23 @@ namespace.
|
|||||||
|
|
||||||
```console
|
```console
|
||||||
$ kubectl describe quota quota --namespace=quota-example
|
$ kubectl describe quota quota --namespace=quota-example
|
||||||
Name: quota
|
Name: quota
|
||||||
Namespace: quota-example
|
Namespace: quota-example
|
||||||
Resource Used Hard
|
Resource Used Hard
|
||||||
-------- ---- ----
|
-------- ---- ----
|
||||||
cpu 0 20
|
cpu 0 20
|
||||||
memory 0 1Gi
|
memory 0 1Gi
|
||||||
persistentvolumeclaims 0 10
|
persistentvolumeclaims 0 10
|
||||||
pods 0 10
|
pods 0 10
|
||||||
replicationcontrollers 0 20
|
replicationcontrollers 0 20
|
||||||
resourcequotas 1 1
|
resourcequotas 1 1
|
||||||
secrets 1 10
|
secrets 1 10
|
||||||
services 0 5
|
services 0 5
|
||||||
```
|
```
|
||||||
|
|
||||||
Step 3: Applying default resource limits
|
Step 3: Applying default resource requests and limits
|
||||||
-----------------------------------------
|
-----------------------------------------
|
||||||
Pod authors rarely specify resource limits for their pods.
|
Pod authors rarely specify resource requests and limits for their pods.
|
||||||
|
|
||||||
Since we applied a quota to our project, let's see what happens when an end-user creates a pod that has unbounded
|
Since we applied a quota to our project, let's see what happens when an end-user creates a pod that has unbounded
|
||||||
cpu and memory by creating an nginx container.
|
cpu and memory by creating an nginx container.
|
||||||
@ -99,8 +104,7 @@ To demonstrate, lets create a replication controller that runs nginx:
|
|||||||
|
|
||||||
```console
|
```console
|
||||||
$ kubectl run nginx --image=nginx --replicas=1 --namespace=quota-example
|
$ kubectl run nginx --image=nginx --replicas=1 --namespace=quota-example
|
||||||
CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS
|
replicationcontroller "nginx" created
|
||||||
nginx nginx nginx run=nginx 1
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Now let's look at the pods that were created.
|
Now let's look at the pods that were created.
|
||||||
@ -114,78 +118,78 @@ What happened? I have no pods! Let's describe the replication controller to ge
|
|||||||
|
|
||||||
```console
|
```console
|
||||||
kubectl describe rc nginx --namespace=quota-example
|
kubectl describe rc nginx --namespace=quota-example
|
||||||
Name: nginx
|
Name: nginx
|
||||||
Image(s): nginx
|
Namespace: quota-example
|
||||||
Selector: run=nginx
|
Image(s): nginx
|
||||||
Labels: run=nginx
|
Selector: run=nginx
|
||||||
Replicas: 0 current / 1 desired
|
Labels: run=nginx
|
||||||
Pods Status: 0 Running / 0 Waiting / 0 Succeeded / 0 Failed
|
Replicas: 0 current / 1 desired
|
||||||
|
Pods Status: 0 Running / 0 Waiting / 0 Succeeded / 0 Failed
|
||||||
|
No volumes.
|
||||||
Events:
|
Events:
|
||||||
FirstSeen LastSeen Count From SubobjectPath Reason Message
|
FirstSeen LastSeen Count From SubobjectPath Reason Message
|
||||||
Mon, 01 Jun 2015 22:49:31 -0400 Mon, 01 Jun 2015 22:52:22 -0400 7 {replication-controller } failedCreate Error creating: Pod "nginx-" is forbidden: Limited to 1Gi memory, but pod has no specified memory limit
|
42s 11s 3 {replication-controller } FailedCreate Error creating: Pod "nginx-" is forbidden: Must make a non-zero request for memory since it is tracked by quota.
|
||||||
```
|
```
|
||||||
|
|
||||||
The Kubernetes API server is rejecting the replication controllers requests to create a pod because our pods
|
The Kubernetes API server is rejecting the replication controllers requests to create a pod because our pods
|
||||||
do not specify any memory usage.
|
do not specify any memory usage *request*.
|
||||||
|
|
||||||
So let's set some default limits for the amount of cpu and memory a pod can consume:
|
So let's set some default values for the amount of cpu and memory a pod can consume:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ kubectl create -f docs/admin/resourcequota/limits.yaml --namespace=quota-example
|
$ kubectl create -f docs/admin/resourcequota/limits.yaml --namespace=quota-example
|
||||||
limitranges/limits
|
limitrange "limits" created
|
||||||
$ kubectl describe limits limits --namespace=quota-example
|
$ kubectl describe limits limits --namespace=quota-example
|
||||||
Name: limits
|
Name: limits
|
||||||
Namespace: quota-example
|
Namespace: quota-example
|
||||||
Type Resource Min Max Default
|
Type Resource Min Max Request Limit Limit/Request
|
||||||
---- -------- --- --- ---
|
---- -------- --- --- ------- ----- -------------
|
||||||
Container memory - - 512Mi
|
Container memory - - 256Mi 512Mi -
|
||||||
Container cpu - - 100m
|
Container cpu - - 100m 200m -
|
||||||
```
|
```
|
||||||
|
|
||||||
Now any time a pod is created in this namespace, if it has not specified any resource limits, the default
|
Now any time a pod is created in this namespace, if it has not specified any resource request/limit, the default
|
||||||
amount of cpu and memory per container will be applied as part of admission control.
|
amount of cpu and memory per container will be applied, and the request will be used as part of admission control.
|
||||||
|
|
||||||
Now that we have applied default limits for our namespace, our replication controller should be able to
|
Now that we have applied default resource *request* for our namespace, our replication controller should be able to
|
||||||
create its pods.
|
create its pods.
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ kubectl get pods --namespace=quota-example
|
$ kubectl get pods --namespace=quota-example
|
||||||
NAME READY STATUS RESTARTS AGE
|
NAME READY STATUS RESTARTS AGE
|
||||||
nginx-t9cap 1/1 Running 0 49s
|
nginx-fca65 1/1 Running 0 1m
|
||||||
```
|
```
|
||||||
|
|
||||||
And if we print out our quota usage in the namespace:
|
And if we print out our quota usage in the namespace:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ kubectl describe quota quota --namespace=quota-example
|
$ kubectl describe quota quota --namespace=quota-example
|
||||||
Name: quota
|
Name: quota
|
||||||
Namespace: default
|
Namespace: quota-example
|
||||||
Resource Used Hard
|
Resource Used Hard
|
||||||
-------- ---- ----
|
-------- ---- ----
|
||||||
cpu 100m 20
|
cpu 100m 20
|
||||||
memory 536870912 1Gi
|
memory 256Mi 1Gi
|
||||||
persistentvolumeclaims 0 10
|
persistentvolumeclaims 0 10
|
||||||
pods 1 10
|
pods 1 10
|
||||||
replicationcontrollers 1 20
|
replicationcontrollers 1 20
|
||||||
resourcequotas 1 1
|
resourcequotas 1 1
|
||||||
secrets 1 10
|
secrets 1 10
|
||||||
services 0 5
|
services 0 5
|
||||||
```
|
```
|
||||||
|
|
||||||
You can now see the pod that was created is consuming explicit amounts of resources, and the usage is being
|
You can now see the pod that was created is consuming explicit amounts of resources (specified by resource *request*),
|
||||||
tracked by the Kubernetes system properly.
|
and the usage is being tracked by the Kubernetes system properly.
|
||||||
|
|
||||||
Summary
|
Summary
|
||||||
----------------------------
|
----------------------------
|
||||||
Actions that consume node resources for cpu and memory can be subject to hard quota limits defined
|
Actions that consume node resources for cpu and memory can be subject to hard quota limits defined
|
||||||
by the namespace quota.
|
by the namespace quota. The resource consumption is measured by resource *request* in pod specification.
|
||||||
|
|
||||||
Any action that consumes those resources can be tweaked, or can pick up namespace level defaults to
|
Any action that consumes those resources can be tweaked, or can pick up namespace level defaults to
|
||||||
meet your end goal.
|
meet your end goal.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||||
[]()
|
[]()
|
||||||
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||||
|
5
docs/admin/resourcequota/limits.yaml
Normal file → Executable file
5
docs/admin/resourcequota/limits.yaml
Normal file → Executable file
@ -5,6 +5,9 @@ metadata:
|
|||||||
spec:
|
spec:
|
||||||
limits:
|
limits:
|
||||||
- default:
|
- default:
|
||||||
cpu: 100m
|
cpu: 200m
|
||||||
memory: 512Mi
|
memory: 512Mi
|
||||||
|
defaultRequest:
|
||||||
|
cpu: 100m
|
||||||
|
memory: 256Mi
|
||||||
type: Container
|
type: Container
|
||||||
|
Loading…
Reference in New Issue
Block a user