explain multi-project quota

_build_cfg.yml

@@ -399,6 +399,8 @@ Topics:
     Distros: openshift-*
   - Name: Setting Quotas
     File: quota
+  - Name: Setting Multi-Project Quotas
+    File: multiproject_quota
   - Name: Setting Limit Ranges
     File: limits
   - Name: Pruning Objects

admin_guide/multiproject_quota.adoc

@@ -0,0 +1,105 @@
+[[admin-guide-muliproject-quota]]
+= Multi-Project Quotas
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+:prewrap!:
+
+toc::[]
+
+== Overview
+
+A multi-project quota, defined by a `*ClusterResourceQuota*` object, allows xref:../admin_guide/quota.adoc#admin-guide-quota[quota]
+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.
+
+[[multi-project-quotas-selecting-projects]]
+=== Selecting Projects
+
+Projects can be selected based on either annotation selection, label selection, or both.
+For example, `oc create clusterquota for-user --project-annotation-selector openshift.io/requester=<user-name> --hard pods=10 --hard secrets=20`
+creates: 
+
+====
+[source,yaml]
+----
+apiVersion: v1
+kind: ClusterResourceQuota
+metadata:
+  name: for-user
+spec:
+  quota: <1>
+    hard:
+      pods: "10"
+      secrets: "20"
+  selector:
+    annotations: <2>
+      openshift.io/requester: <user-name>
+    labels: null <3>
+status:
+  namespaces: <4>
+  - namespace: ns-one
+    status:
+      hard:
+        pods: "10"
+        secrets: "20"
+      used:
+        pods: "1"
+        secrets: "9"
+  total: <5>
+    hard:
+      pods: "10"
+      secrets: "20"
+    used:
+      pods: "1"
+      secrets: "9"
+----
+<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 will control all projects requested by `"<user-name>"` using the default
+project request endpoint.  He will be limited to ten pods and twenty secrets.
+
+
+[[multi-project-quotas-viewing-applicable-clusterresourcequotas]]
+=== Viewing Applicable ClusterResourceQuotas
+
+A project-admin is not allowed to create or modify the multi-project quota that limits
+him, but he is allowed to view the multi-project quota documents are applied to his project.
+He can do this via the `*AppliedClusterResourceQuota*` resource.
+
+`oc describe AppliedClusterResourceQuota` produces:
+
+====
+----
+Name:   for-user
+Namespace:  <none>
+Created:  19 hours ago
+Labels:   <none>
+Annotations:  <none>
+Label Selector: <null>
+AnnotationSelector: map[openshift.io/requester:<user-name>]
+Resource  Used  Hard
+--------  ----  ----
+pods    1 10
+secrets   9 20
+----
+====
+
+
+[[multi-project-quotas-selection-granularity]]
+=== Selection Granularity
+
+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 may have
+deleterious effects on API server responsiveness in those projects.