open-cluster-management.io/governance-policy-propagator@v0.13.0/README.md (about)

     1  [comment]: # " Copyright Contributors to the Open Cluster Management project "
     2  
     3  # Governance Policy Propagator [![KinD tests](https://github.com/open-cluster-management-io/governance-policy-propagator/actions/workflows/kind.yml/badge.svg?branch=main&event=push)](https://github.com/open-cluster-management-io/governance-policy-propagator/actions/workflows/kind.yml)[![License](https://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
     4  
     5  ## Description
     6  
     7  The governance policy propagator is a controller that watches `Policies`, `PlacementBindings`, and `PlacementRules`. It
     8  manages replicated Policies in cluster namespaces based on the PlacementBindings and PlacementRules, and it updates the
     9  status on Policies to show aggregated cluster compliance results.
    10  
    11  The operator watches for changes to trigger a reconcile:
    12  
    13  1. Changes to Policies in non-cluster namespaces trigger a self reconcile.
    14  2. Changes to Policies in cluster namespaces trigger a root Policy reconcile.
    15  3. Changes to PlacementBindings trigger reconciles on the subject Policies.
    16  4. Changes to PlacementRules trigger reconciles on subject Policies.
    17  
    18  Every reconcile does the following:
    19  
    20  1. Creates/updates/deletes replicated policies in cluster namespaces based on PlacementBinding/PlacementRule results.
    21  2. Creates/updates/deletes the policy status to show aggregated cluster compliance results.
    22  
    23  ## Getting started
    24  
    25  Go to the
    26  [Contributing guide](https://github.com/open-cluster-management-io/community/blob/main/sig-policy/contribution-guidelines.md)
    27  to learn how to get involved.
    28  
    29  Check the [Security guide](SECURITY.md) if you need to report a security issue.
    30  
    31  ### Changes to the deploy YAML files
    32  
    33  The YAML files in the deploy directory are autogenerated by Kubebuilder and Kustomize. After code changes that affect
    34  the YAML files, the YAML files can be regenerated with `make generate-operator-yaml`.
    35  
    36  ### Build and deploy locally
    37  
    38  You will need [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) installed.
    39  
    40  1. Create the Kind cluster
    41     ```bash
    42     make kind-bootstrap-cluster-dev
    43     ```
    44  2. Start the propagator:
    45     - Run in a pod on the cluster:
    46       ```bash
    47       make build-images
    48       make kind-deploy-controller-dev
    49       ```
    50     - Run locally:
    51       ```bash
    52       make run
    53       ```
    54  
    55  ### Running tests
    56  
    57  ```
    58  make test-dependencies
    59  make test
    60  
    61  make e2e-dependencies
    62  make e2e-test
    63  ```
    64  
    65  ### How to run webhook locally
    66  
    67  ```bash
    68  --enable-webhooks=true
    69  ```
    70  
    71  > **Limit**: If you want to run the webhook locally, you need to generate certificates and place them in `/tmp/k8s-webhook-server/serving-certs/tls.{crt,key}`. If you’re not running a local API server, you’ll also need to figure out how to proxy traffic from the remote cluster to your local webhook server. For this reason, Kubebuilder generally recommends disabling webhooks when doing your local code-run-test cycle. To disable it, please supply the `--enable-webhooks=false` argument when running the controller.
    72  > For more information, visit https://book.kubebuilder.io/cronjob-tutorial/running.html
    73  
    74  ### Clean up
    75  
    76  ```
    77  make kind-delete-cluster
    78  ```
    79  
    80  ### Updating Deployment resources
    81  
    82  Some of the deployment resources are generated by kubebuilder - the crds are generated into `./deploy/crds` and the rbac
    83  details from kubebuilder comments are compiled into `./deploy/rbac/role.yaml`. Other details are managed independently -
    84  in particular, the details in `./deploy/manager/manager.yaml`. When any of those details need to be changed, the main
    85  deployment yaml `./deploy/operator.yaml` must be regenerated through the `make generate-operator-yaml` target. The
    86  `./deploy/operator.yaml` SHOULD NOT be manually updated.
    87  
    88  ## Running the Compliance Events API
    89  
    90  Create the KinD cluster and install Postgres with the following commands:
    91  
    92  ```bash
    93  make kind-bootstrap-cluster-dev
    94  ```
    95  
    96  You can connect to the Postgres server with the following command:
    97  
    98  ```bash
    99  psql "host=localhost dbname=ocm-compliance-history user=grc password=grc"
   100  ```
   101  
   102  Run the Governance Policy Propagator with the following command:
   103  
   104  ```bash
   105  WATCH_NAMESPACE="" WATCH_NAMESPACE_COMPLIANCE_EVENTS_STORE="open-cluster-management" go run main.go --leader-elect=false  --enable-webhooks=false
   106  ```
   107  
   108  ## References
   109  
   110  - The `governance-policy-propagator` is part of the `open-cluster-management` community. For more information, visit:
   111    [open-cluster-management.io](https://open-cluster-management.io).
   112