diff --git a/README.md b/README.md index 14392689..aa0b8f30 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,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/) -