From 367fc2b6cc71d756c9a933b87441e26a38a542b7 Mon Sep 17 00:00:00 2001 From: yiraeChristineKim Date: Fri, 12 Jul 2024 10:28:56 -0400 Subject: [PATCH] Add documentation about transition from placementRule to placement Ref: https://issues.redhat.com/browse/ACM-12698 Signed-off-by: yiraeChristineKim --- README.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 112 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 14392689..e9362cc5 100644 --- a/README.md +++ b/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 ` instead. From within this directory in terminal, run `cd deploy` to access the deployment directory, then run `bash ./deploy.sh -u -p -n `. (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/) -