Add documentation about transition from placementRule to placement

Ref: https://issues.redhat.com/browse/ACM-12698
Signed-off-by: yiraeChristineKim <[email protected]>

README.md

@@ -9,21 +9,21 @@ This repository hosts policies for Open Cluster Management. You can deploy these
 that is available as an addon. Policies are organized in two ways:
 
 1. By support expectations which are detailed below.
-2. By [NIST Special Publication 800-53](https://nvd.nist.gov/800-53). 
+2. By [NIST Special Publication 800-53](https://nvd.nist.gov/800-53).
 
 The following folders are used to separate policies by the support expectations:
 
 - [stable](stable) -- Policies in the `stable` folder are contributions that are being supported by
   the Open Cluster Management Policy SIG.
 - [3rd-party](3rd-party) -- Policies in the `3rd-party` folder are contributions that are being
-  supported, but not by the Open Cluster Management Policy SIG.  See the details of the policy to understand
+  supported, but not by the Open Cluster Management Policy SIG. See the details of the policy to understand
   the support being provided.
 - [community](community) -- Policies in the `community` folder are contributed from the open source
-  community.  Contributions should start in the community.
+  community. Contributions should start in the community.
 
 In addition to policy contributions, there is the option to contribute groups of policies as a set.
 This is known as `PolicySets` and these contributions are made in directories organized as
-`PolicyGenerator` projects.  The folder containing these contributions is located here:
+`PolicyGenerator` projects. The folder containing these contributions is located here:
 [`PolicySet` projects](https://github.com/open-cluster-management-io/policy-collection/tree/main/policygenerator/policy-sets).
 
 ## Using GitOps to deploy policies to a cluster
@@ -42,15 +42,15 @@ namespace something else, you can run `kubectl create ns <custom ns>` instead.
 
 From within this directory in terminal, run `cd deploy` to access the deployment directory, then run
 `bash ./deploy.sh -u <url> -p <path> -n <namespace>`. (Details on all of the parameters for this
-command can be viewed in its [README](deploy/README.md).) This script assumes you have enabled 
+command can be viewed in its [README](deploy/README.md).) This script assumes you have enabled
 Application lifecycle management as an addon in your Open Cluster Management installation. See
-[Application lifecycle management](https://open-cluster-management.io/getting-started/integration/app-lifecycle/) 
+[Application lifecycle management](https://open-cluster-management.io/getting-started/integration/app-lifecycle/)
 for details on installing the Application addon.
 **Note**: If you are using ArgoCD for gitops, a similar script [argoDeploy.sh](deploy/argoDeploy.sh) is provided that does
 not require the Application Lifecycle addon.
 
 The policies are applied to all managed clusters that are available, and have the `environment` set
-to `dev`. If policies need to be applied to another set of clusters, update the 
+to `dev`. If policies need to be applied to another set of clusters, update the
 `PlacementRule.spec.clusterSelector.matchExpressions` section in the policies.
 
 **Note**: As new clusters are added that fit the criteria previously mentioned, the policies are
@@ -99,6 +99,111 @@ For additional information about the Policy Generator:
 - [Policy Generator reference YAML](https://github.com/stolostron/policy-generator-plugin/blob/main/docs/policygenerator-reference.yaml)
 - [Policy Generator examples](policygenerator)
 
+## Using PlacementRule to distribute policies (Deprecated)
+
+### Distributing Policies to Managed Clusters
+
+[Policy](https://open-cluster-management.io/concepts/policy/) is a grouping mechanism for Policy Templates and is the smallest deployable unit on the hub cluster. Embedded Policy Templates are distributed to applicable managed clusters and acted upon by the appropriate `policy controller`.
+
+[PlacementBinding](https://open-cluster-management.io/concepts/policy/#placementbinding) binds a Placement to a `Policy` or `PolicySet`.
+
+[Placement](https://open-cluster-management.io/concepts/placement/) concept is used to dynamically select a set of `managedClusters` in one or multiple `ManagedClusterSet` so that higher level users can either replicate Kubernetes resources to the member clusters or run their advanced workload i.e. multi-cluster scheduling.
+
+When the `Policy` is bound to a `Placement` using a `PlacementBinding`, the Policy status will report on each cluster that matches the bound Placement
+
+### Using `Placement` with `Policies`
+
+To use Placement for policies without having previously used PlacementRule, please refer to this [guide](https://open-cluster-management.io/concepts/placement/)
+
+### Deprecated PlacementRule details
+
+> **_NOTE:_** `PlacementRule` is now **deprecated**. We recommend switching to `Placement` instead.
+
+Previously, policies defined the PlacementRule and PlacementBinding resources, configuring the policy to be distributed to all managed clusters with the environment label set to "dev." To apply your policies to managed clusters, use the information provided in this section, as PlacementRule and PlacementBinding resources are no longer included with the policies in this repository.
+
+As new clusters meeting the specified criteria are added, the policies will be applied to them automatically.
+
+**Example of `PlacementRule` and `PlacementBinding`**:
+
+```yaml
+apiVersion: policy.open-cluster-management.io/v1
+kind: PlacementBinding
+metadata:
+  name: binding-policy-example
+placementRef:
+  name: placement-policy-example
+  kind: PlacementRule
+  apiGroup: apps.open-cluster-management.io
+subjects:
+  - name: policy-example
+    kind: Policy
+    apiGroup: policy.open-cluster-management.io
+---
+apiVersion: apps.open-cluster-management.io/v1
+kind: PlacementRule
+metadata:
+  name: placement-policy-example
+spec:
+  clusterSelector:
+    matchExpressions:
+      - { key: environment, operator: In, values: ["dev"] }
+```
+
+### Transitioning from `PlacementRule`(deprecated) to `Placement`
+
+#### Step 1:
+
+Make sure your clusters are organized as desired into `ManagedClusterSet`. [See link](https://open-cluster-management.io/concepts/managedclusterset/)
+
+#### Step 2:
+
+Make sure you have a `ManagedClusterSetBinding` for the `namespace` where you are authoring policies. [See link](https://open-cluster-management.io/concepts/managedclusterset)
+
+> **Caution**: The `namespace` under `ManagedClusterSetBinding` should match the namespace in your `Policy`
+
+#### Step 3:
+
+Identify any PlacementBinding resources that reference a PlacementRule. For each of those PlacementBindings, proceed with the following steps.
+
+#### Step 4:
+
+Create the `Placement` manifest as shown below. This `Placement` manifest replaces the `PlacementRule`. Ensure that the `namespace` in `Placement` matches the `namespace` used in `ManagedClusterSetBinding`. Copy `matchExpressions` from the `PlacementRule` and paste them into `spec.predicates.requiredClusterSelector.labelSelector`.
+
+#### Step 5:
+
+Update the `PlacementBinding` to reference the new `Placement`. Change the `placementRef.kind` to `Placement` and update the `placementRef.apiGroup` to `cluster.open-cluster-management.io` to reflect the `Placement`'s API version.
+
+Expected Result:
+
+```yaml
+apiVersion: cluster.open-cluster-management.io/v1beta1
+kind: Placement
+metadata:
+  name: placement-policy-example
+  namespace: example-ns // Please ensure that this namespace matches one in ManagedClusterSetBinding
+spec:
+  predicates:
+  - requiredClusterSelector:
+      labelSelector:
+        matchExpressions: // From PlacementRule
+         - {key: environment, operator: In, values: ["dev"]}
+---
+apiVersion: policy.open-cluster-management.io/v1
+kind: PlacementBinding
+metadata:
+  name: binding-policy-example
+placementRef:
+  name: placement-policy-example
+  kind: Placement // Set here to Placement
+  apiGroup: cluster.open-cluster-management.io // Set cluster.open-cluster-management.io
+subjects:
+  - name: policy-example
+    kind: Policy
+    apiGroup: policy.open-cluster-management.io
+```
+
+This explanation provides a clear transition from using `PlacementRule` to `Placement`, ensuring compatibility and proper configuration alignment with Open Cluster Management principles.
+
 ## Community, discussion, contribution, and support
 
 Check the [Contributing policies](CONTRIBUTING.md) document for guidelines on how to contribute to
@@ -110,4 +215,3 @@ the repository.
 are implemented in the product governance framework.
 
 - [Open Cluster Management Quick Start](https://https://open-cluster-management.io/getting-started/quick-start/)
-