README.md

Policy Generator

Overview

The Policy Generator constructs Open Cluster Management policies from Kubernetes YAML files provided through a PolicyGenerator Custom Resource. The Policy Generator is a binary compiled for use as a kustomize exec plugin.

• Installing the Policy Generator
  • Prerequisite
  • Install the binary
    • Download a released version
    • Using go install (available for v1.11.0 and higher)
    • Build from source
• Using the Policy Generator
  • As a Kustomize plugin
  • As a standalone binary
• Additional Policy Generator references

For more about Open Cluster Management and its Policy Framework:

• Open Cluster Management website
• Governance Policy Framework
• Policy Collection repository

Install the Policy Generator

Prerequisite

Create the plugin directory (optional if using the generator without Kustomize):

mkdir -p ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator

NOTE: The default directory for Kustomize plugins is ${HOME}/.config/kustomize/plugin/, which is used directly in this readme. You can change this by exporting KUSTOMIZE_PLUGIN_HOME to a different path and updating the root of the paths used in this document.

Install the binary

Download a released version

1. Download the precompiled plugin binary from the release of your choice.

2. Make the binary executable and move the binary to the plugin directory:

   • Linux:

     chmod +x linux-amd64-PolicyGenerator
     mv linux-amd64-PolicyGenerator ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator

   • MacOS:

     chmod +x darwin-amd64-PolicyGenerator
     mv darwin-amd64-PolicyGenerator ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator

Use go install (available for v1.11.0 and higher)

Set the GOBIN to the plugin directory and specify the desired version (this command uses latest):

GOBIN=${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator \
go install open-cluster-management.io/policy-generator-plugin/cmd/PolicyGenerator@latest

Build from source

make build

NOTE:

• This defaults to placing the binary in the Kustomize default plugin directory ${HOME}/.config/kustomize/plugin/. You can change this by exporting KUSTOMIZE_PLUGIN_HOME to a different path.
• Alternatively, you can run make build-binary to place the binary at the root of the repository and either use it directly from there or move it to the plugin directory to use with Kustomize.

Using the Policy Generator

As a Kustomize plugin

1. Create a kustomization.yaml file that points to PolicyGenerator manifest(s), with any additional desired patches or customizations (see examples/policyGenerator.yaml for an example):

   generators:
     - path/to/generator/file.yaml

   • To read more about the PolicyGenerator YAML structure, see the Policy Generator reference YAML

2. To use the plugin to generate policies, run the Kustomize build command from any directory with a kustomization.yaml file pointing to PolicyGenerator manifests:

   kustomize build --enable-alpha-plugins

NOTE: To enable Helm processing when passing a Kustomize directory into the generator, set the environment variable POLICY_GEN_ENABLE_HELM to "true". If the Helm directory is outside of the Kustomize path, you may set the environment variable POLICY_GEN_DISABLE_LOAD_RESTRICTORS to "true".

As a standalone binary

In order to bypass Kustomize and run the generator binary directly, change to the directory of PolicyGenerator manifest(s) and run the binary with the manifest(s) as the input arguments:

path/to/PolicyGenerator <path/to/file/1> ... <path/to/file/n>

For example:

make build-binary # This places the binary at the root of the repo, so this is optional if it was done previously
cd examples
../PolicyGenerator policyGenerator.yaml

NOTE:

• To print the trace in the case of an error, you can add the --debug flag to the arguments.
• To enable Helm processing when passing a Kustomize directory into the generator, set the environment variable POLICY_GEN_ENABLE_HELM to "true". If the Helm directory is outside of the Kustomize path, you may set the environment variable POLICY_GEN_DISABLE_LOAD_RESTRICTORS to "true".

Additional Policy Generator references

• Policy Generator reference YAML
• Policy Generator technical documentation