Merge pull request #195 from appuio/feat/edit-resource-quotas

Document how users are able to lower resource quotas

docs/modules/ROOT/nav.adoc

@@ -125,6 +125,7 @@
 .Scalability and Performance
 * xref:explanation/fair-use-policy.adoc[]
 * xref:references/default-quota.adoc[]
+** xref:how-to/lower-resource-quotas.adoc[]
 * xref:how-to/use-vpa.adoc[]
 * xref:how-to/check-cpu-requests.adoc[]
 * xref:explanation/unit-prefixes.adoc[]

docs/modules/ROOT/pages/how-to/fine-grained-access-examples.adoc

@@ -34,6 +34,7 @@ There are multiple relevant RoleBindings in each Namespace:
 * `admin` - allows the user to manage most resources in the Namespace
 * `namespace-owner` - allows the user to manage (including delete) the Namespace itself
 * `monitoring-edit`, `monitoring-edit-probe`, `alert-routing-edit` - allow the user to manage user workload monitoring related resources.
+* `resource-quota-edit` - allow the user to manage ResourceQuota objects.
 ====
 
 . Remove the user from the `mycompany` organization
@@ -137,3 +138,27 @@ subjects:
 """
 done
 ----
+
+== Give a team or user permissions to manage resource quotas in a project
+
+. Remove the user from the `organization` group
+
+. Add the user or team which should have permission to manage resource quotas to the role binding `resource-quota-edit` in the required projects.
++
+[source,bash]
+----
+ORGANIZATION=mycompany
+TEAM=developers
+PROJECT=mycompany-web-portal
+
+oc -n "${PROJECT}" patch rolebinding resource-quota-edit -oyaml --patch """
+subjects:
+  - apiGroup: rbac.authorization.k8s.io
+    kind: Group
+    name: ${ORGANIZATION}
+  - apiGroup: rbac.authorization.k8s.io
+    kind: Group
+    name: ${ORGANIZATION}+${TEAM}
+"""
+done
+----

docs/modules/ROOT/pages/how-to/lower-resource-quotas.adoc

@@ -0,0 +1,48 @@
+= Lowering Resource Quotas
+
+This page describes how you can set up custom ResourceQuota objects in your projects to lower the quota, for example to protect yourself from unexpected cost.
+
+NOTE: It's not possible to increase a project's resource quota beyond the default values using this method.
+Setting a custom ResourceQuota with a higher-than-default value will have no effect.
+
+== Creating a ResourceQuota object
+
+In each project, you'll find existing ResourceQuota objects that manage the default quotas of {product}.
+These are managed by {product} and can't be edited directly.
+In order to lower the quota for a specific resource, a new ResourceQuota object needs to be created, which contains the new, lower limit.
+
+*resourcequota.yaml*
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ResourceQuota
+metadata:
+  name: core-object-counts
+spec:
+  hard:
+    requests.cpu: "1" 
+    requests.memory: "1Gi"
+----
+
+To apply the resource quota from the file:
++
+[source,bash]
+----
+oc create -f resourcequota.yaml -n <project-name>
+----
+
+For further reference on ResourceQuota objects, refer to the https://kubernetes.io/docs/concepts/policy/resource-quotas/[official documentation].
+
+== Preventing other users from editing the ResourceQuota object
+
+In a shared project, it's often desirable to restrict access to ResourceQuota objects, to prevent others from circumventing the quota by simply increasing it.
+This can be achieved using Kubernetes RBAC.
+
+Permissions to manage ResourceQuota objects are governed by the `resource-quota-edit` RoleBinding, which is created automatically in each project by {product}.
+{product} users may freely edit this RoleBinding to suit their needs.
+By default, every user in the project's organization has permission to manage ResourceQuota objects.
+
+A more detailed how-to for fine-grained access control within a project can be found in xref:how-to/fine-grained-access-examples.adoc[].
+
+