docs: update cro docs (#1025)

Author: zhiying-lin

docs/concepts/Override/README.md

@@ -36,6 +36,10 @@ and `ResourceOverride`.
 - At most 100 `ClusterResourceOverride` can be created.
 - At most 100 `ResourceOverride` can be created.
 
+## Placement
+
+This specifies which placement the override should be applied to.
+
 ## Resource Selector
 `ClusterResourceSelector` of `ClusterResourceOverride` selects which cluster-scoped resources need to be overridden before
 applying to the selected clusters.
@@ -64,14 +68,52 @@ Each override rule contains the following fields:
   - Select clusters by specifying the cluster labels.
   - An empty selector selects ALL the clusters.
   - A nil selector selects NO target cluster.
-- `JSONPatchOverrides`: a list of JSON path override rules applied to the selected resources following [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902).
+- `OverrideType`: which type of the override should be applied to the selected resources. The default type is `JSONPatch`.
+  - `JSONPatch`: applies the JSON patch to the selected resources using [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902).
+  - `Delete`: deletes the selected resources on the target cluster.
+- `JSONPatchOverrides`: a list of JSON path override rules applied to the selected resources following [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) when the override type is `JSONPatch`.
 
 > **Note:** Updating the fields in the TypeMeta (e.g., `apiVersion`, `kind`) is not allowed.
 
 > **Note:** Updating the fields in the ObjectMeta (e.g., `name`, `namespace`) excluding annotations and labels is not allowed.
 
 > **Note:** Updating the fields in the Status (e.g., `status`) is not allowed.
 
+### Reserved Variables in the JSON Patch Override Value
+
+There is a list of reserved variables that will be replaced by the actual values used in the `value` of the JSON patch override rule:
+* `${MEMBER-CLUSTER-NAME}`:  this will be replaced by the name of the `memberCluster` that represents this cluster.
+
+For example, to add a label to the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`,
+you can use the following configuration:
+```yaml
+apiVersion: placement.kubernetes-fleet.io/v1alpha1
+kind: ClusterResourceOverride
+metadata:
+  name: example-cro
+spec:
+  placement:
+    name: crp-example
+  clusterResourceSelectors:
+    - group: rbac.authorization.k8s.io
+      kind: ClusterRole
+      version: v1
+      name: secret-reader
+  policy:
+    overrideRules:
+      - clusterSelector:
+          clusterSelectorTerms:
+            - labelSelector:
+                matchLabels:
+                  env: prod
+        jsonPatchOverrides:
+          - op: add
+            path: /metadata/labels
+            value:
+              {"cluster-name":"${MEMBER-CLUSTER-NAME}"}
+```
+The `ClusterResourceOverride` object above will add a label `cluster-name` with the value of the `memberCluster` name to the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`.
+
 ## When To Trigger Rollout
 
 It will take the snapshot of each override change as a result of `ClusterResourceOverrideSnapshot` and
@@ -112,6 +154,8 @@ metadata:
   resourceVersion: "1436"
   uid: 32237804-7eb2-4d5f-9996-ff4d8ce778e7
 spec:
+  placement:
+    name: crp-example
   clusterResourceSelectors:
     - group: ""
       kind: Namespace
@@ -170,6 +214,8 @@ metadata:
   resourceVersion: "3859"
   uid: b4117925-bc3c-438d-a4f6-067bc4577364
 spec:
+  placement:
+    name: crp-example
   policy:
     overrideRules:
     - clusterSelector:

docs/howtos/cluster-resource-override.md

@@ -11,12 +11,17 @@ parameters, ensuring consistent management and enforcement of configurations acr
 
 ## API Components
 The ClusterResourceOverride API consists of the following components:
+- **Placement**: This specifies which placement the override is applied to.
 - **Cluster Resource Selectors**: These specify the set of cluster resources selected for overriding.
 - **Policy**: This specifies the policy to be applied to the selected resources.
 
 
 The following sections discuss these components in depth.
 
+## Placement
+
+To configure which placement the override is applied to, you can use the name of `ClusterResourcePlacement`.
+
 ## Cluster Resource Selectors
 A `ClusterResourceOverride` object may feature one or more cluster resource selectors, specifying which resources to select to be overridden.
 
@@ -61,7 +66,10 @@ resources on selected clusters.
 
 Each `OverrideRule` supports the following fields:
 - **Cluster Selector**: This specifies the set of clusters to which the override applies.
-- **JSON Patch Override**: This specifies the changes to be applied to the selected resources.
+- **Override Type**: This specifies the type of override to be applied. The default type is `JSONPatch`.
+  - `JSONPatch`: applies the JSON patch to the selected resources using [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902).
+  - `Delete`: deletes the selected resources on the target cluster.
+- **JSON Patch Override**: This specifies the changes to be applied to the selected resources when the override type is `JSONPatch`.
 
 To add an override rule, edit the `policy` field in the `ClusterResourceOverride` spec:
 ```yaml
@@ -70,6 +78,8 @@ kind: ClusterResourceOverride
 metadata:
   name: example-cro
 spec:
+  placement:
+    name: crp-example
   clusterResourceSelectors:
     - group: rbac.authorization.k8s.io
       kind: ClusterRole
@@ -87,7 +97,7 @@ spec:
             path: /rules/0/verbs/2
 ```
 The `ClusterResourceOverride` object above will remove the verb "list" in the `ClusterRole` named `secret-reader` on 
-clusters with the label `env: prod`.
+clusters with the label `env: prod` selected by the clusterResourcePlacement `crp-example`.
 
 > The ClusterResourceOverride mentioned above utilizes the cluster role displayed below:
 > ```
@@ -100,12 +110,42 @@ clusters with the label `env: prod`.
 > secrets    []                 []              [get watch list]
 >```
 
+To delete the `secret-reader` on the clusters with the label `env: test` selected by the clusterResourcePlacement `crp-example`, you can use the `Delete` override type.
+```yaml
+apiVersion: placement.kubernetes-fleet.io/v1alpha1
+kind: ClusterResourceOverride
+metadata:
+  name: example-cro
+spec:
+  placement:
+    name: crp-example
+  clusterResourceSelectors:
+    - group: rbac.authorization.k8s.io
+      kind: ClusterRole
+      version: v1
+      name: secret-reader
+  policy:
+    overrideRules:
+      - clusterSelector:
+          clusterSelectorTerms:
+            - labelSelector:
+                matchLabels:
+                  env: test
+        overrideType: Delete
+```
+
 ### Cluster Selector
 To specify the clusters to which the override applies, you can use the `clusterSelector` field in the `OverrideRule` spec.
 The `clusterSelector` field supports the following fields:
 - `clusterSelectorTerms`: A list of terms that are used to select clusters.
     * Each term in the list is used to select clusters based on the label selector.
 
+### Override Type
+To specify the type of override to be applied, you can use the overrideType field in the OverrideRule spec.
+The default value is `JSONPatch`. 
+- `JSONPatch`: applies the JSON patch to the selected resources using [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902).
+- `Delete`: deletes the selected resources on the target cluster.
+
 ### JSON Patch Override
 To specify the changes to be applied to the selected resources, you can use the jsonPatchOverrides field in the OverrideRule spec. 
 The jsonPatchOverrides field supports the following fields:
@@ -136,7 +176,38 @@ The jsonPatchOverrides field supports the following fields:
 
 - `value`: The value to be set.
     * If the `op` is `remove`, the value cannot be set.
+    * There is a list of reserved variables that will be replaced by the actual values:
+      * `${MEMBER-CLUSTER-NAME}`:  this will be replaced by the name of the `memberCluster` that represents this cluster.
 
+For example, to add a label to the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`,
+you can use the following configuration:
+```yaml
+apiVersion: placement.kubernetes-fleet.io/v1alpha1
+kind: ClusterResourceOverride
+metadata:
+  name: example-cro
+spec:
+  placement:
+    name: crp-example
+  clusterResourceSelectors:
+    - group: rbac.authorization.k8s.io
+      kind: ClusterRole
+      version: v1
+      name: secret-reader
+  policy:
+    overrideRules:
+      - clusterSelector:
+          clusterSelectorTerms:
+            - labelSelector:
+                matchLabels:
+                  env: prod
+        jsonPatchOverrides:
+          - op: add
+            path: /metadata/labels
+            value:
+              {"cluster-name":"${MEMBER-CLUSTER-NAME}"}
+```
+The `ClusterResourceOverride` object above will add a label `cluster-name` with the value of the `memberCluster` name to the `ClusterRole` named `secret-reader` on clusters with the label `env: prod`.
 
 ### Multiple Override Patches
 You may add multiple `JSONPatchOverride` to an `OverrideRule` to apply multiple changes to the selected cluster resources.
@@ -146,6 +217,8 @@ kind: ClusterResourceOverride
 metadata:
   name: example-cro
 spec:
+  placement:
+    name: crp-example
   clusterResourceSelectors:
     - group: rbac.authorization.k8s.io
       kind: ClusterRole
@@ -210,6 +283,9 @@ spec:
             - labelSelector:
                 matchLabels:
                   env: prod
+            - labelSelector:
+                matchLabels:
+                  env: test
 ```
 The `ClusterResourcePlacement` configuration outlined above will disperse resources across all clusters labeled with `env: prod`. 
 As the changes are implemented, the corresponding `ClusterResourceOverride` configurations will be applied to the 
@@ -245,7 +321,7 @@ Status:
      ...
 ```
 Each cluster maintains its own `Applicable Cluster Resource Overrides` which contain the cluster resource override snapshot
-if relevant. Additionally, individual status messages for each cluster indicates whether the override rules have been
+if relevant. Additionally, individual status messages for each cluster indicate whether the override rules have been
 effectively applied.
 
 The `ClusterResourcePlacementOverridden` condition indicates whether the resource override has been successfully applied
@@ -260,7 +336,7 @@ check resources in the selected clusters:
    `kubectl --context=<member-cluster-context>  get clusterrole secret-reader -o yaml`
 
 Upon inspecting the described ClusterRole object, it becomes apparent that the verbs "watch" and "list" have been 
-removed from the permissions list within the ClusterRole named "secret-reader" on the selected cluster.
+removed from the permissions list within the ClusterRole named "secret-reader" on the prod clusters.
    ```
     apiVersion: rbac.authorization.k8s.io/v1
     kind: ClusterRole
@@ -273,4 +349,5 @@ removed from the permissions list within the ClusterRole named "secret-reader" o
       - secrets
       verbs:
       - get
-```
+  ```
+Similarly, you can verify that this cluster role does not exist in the test clusters.

examples/test-cro1.yaml

@@ -3,6 +3,8 @@ kind: ClusterResourceOverride
 metadata:
   name: cro-1
 spec:
+  placement:
+    name: crp-example
   clusterResourceSelectors:
     - group: apiextensions.k8s.io
       kind: CustomResourceDefinition

examples/test-ro1.yaml

@@ -4,6 +4,8 @@ metadata:
   name: ro-1
   namespace: test-namespace
 spec:
+  placement:
+    name: crp-example
   resourceSelectors:
     -  group: ""
        kind: ConfigMap