Add quota docs to v4

_topic_map.yml

@@ -144,6 +144,15 @@ Topics:
   File: creating-project-other-user
   Distros: openshift-enterprise,openshift-origin
 ---
+Name: Administering clusters
+Dir: administering_clusters
+Distros: openshift-origin, openshift-enterprise
+Topics:
+- Name: Setting quotas per project
+  File: quotas-setting-per-project
+- Name: Setting quotas across multiple projects
+  File: quotas-setting-across-multiple-projects
+---
 Name: Networking
 Dir: networking
 Distros: openshift-*

administering_clusters/quotas-setting-across-multiple-projects.adoc

@@ -0,0 +1,23 @@
+[id='setting-quotas-across-multiple-projects']
+= Setting quotas across multiple projects
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+:prewrap!:
+:context: setting-quotas-across-multiple-projects
+
+toc::[]
+
+{nbsp} +
+A multi-project quota, defined by a `ClusterResourceQuota` object, allows quotas
+to be shared across multiple projects. Resources used in each selected project
+will be aggregated and that aggregate will be used to limit resources across all
+the selected projects.
+
+include::modules/quotas-selecting-projects.adoc[leveloffset=+1]
+include::modules/quotas-viewing-clusterresourcequotas.adoc[leveloffset=+1]
+include::modules/quotas-selection-granularity.adoc[leveloffset=+1]

administering_clusters/quotas-setting-per-project.adoc

@@ -0,0 +1,31 @@
+[id='quotas-setting-per-project']
+= Setting quotas per project
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+:prewrap!:
+:context: quotas-setting-per-project
+
+toc::[]
+
+{nbsp} +
+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.
+
+include::modules/quotas-resources-managed.adoc[leveloffset=+1]
+include::modules/quotas-scopes.adoc[leveloffset=+1]
+include::modules/quotas-enforcement.adoc[leveloffset=+1]
+include::modules/quotas-requests-vs-limits.adoc[leveloffset=+1]
+include::modules/quotas-sample-resource-quotas-def.adoc[leveloffset=+1]
+include::modules/quotas-creating-a-quota.adoc[leveloffset=+1]
+include::modules/quotas-creating-object-count-quotas.adoc[leveloffset=+2]
+include::modules/setting-resource-quota-for-extended-resources.adoc[leveloffset=+2]
+include::modules/quotas-viewing-quotas.adoc[leveloffset=+1]
+include::modules/quotas-configuring-quota-sync-period.adoc[leveloffset=+1]
+include::modules/quotas-requiring-explicit-quota.adoc[leveloffset=+1]

modules/quotas-configuring-quota-sync-period.adoc

@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * administering_clusters/quotas-setting-per-project.adoc
+
+[id='quotas-configuring-quota-sync-period']
+[[]]
+= Configuring quota synchronization period
+
+When a set of resources are deleted, but before quota usage is restored, a user
+might encounter problems when attempting to reuse the resources. The
+synchronization time frame of resources is determined by the
+`resource-quota-sync-period` setting, which can be configured by a cluster
+administrator.
+
+Adjusting the regeneration time can be helpful for creating resources and
+determining resource usage when automation is used.
+
+[NOTE]
+====
+The `resource-quota-sync-period` setting is designed to balance system
+performance. Reducing the sync period can result in a heavy load on the master.
+====
+
+.Procedure
+
+To configure the quota synchronization period:
+
+. Change the `resource-quota-sync-period` setting to have the set of resources
+regenerate at the desired amount of time (in seconds) and for the resources to
+be available again:
++
+[source,yaml]
+----
+kubernetesMasterConfig:
+  apiLevels:
+  - v1beta3
+  - v1
+  apiServerArguments: null
+  controllerArguments:
+    resource-quota-sync-period:
+      - "10s"
+----
+
+. Restart the master services to apply the changes:
++
+----
+# master-restart api
+# master-restart controllers
+----

modules/quotas-creating-a-quota.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * administering_clusters/quotas-setting-per-project.adoc
+
+[id='quotas-creating-a-quota']
+= Creating a quota
+
+You can create a quota to constrain resource usage in a given project.
+
+.Procedure
+
+. Define the quota in a file. See
+xref:../administering_clusters/quotas-setting-per-project.adoc#quotas-sample-resource-quota-definitions[Sample resource quota definitions]
+for examples.
+
+. Use the file to create the quota and apply it to a project:
++
+----
+$ oc create -f <file> [-n <project_name>]
+----
++
+For example:
++
+----
+$ oc create -f core-object-counts.yaml -n demoproject
+----

modules/quotas-creating-object-count-quotas.adoc

@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// * administering_clusters/quotas-setting-per-project.adoc
+
+[id='quota-creating-object-count-quotas-{context}']
+== 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.
+
+.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> <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.
++
+For example:
++
+----
+$ oc create quota test \
+    --hard=count/deployments.extensions=2,count/replicasets.extensions=4,count/pods=3,count/secrets=4
+resourcequota "test" created
+----
++
+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
+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
+----

modules/quotas-enforcement.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * administering_clusters/quotas-setting-per-project.adoc
+
+[id='quota-enforcement-{context}']
+= Quota enforcement
+
+After a resource quota for a project is first created, the project restricts the
+ability to create any new resources that may violate a quota constraint until it
+has calculated updated usage statistics.
+
+After a quota is created and usage statistics are updated, the project accepts
+the creation of new content. When you create or modify resources, your quota
+usage is incremented immediately upon the request to create or modify the
+resource.
+
+When you delete a resource, your quota use is decremented during the next full
+recalculation of quota statistics for the project. 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.

modules/quotas-requests-vs-limits.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * administering_clusters/quotas-setting-per-project.adoc
+
+[id='quotas-requests-vs-limits']
+= Requests versus limits
+
+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.

modules/quotas-requiring-explicit-quota.adoc

@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * administering_clusters/quotas-setting-per-project.adoc
+
+[id='quota-requiring-explicit-quota-{context}']
+== Requiring 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 might want to require
+an explicit quota be granted in order 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.
+
+.Procedure
+
+To require explicit quota to consume a particular resource:
+
+. Add the following stanza to the master configuration:
++
+[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/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 understood
+by quota would be consumed, and 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.