Merge pull request #835 from mszacillo/main

Adding documentation for resource quota enforcement feature

Author: karmada-bot

docs/resources/key-features/federated-quota-enforcement.png

@@ -16,14 +16,22 @@ Here's where the `FederatedResourceQuota` API comes in. The following is several
 
 FederatedResourceQuota supports:
 
-* Global quota management for applications that run on multiple clusters.
-* Fine-grained management of quotas under the same namespace of different clusters.
-  * Ability to enumerate resource usage limits per namespace.
-  * Ability to monitor resource usage for tracked resources.
-  * Ability to reject resource usage exceeding hard quotas.
+1. **ResourceQuota Management**
+  * Set and track overall quota usage for federated applications deployed across clusters. Also supports fine-grained management of quotas under the same namespace of different clusters with:
+    * Ability to enumerate resource usage limits per namespace.
+    * Ability to monitor resource usage for tracked resources.
+    * Ability to reject resource usage exceeding hard quotas.
 
 ![unified resourcequota](../../resources/key-features/unified-resourcequota.png)
 
+2. **Karmada Control Plane-Level Quota Enforcement**
+  * Enables enforcement of namespaced resource limits at the federated level, not just per-cluster.
+  * Centralized quota checks:
+    * Resource creation and updates against Karmada control-plane
+    * Prevents overcommitment by rejecting scheduling requests that would exceed the aggregate quota for the namespace
+
+![federated quota enforcement](../../resources/key-features/federated-quota-enforcement.png)
+
 You can use FederatedResourceQuota to manage CPU, memory, storage and ephemeral-storage.
 
 ## Deploy a simplest FederatedResourceQuota
@@ -185,8 +193,50 @@ status:
     cpu: "1"
 ```
 
+## Using FederatedResourceQuota enforcement
+
+:::note
+
+FederatedResourceQuota enforcement is a new feature. This capability requires enabling the `FederatedQuotaEnforcement` feature gate. FederatedQuotaEnforcement is currently in Alpha and is turned off by default.
+
+:::
+
+The FederatedResourceQuota's base feature allows user to schedule ResourceQuotas that can control overall resource limits across many clusters using `staticAssignment`. However, you can also use the FederatedResourceQuota to impose and enforce resource limits directly against the Karmada control-plane.
+
+This can be especially useful if:
+  * You need to track resource consumption and limits from a unified place
+  * You would like to prevent unnecessary scheduling to clusters by verifying quota resource limits
+
+Using the previous spec as an example, let's assume you want to set the overall cpu limit to 100. All you would need to do is define the `Overall` limits:
+
+```yaml
+apiVersion: policy.karmada.io/v1alpha1
+kind: FederatedResourceQuota
+metadata:
+  name: test
+  namespace: test
+spec:
+  overall:
+    cpu: 100
+```
+
+Once applied, Karmada will begin monitoring and enforcing the cpu resource limit for the test namespace. Let's assume you apply a new `Deployment` that has a requirement of 20 CPU. The status of the FederatedResourceQuota will be updated to look like the following:
+
+```
+spec:
+  overall:
+    cpu: 100
+status:
+  overall:
+    cpu: "100"
+  overallUsed:
+    cpu: "20"
+```
+
+If you apply a resource that goes above the limit of 100 CPU, the resource will not be scheduled to your member clusters.
+
 :::note
 
 FederatedResourceQuota is still a work in progress. We are in the progress of gathering use cases. If you are interested in this feature, please feel free to start an enhancement issue to let us know.
 
-:::
+:::