Merge pull request #13725 from HaiyangDING/update_resource-quota_doc

Auto commit by PR queue bot
This commit is contained in:
k8s-merge-robot 2015-09-22 08:56:12 -07:00
commit ab07e320ec
3 changed files with 84 additions and 68 deletions

23
docs/admin/resource-quota.md Normal file → Executable file
View 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
View 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 -->
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/admin/resourcequota/README.md?pixel)]() [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/admin/resourcequota/README.md?pixel)]()
<!-- END MUNGE: GENERATED_ANALYTICS --> <!-- END MUNGE: GENERATED_ANALYTICS -->

5
docs/admin/resourcequota/limits.yaml Normal file → Executable file
View 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