diff --git a/README.md b/README.md index 9d612778..9a2e5e23 100644 --- a/README.md +++ b/README.md @@ -28,15 +28,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/) -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. +[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 @@ -68,7 +68,8 @@ subjects: name: my-username ``` -After updating the `ClusterRoleBinding`, you need to delete the subscription and deploy the subscription again. +After updating the `ClusterRoleBinding`, you need to delete the subscription and deploy the +subscription again. ### Policy Generator @@ -85,6 +86,132 @@ 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) +## Distributing Policies to Managed Clusters + +Distributing a `Policy` to a managed cluster requires four parts, all of which must be in the same +namespace: + +- [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/): Dynamically selects a set of + `ManagedClusters` in one or multiple `ManagedClusterSet`s. + +- [ManagedClusterSetBinding](https://open-cluster-management.io/concepts/managedclusterset/): Binds + a `ManagedClusterSet` to a namespace, making this group of managed clusters available for + selection by `Placement`. + +When the `Policy` is bound to a `Placement` using a `PlacementBinding`, the `Policy` is distributed +to the managed clusters and the `Policy` status will report on each cluster returned by the bound +`Placement`. + +### Using `Placement` with `Policies` + +See the [Placement documentation](https://open-cluster-management.io/concepts/placement/) for +additional details on selecting managed clusters using `Placement`. + +- **NOTE:** `PlacementRule` is **deprecated**. See the + [migration section](#transitioning-from-placementruledeprecated-to-placement) for detail on + migrating to `Placement`. + +To use `Placement` to distribute `Policies`, bind the `Policy` to the `Placement` using a +`PlacementBinding`. All of the objects must be in the same namespace. View the following sample +`Placement` and `PlacementBinding` bound to a `Policy` named `policy-example` in the namespace +`example-ns`. The `Placement` selects managed clusters that have the label `environment: dev`: + +```yaml +apiVersion: cluster.open-cluster-management.io/v1beta1 +kind: Placement +metadata: + name: placement-policy-example + namespace: example-ns +spec: + predicates: + - requiredClusterSelector: + labelSelector: + matchExpressions: + - { key: environment, operator: In, values: ["dev"] } +--- +apiVersion: policy.open-cluster-management.io/v1 +kind: PlacementBinding +metadata: + name: binding-policy-example + namespace: example-ns +placementRef: + name: placement-policy-example + kind: Placement + apiGroup: cluster.open-cluster-management.io +subjects: + - name: policy-example + kind: Policy + apiGroup: policy.open-cluster-management.io +``` + +### Transitioning from `PlacementRule`(deprecated) to `Placement` + +`PlacementRule` had unrestricted access to selecting managed clusters. However, `Placement` requires +binding managed clusters to the `Policy` namespace in order for `Policies` to be distributed to +those managed clusters, bringing an additional layer of control to system administrators. View the +following steps on migrating from `PlacementRule` to `Placement`: + +1. The desired managed clusters must be contained in a `ManagedClusterSet`. See the + [ManagedClusterSet documentation](https://open-cluster-management.io/concepts/managedclusterset/) + to read more, including the default sets that are available that include all managed clusters + that would replicate `PlacementRule` behavior. + +2. Create a `ManagedClusterSetBinding` to bind the `ManagedClusterSet` to the namespace where you + are authoring policies. See the + [ManagedClusterSet documentation](https://open-cluster-management.io/concepts/managedclusterset/). + +3. Create the `Placement` manifest to replace the `PlacementRule`. To do this, take the selector + `spec.clusterSelector` from the `PlacementRule` and put it into + `spec.predicates.requiredClusterSelector.labelSelector`. For example, to select managed clusters + with the label `environment: dev`: + ```yaml + apiVersion: cluster.open-cluster-management.io/v1beta1 + kind: Placement + metadata: + name: placement-policy-example + namespace: example-ns // Ensure this namespace matches the ManagedClusterSetBinding + spec: + predicates: + - requiredClusterSelector: + labelSelector: + matchExpressions: // From PlacementRule + - {key: environment, operator: In, values: ["dev"]} + ``` + + See the [Placement documentation](https://open-cluster-management.io/concepts/placement/) for + additional details on selecting managed clusters using `Placement`. + +4. Identify any `PlacementBinding` resources that reference a `PlacementRule`. Update the + `PlacementBinding` to reference the new `Placement`: + + - Change the `placementRef.kind` to `Placement` + - Update the `placementRef.apiGroup` to `cluster.open-cluster-management.io` to reflect the + `Placement`'s API version + + View the following sample `PlacementBinding` that references a `Placement`: + + ```yaml + apiVersion: policy.open-cluster-management.io/v1 + kind: PlacementBinding + metadata: + name: binding-policy-example + placementRef: + apiGroup: cluster.open-cluster-management.io // Set to cluster.open-cluster-management.io + kind: Placement // Set to Placement + name: placement-policy-example + subjects: + - name: policy-example + kind: Policy + apiGroup: policy.open-cluster-management.io + ``` + ## Community, discussion, contribution, and support Check the [Contributing policies](CONTRIBUTING.md) document for guidelines on how to contribute to