Add example YAML and field descriptions

The content and format here is based off of the great example of the
cert-policy-controller. The example is from the `policy-pod` in the
policy-collection.

The fields are from configurationpolicy_types.go, and I marked them as
required or optional depending on if they seemed necessary for the
policy to work as expected; most of them had `omitempty` in their go
struct tags, so they aren't *technically* required.

Signed-off-by: Justin Kulikauskas <justin.kulikauskas@gmail.com>

README.md

@@ -1,18 +1,59 @@
 [comment]: # ( Copyright Contributors to the Open Cluster Management project )
 
-# Configuration Policy Controller [![KinD tests](https://github.com/open-cluster-management/config-policy-controller/actions/workflows/kind.yml/badge.svg?branch=main&event=push)](https://github.com/open-cluster-management/config-policy-controller/actions/workflows/kind.yml)
+# Configuration Policy Controller
+
 Red Hat Advanced Cluster Management - Governance - Configuration Policy Controller
 
-## How it works
+[![Build](https://img.shields.io/badge/build-Prow-informational)](https://prow.ci.openshift.org/?repo=open-cluster-management%2Fconfig-policy-controller)
+[![KinD tests](https://github.com/open-cluster-management/config-policy-controller/actions/workflows/kind.yml/badge.svg?branch=main&event=push)](https://github.com/open-cluster-management/config-policy-controller/actions/workflows/kind.yml)
+[![License](https://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
+
+## Description
 
-The Configuration Policy Controller watches for the following triggers to execute a reconcile:
+The Configuration Policy Controller watches `ConfigurationPolicies`, and checks if the specified objects are present in the cluster. It records compliancy details in the `status` of each ConfigurationPolicy, and as Kubernetes Events. If set to `enforce` the configuration, then the controller will attempt to create, update, or delete objects on the cluster as necessary to match the specified state. The controller can be run as a stand-alone program or as an integrated part of governing risk with Red Hat Advanced Cluster Management for Kubernetes.
+
+This is an example spec of a `ConfigurationPolicy` object:
+```yaml
+apiVersion: policy.open-cluster-management.io/v1
+kind: ConfigurationPolicy
+metadata:
+ name: policy-pod-example
+spec:
+ remediationAction: enforce
+ severity: low
+ namespaceSelector:
+ exclude: ["kube-*"]
+ include: ["default"]
+ object-templates:
+ - complianceType: musthave
+ objectDefinition:
+ apiVersion: v1
+ kind: Pod
+ metadata:
+ name: sample-nginx-pod
+ spec:
+ containers:
+ - image: nginx:1.18.0
+ name: nginx
+ ports:
+ - containerPort: 80
+```
 
-1. ConfigurationPolicy changes in all watched namespaces on the hub cluster
+The `ConfigurationPolicy` spec includes the following fields:
 
-Every reconcile the controller will:
+| Field | Description |
+| ---- | ---- |
+| severity | Optional: `low`, `medium`, or `high`. |
+| remediationAction | Required: `inform` or `enforce`. Determines what actions the controller will take if the actual state of the object-templates does not match what is desired. |
+| namespaceSelector | Required: an object with `include` and `exclude` lists, specifying where the controller will look for the actual state of the object-templates. |
+| object-templates | Required: A list of Kubernetes objects that will be checked on the cluster. |
 
-1. Create/update/delete the replicated policy on the managed cluster in the cluster namespace
-2. Handle the object template specified in the ConfigurationPolicy and create an object and/or status update depending on the details of the object template
+Additionally, each item in the `object-templates` includes these fields:
+
+| Field | Description |
+| ---- | ---- |
+| complianceType | Required: `musthave`, `mustnothave` or `mustonlyhave`. Determines how to decide if the cluster is compliant with the policy. |
+| objectDefinition | Required: A Kubernetes object which must (or must not) match an object on the cluster in order to comply with this policy. |
 
 ## Run
 
@@ -21,6 +62,8 @@ To run the controller locally, point your CLI to a running cluster and then run:
 export WATCH_NAMESPACE=cluster_namespace_on_hub
 go run cmd/manager/main.go
 ```
-<!---
-Date: 9/09/2020
--->
+
+## References
+
+- The `config-policy-controller` is part of the `open-cluster-management` community. For more information, visit: [open-cluster-management.io](https://open-cluster-management.io).
+- Check the [Security guide](SECURITY.md) if you need to report a security issue.