Configuration Policy Controller

Open Cluster Management - Configuration Policy Controller

Description

With the Configuration Policy Controller, you can create ConfigurationPolicies to check if the specified objects are present in the cluster. The controller records compliancy details in the status of each ConfigurationPolicy, and as Kubernetes Events. If the policy is 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 the Open Cluster Management project.

The ConfigurationPolicy spec includes the following fields:

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	Optional: an object with `include` and `exclude` lists, specifying where the controller will look for the actual state of the object-templates, if the object is namespaced and not already specified in the object.
object-templates	Required: A list of Kubernetes objects that will be checked on the cluster.

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.

Following is an example spec of a ConfigurationPolicy object:

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

Templating

Configuration Policies supports inclusion of Golang text templates in ObjectDefinitions. These templates are resolved at runtime on the target cluster using configuration local to that cluster giving the user the ability to define policies customized to the target cluster. Following custom template functions are available to allow referencing kube-resources on the target cluster.

fromSecret - returns the value of the specified data key in the Secret resource
fromConfigMap - returns the values of the specified data key in the ConfigMap resource.
fromClusterClaim - returns the value of Spec.Value field in the ClusterClaim resource.
lookup - a generic lookup function to retreive any kube resource.

Following is an example spec of a ConfigurationPolicy object with templates :

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-templates
  namespace: test-templates
spec:
  namespaceSelector:
    exclude:
    - kube-*
    include:
    - default
  object-templates:
  - complianceType: musthave
    objectDefinition:
      kind: ConfigMap
      apiVersion: v1
      metadata:
        name: demo-templates
        namespace: test
      data:
        # Configuration values can be set as key-value properties
        app-name: sampleApp
        app-description: "this is a sample app"
        app-key: '{{ fromSecret "test" "testappkeys" "app-key"  | base64dec }}'
        log-file: '{{ fromConfigMap "test" "logs-config" "log-file" }}'
        appmetrics-url: |
          http://{{ (lookup "v1" "Service" "test" "appmetrics").spec.clusterIP }}:8080
        app-version: version: '{{ fromClusterClaim "version.openshift.io" }}'
  remediationAction: enforce
  severity: low

Getting started

Go to the Contributing guide to learn how to get involved.

Steps for development

Build code
```
make build
```
Run controller locally against the Kubernetes cluster currently configured with kubectl
```
export WATCH_NAMESPACE=<namespace>
make run
```
(WATCH_NAMESPACE can be any namespace on the cluster that you want the controller to monitor for policies.)

Steps for deployment

Build container image

make build-images

The image registry, name, and tag used in the image build, are configurable with:

export REGISTRY=''  # (defaults to 'quay.io/stolostron')
export IMG=''       # (defaults to the repository name)
export TAG=''       # (defaults to 'latest')

Deploy controller to a cluster

The controller is deployed to a namespace defined in CONTROLLER_NAMESPACE and monitors the namepace defined in WATCH_NAMESPACE for ConfigurationPolicy resources.
1. Create the deployment namespaces
```
make create-ns
```
  The deployment namespaces are configurable with:
```
export CONTROLLER_NAMESPACE=''  # (defaults to 'open-cluster-management-agent-addon')
export WATCH_NAMESPACE=''       # (defaults to 'managed')
```
2. Deploy the controller and related resources
```
make deploy
```
NOTE: Please be aware of the community's deployment images special note.

Steps for test

Code linting
```
make lint
```
Unit tests
- Install prerequisites
```
make test-dependencies
```
- Run unit tests
```
make test
```
E2E tests
1. Prerequisites:
  - docker
  - kind
2. Start KinD cluster (make sure Docker is running first)
```
make kind-bootstrap-cluster-dev
```
3. Start the controller locally (see Steps for development)
4. Run E2E tests:
```
export WATCH_NAMESPACE=managed
make e2e-test
```

References

The config-policy-controller is part of the open-cluster-management community. For more information, visit: open-cluster-management.io.
Check the Security guide if you need to report a security issue.

mprahl/config-policy-controller