github.com/dhaiducek/policy-generator-plugin@v1.99.99/README.md (about)

     1  # Policy Generator
     2  
     3  ## Overview
     4  
     5  The Policy Generator constructs Open Cluster Management policies from Kubernetes YAML files provided through a
     6  PolicyGenerator Custom Resource. The Policy Generator is a binary compiled for use as a
     7  [kustomize](https://kustomize.io/) exec plugin.
     8  
     9  - [Installing the Policy Generator](#installing-the-policy-generator)
    10    - [Prerequisite](#prerequisite)
    11    - [Install the binary](#install-the-binary)
    12      - [Download a released version](#download-a-released-version)
    13      - [Using `go install` (available for `v1.11.0` and higher)](#using-go-install-available-for-v1110-and-higher)
    14      - [Build from source](#build-from-source)
    15  - [Using the Policy Generator](#using-the-policy-generator)
    16    - [As a Kustomize plugin](#as-a-kustomize-plugin)
    17    - [As a standalone binary](#as-a-standalone-binary)
    18  - [Additional Policy Generator references](#additional-policy-generator-references)
    19  
    20  For more about Open Cluster Management and its Policy Framework:
    21  
    22  - [Open Cluster Management website](https://open-cluster-management.io/)
    23  - [Governance Policy Framework](https://open-cluster-management.io/getting-started/integration/policy-framework/)
    24  - [Policy Collection repository](https://github.com/open-cluster-management-io/policy-collection)
    25  
    26  ## Install the Policy Generator
    27  
    28  ### Prerequisite
    29  
    30  Create the plugin directory (optional if using the generator without Kustomize):
    31  
    32  ```bash
    33  mkdir -p ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator
    34  ```
    35  
    36  **NOTE:** The default directory for Kustomize plugins is `${HOME}/.config/kustomize/plugin/`, which is used directly in
    37  this readme. You can change this by exporting `KUSTOMIZE_PLUGIN_HOME` to a different path and updating the root of the
    38  paths used in this document.
    39  
    40  ### Install the binary
    41  
    42  #### Download a released version
    43  
    44  1. Download the precompiled plugin binary from the
    45     [release](https://github.com/open-cluster-management-io/policy-generator-plugin/releases) of your choice.
    46  
    47  2. Make the binary executable and move the binary to the plugin directory:
    48  
    49     - Linux:
    50  
    51       ```bash
    52       chmod +x linux-amd64-PolicyGenerator
    53       mv linux-amd64-PolicyGenerator ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator
    54       ```
    55  
    56     - MacOS:
    57       ```bash
    58       chmod +x darwin-amd64-PolicyGenerator
    59       mv darwin-amd64-PolicyGenerator ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator
    60       ```
    61  
    62  #### Use `go install` (available for `v1.11.0` and higher)
    63  
    64  Set the `GOBIN` to the plugin directory and specify the desired version (this command uses `latest`):
    65  
    66  ```bash
    67  GOBIN=${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator \
    68  go install github.com/dhaiducek/policy-generator-plugin/cmd/PolicyGenerator@latest
    69  ```
    70  
    71  #### Build from source
    72  
    73  ```bash
    74  make build
    75  ```
    76  
    77  **NOTE:**
    78  
    79  - This defaults to placing the binary in the Kustomize default plugin directory `${HOME}/.config/kustomize/plugin/`. You
    80    can change this by exporting `KUSTOMIZE_PLUGIN_HOME` to a different path.
    81  - Alternatively, you can run `make build-binary` to place the binary at the root of the repository and either use it
    82    directly from there or move it to the plugin directory to use with Kustomize.
    83  
    84  ## Using the Policy Generator
    85  
    86  ### As a Kustomize plugin
    87  
    88  1. Create a `kustomization.yaml` file that points to `PolicyGenerator` manifest(s), with any additional desired patches
    89     or customizations (see [`examples/policyGenerator.yaml`](./examples/policyGenerator.yaml) for an example):
    90  
    91     ```yaml
    92     generators:
    93       - path/to/generator/file.yaml
    94     ```
    95  
    96     - To read more about the `PolicyGenerator` YAML structure, see the
    97       [Policy Generator reference YAML](./docs/policygenerator-reference.yaml)
    98  
    99  2. To use the plugin to generate policies, run the Kustomize build command from any directory with a
   100     `kustomization.yaml` file pointing to `PolicyGenerator` manifests:
   101     ```bash
   102     kustomize build --enable-alpha-plugins
   103     ```
   104  
   105  ### As a standalone binary
   106  
   107  In order to bypass Kustomize and run the generator binary directly, change to the directory of PolicyGenerator
   108  manifest(s) and run the binary with the manifest(s) as the input arguments:
   109  
   110  ```bash
   111  path/to/PolicyGenerator <path/to/file/1> ... <path/to/file/n>
   112  ```
   113  
   114  For example:
   115  
   116  ```bash
   117  make build-binary # This places the binary at the root of the repo, so this is optional if it was done previously
   118  cd examples
   119  ../PolicyGenerator policyGenerator.yaml
   120  ```
   121  
   122  **NOTE:** To print the trace in the case of an error, you can add the `--debug` flag to the arguments.
   123  
   124  ## Additional Policy Generator references
   125  
   126  - [Policy Generator reference YAML](./docs/policygenerator-reference.yaml)
   127  - [Policy Generator technical documentation](./docs/policygenerator.md)