Add documentation about transition from placementRule to placement

Ref: https://issues.redhat.com/browse/ACM-12698
Signed-off-by: yiraeChristineKim <yikim@redhat.com>

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,101 @@ 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)
+
+### Background
+
+As PlacementRule has been **deprecated**, it's recommended to migrate towards using Placement for defining resource placement strategies within multi-cluster environments. This transition aims to adopt a more modern and versatile format offered by Placement.
+
+### Objectives of Conversion
+
+The goal of converting from PlacementRule to Placement is to update your configuration from an older, deprecated format to a newer, more flexible one. This ensures alignment with current best practices and enables leveraging the enhanced capabilities provided by Placement.
+
+### 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.
+
+The policies are applied to all available managed clusters with the environment set to "dev." To apply the policies to a different set of clusters, update the PlacementRule.spec.clusterSelector.matchExpressions section in the policies.
+
+As new clusters meeting the specified criteria are added, the policies will be applied to them automatically.
+
+### Prerequisite
+
+- [ManagedClusterSet](https://open-cluster-management.io/concepts/managedclusterset/) and [ManagedClusterSetBinding](https://open-cluster-management.io/concepts/managedclusterset)
+- `Policy`(The `namespace` in the `policy` should be bound to `ManagedClusterSetBinding`)
+- `PlacementBinding` and `PlacementRule`
+
+```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`
+
+Create the `Placement` manifest as shown below. This `Placement` manifest replaces the `PlacementRule`. Ensure that the `namespace` specified (`example-ns`) matches the `namespace` used in `ManagedClusterSetBinding`. Copy `matchExpressions` from the `PlacementRule` and paste them into `spec.predicates.requiredClusterSelector.labelSelector`. 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.
+
+```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 +205,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/)
-